contrib: Add unit file and instructions for systemd

refs #1586 Change-Id: I06b91804fc8b8613560ef98687307f56262689fb
2015-05-13 01:22:51 -07:00
parent 2d1b64066c
commit 187ade8566
2 changed files with 172 additions and 0 deletions
@@ -0,0 +1,130 @@
+Starting NFD on Linux with systemd
+==================================
+
+Newer versions of Ubuntu (starting with 15.04) and some other Linux distributions, including Debian
+use systemd to start system daemons, monitor their health, and restart them when they die.
+
+Initial setup
+-------------
+
+* Edit `nfd.service`, correcting the paths to the `nfd` executable, configuration, and
+  ``HOME`` directories.
+
+* Copy the systemd config file for NFD to the proper directory
+
+        sudo cp nfd.service /etc/systemd/system
+
+* Reload the systemd manager configuration
+
+        sudo systemctl daemon-reload
+
+### Assumptions in the default scripts
+
+* `nfd` is installed into `/usr/local/bin`
+* Configuraton file is `/usr/local/etc/ndn/nfd.conf`
+* `nfd` will be run as root
+* Log files will be written to `/usr/local/var/log/ndn` folder, which is owned by user `ndn`
+
+### Creating users
+
+If the `ndn` user and group do not exist, they need to be manually created.
+
+    # Create group `ndn`
+    sudo addgroup --system ndn
+
+    # Create user `ndn`
+    sudo adduser --system \
+                 --disabled-login \
+                 --ingroup ndn \
+                 --home /nonexistent \
+                 --gecos "NDN User" \
+                 --shell /bin/false \
+                 ndn
+
+
+### Creating folders
+
+Folder `/usr/local/var/log/ndn` should be created and assigned proper user and group:
+
+    sudo mkdir -p /usr/local/var/log/ndn
+    sudo chown -R ndn:ndn /usr/local/var/log/ndn
+
+`HOME` directory for `nfd` should be created prior to starting. This is necessary to manage
+unique security credentials for the daemon.
+
+    # Create HOME and generate self-signed NDN certificate for nfd
+    sudo sh -c ' \
+      mkdir -p /usr/local/var/lib/ndn/nfd/.ndn; \
+      export HOME=/usr/local/var/lib/ndn/nfd; \
+      ndnsec-keygen /localhost/daemons/nfd | ndnsec-install-cert -; \
+    '
+
+### Configuring NFD's security
+
+NFD sample configuration allows anybody to create faces, add nexthops to FIB, and set
+strategy choice for namespaces. While such settings could be a good start, it is
+generally not a good idea to run NFD in this mode.
+
+While thorough discussion about the security configuration of NFD is outside the scope of
+this document, at least the following change should be done in ``nfd.conf`` in the
+authorize section:
+
+    authorizations
+    {
+      authorize
+      {
+        certfile certs/localhost_daemons_nfd.ndncert
+        privileges
+        {
+            faces
+            fib
+            strategy-choice
+        }
+      }
+
+      authorize
+      {
+        certfile any
+        privileges
+        {
+            faces
+            strategy-choice
+        }
+      }
+    }
+
+While this configuration still allows the management of faces and updating strategy choice by
+anyone, only NFD's RIB Manager (i.e., NFD itself) is allowed to manage FIB.
+
+As the final step to make this configuration work, nfd's self-signed certificate needs to
+be exported into the `localhost_daemons_nfd.ndncert` file:
+
+    sudo sh -c '\
+      mkdir -p /usr/local/etc/ndn/certs || true; \
+      export HOME=/usr/local/var/lib/ndn/nfd; \
+      ndnsec-dump-certificate -i /localhost/daemons/nfd > \
+        /usr/local/etc/ndn/certs/localhost_daemons_nfd.ndncert; \
+    '
+
+Enable auto-start
+-----------------
+
+After copying the provided upstart script, auto-start of the `nfd` daemon can be enabled with:
+
+    sudo systemctl enable nfd
+
+To manually start it, use the following command:
+
+    sudo systemctl start nfd
+
+Disable auto-start
+------------------
+
+To stop the `nfd` daemon, use the following command:
+
+    sudo systemctl stop nfd
+
+To permanently stop the `nfd` daemon and disable it from being automatically started on reboot,
+disable the service:
+
+    sudo systemctl disable nfd
@@ -0,0 +1,42 @@
+# Copyright (c) 2015,  Regents of the University of California,
+#                      Arizona Board of Regents,
+#                      Colorado State University,
+#                      University Pierre & Marie Curie, Sorbonne University,
+#                      Washington University in St. Louis,
+#                      Beijing Institute of Technology,
+#                      The University of Memphis.
+#
+# This file is part of NFD (Named Data Networking Forwarding Daemon).
+# See AUTHORS.md for complete list of NFD authors and contributors.
+#
+# NFD is free software: you can redistribute it and/or modify it under the terms
+# of the GNU General Public License as published by the Free Software Foundation,
+# either version 3 of the License, or (at your option) any later version.
+#
+# NFD is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
+# without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+# PURPOSE.  See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with
+# NFD, e.g., in COPYING.md file.  If not, see <http://www.gnu.org/licenses/>.
+#
+# Author: Eric Newberry <enewberry@email.arizona.edu>
+
+[Unit]
+Description=NDN Forwarding Daemon
+Documentation=man:nfd man:nfdc man:nfd-status
+Wants=network-online.target
+After=network-online.target
+
+[Service]
+Environment=HOME=/usr/local/var/lib/ndn/nfd
+ExecStart=/usr/local/bin/nfd --config /usr/local/etc/ndn/nfd.conf
+ExecStartPost=/bin/sh -ec 'sleep 2; if [ -f /usr/local/etc/ndn/nfd-init.sh ]; then . /usr/local/etc/ndn/nfd-init.sh; fi'
+Restart=on-failure
+ProtectSystem=full
+PrivateTmp=yes
+PrivateDevices=yes
+ProtectHome=yes
+
+[Install]
+WantedBy=multi-user.target