blob: 760e8a85f003567b97c4f357f58db0ef96206a14 [file] [log] [blame] [view]
Alexander Afanasyev37a05f62014-05-09 18:55:21 -07001Starting NFD on Linux with upstart
2==================================
3
4Some Linux distributions, such as Ubuntu, use [upstart](http://upstart.ubuntu.com/) as a
5standard mechanism to start system daemons, monitor their health, and restart
6when they die.
7
8Initial setup
9-------------
10
11Edit `nfd.conf` and `nrd.conf` correcting paths for `nfd` and `nfd` binaries,
12configuration file, and log files.
13
14 # Copy upstart config file for nfd (forwarding daemon)
15 sudo cp nfd.conf /etc/init/
16
17 # Copy upstart config file for nrd (RIB management daemon)
18 sudo cp nrd.conf /etc/init/
19
20 # Copy upstart config file for nfd-watcher (will restart NFD when network change detected)
21 sudo cp nfd-watcher.conf /etc/init/
22
23### Assumptions in the default scripts
24
25* `nfd` and `nrd` are installed into `/usr/local/bin`
26* Configuration file is `/usr/local/etc/ndn/nfd.conf`
27* `nfd` will be run as root
28* `nrd` will be run as user `ndn` and group `ndn`
29* Log files will be written to `/usr/local/var/log/ndn` folder, which is owned by user `ndn`
30* Whenever network connectivity changes, both `nfd` and `nrd` are restarted
31
32### Creating users
33
34If `ndn` user and group does not exists, they need to be manually created.
35
36 # Create group `ndn`
37 addgroup --system ndn
38
39 # Create user `ndn`
40 sudo adduser --system \
41 --disabled-login \
42 --ingroup ndn \
43 --home /nonexistent \
44 --gecos "NDN User" \
45 --shell /bin/false \
46 ndn
47
48
49### Creating folders
50
51Folder `/usr/local/var/log/ndn` should be created and assigned proper user and group:
52
53 sudo mkdir -p /usr/local/var/log/ndn
54 sudo chown -R ndn:ndn /usr/local/var/log/ndn
55
56`HOME` directories for `nfd` and `nrd` should be created prior to starting. This is
57necessary to manage unique security credentials for the deamons.
58
59 # Create HOME and generate self-signed NDN certificate for nfd
60 sudo mkdir -p /usr/local/var/lib/ndn/nfd/.ndn
61 sudo HOME=/usr/local/var/lib/ndn/nfd ndnsec-keygen /localhost/daemons/nfd | \
62 sudo HOME=/usr/local/var/lib/ndn/nfd ndnsec-install-cert -
63
64 # Create HOME and generate self-signed NDN certificate for nrd
65 sudo mkdir -p /usr/local/var/lib/ndn/nrd/.ndn
66 sudo chown -R ndn:ndn /usr/local/var/lib/ndn/nrd
67 sudo -u ndn -g ndn HOME=/usr/local/var/lib/ndn/nrd ndnsec-keygen /localhost/daemons/nrd | \
68 sudo -u ndn -g ndn HOME=/usr/local/var/lib/ndn/nrd ndnsec-install-cert -
69
70### Configuring NFD's security
71
72NFD sample configuration allows anybody to create faces, add nexthops to FIB, and set
73strategy choice for namespaces. While such settings could be a good start, it is
74generally not a good idea to run NFD in this mode.
75
76While thorough discussion about security configuration of NFD is outside the scope of this
77document, at least the following change should be done to ``nfd.conf`` in authorize
78section:
79
80 authorizations
81 {
82 authorize
83 {
84 certfile certs/localhost_daemons_nrd.ndncert
85 privileges
86 {
87 faces
88 fib
89 strategy-choice
90 }
91 }
92
93 authorize
94 {
95 certfile any
96 privileges
97 {
98 faces
99 strategy-choice
100 }
101 }
102 }
103
104While this configuration still allows management of faces and updating strategy choice by
105anybody, only NFD's RIB Manager Daemon (`nrd`) is allowed to manage FIB.
106
107As the final step to make this configuration work, nrd's self-signed certificate needs to
108be exported into `localhost_daemons_nrd.ndncert` file:
109
110 sudo mkdir /usr/local/etc/ndn/certs
111 sudo sh -c 'sudo -u ndn -g ndn HOME=/usr/local/var/lib/ndn/nrd \
112 ndnsec-dump-certificate -i /localhost/daemons/nrd \
113 > /usr/local/etc/ndn/certs/localhost_daemons_nrd.ndncert'
114
115
116Enable auto-start
117-----------------
118
119After copying the provided upstart scripts, `nfd` and `nrd` daemons will automatically run
120after the reboot. To manually start them, use the following commands:
121
122 sudo start nfd
123 # nrd will be automatically started by upstart
124
125Note that an additional upstart job, ``nfd-watcher``, will automatically monitor for
126network connectivity changes, such as when network interface gets connected, disconnected,
127or IP addresses of the network interface get updated. When ``nfd-watcher`` detects the
128event, it will restart `nfd` and `nrd`.
129
130Disable auto-start
131------------------
132
133To stop `nrd` and `nfd` daemon, use the following commands:
134
135 sudo stop nfd
136 # nrd will be automatically stopped by upstart
137
138Note that as long as upstart files are present in `/etc/init/`, the daemons will
139automatically start after the reboot. To permanently stop `nfd` and `nrd` daemons, delete
140the upstart files:
141
142 sudo rm /etc/init/nfd.conf
143 sudo rm /etc/init/nrd.conf
144 sudo rm /etc/init/nfd-watcher.conf