Systemd service support and documentation update

RNS/Reticulum.py

@@ -101,6 +101,12 @@ class Reticulum:
         RNS.exit()
 
 
+    @staticmethod
+    def sigterm_handler(signal, frame):
+        RNS.Transport.detach_interfaces()
+        RNS.exit()
+
+
     def __init__(self,configdir=None, loglevel=None):
         """
         Initialises and starts a Reticulum instance. This must be
@@ -182,6 +188,7 @@ class Reticulum:
 
         atexit.register(Reticulum.exit_handler)
         signal.signal(signal.SIGINT, Reticulum.sigint_handler)
+        signal.signal(signal.SIGTERM, Reticulum.sigterm_handler)
 
     def __start_local_interface(self):
         if self.share_instance:

RNS/Utilities/rnsd.py

@@ -2,15 +2,23 @@
 
 import RNS
 import argparse
+import time
 
 from RNS._version import __version__
 
 
-def program_setup(configdir, verbosity = 0, quietness = 0):
+def program_setup(configdir, verbosity = 0, quietness = 0, service = False):
-    reticulum = RNS.Reticulum(configdir = configdir, loglevel = 3+verbosity-quietness)
+    targetloglevel = 3+verbosity-quietness
+
+    if service:
+        RNS.logdest = RNS.LOG_FILE
+        RNS.logfile = RNS.Reticulum.configdir+"/logfile"
+        targetloglevel = None
+
+    reticulum = RNS.Reticulum(configdir=configdir, loglevel=targetloglevel)
     RNS.log("Started rnsd version {version}".format(version=__version__), RNS.LOG_NOTICE)
     while True:
-        input()
+        time.sleep(1)
 
 def main():
     try:
@@ -18,6 +26,7 @@ def main():
         parser.add_argument("--config", action="store", default=None, help="path to alternative Reticulum config directory", type=str)
         parser.add_argument('-v', '--verbose', action='count', default=0)
         parser.add_argument('-q', '--quiet', action='count', default=0)
+        parser.add_argument('-s', '--service', action='store_true', default=False, help="rnsd is running as a service and should log to file")
         parser.add_argument("--version", action="version", version="rnsd {version}".format(version=__version__))
         
         args = parser.parse_args()
@@ -27,7 +36,7 @@ def main():
         else:
             configarg = None
 
-        program_setup(configdir = configarg, verbosity=args.verbose, quietness=args.quiet)
+        program_setup(configdir = configarg, verbosity=args.verbose, quietness=args.quiet, service=args.service)
 
     except KeyboardInterrupt:
         print("")

docs/manual/_sources/using.rst.txt

@@ -163,3 +163,94 @@ destinations will not have this option enabled, and will not be probable.
     --config CONFIG   path to alternative Reticulum config directory
     --version         show program's version number and exit
     -v, --verbose
+
+
+Improving System Configuration
+------------------------------
+
+If you are setting up a system for permanent use with Reticulum, there is a
+few system configuration changes that can make this easier to administrate.
+These changes will be detailed here.
+
+
+Fixed Serial Port Names
+=======================
+
+On a Reticulum node with several serial port based interfaces, it can be
+beneficial to use the fixed name device nodes for the serial ports, instead
+of the dynamically allocated shorthands such as ``/dev/ttyUSB0``. Under most
+Debian-based distributions, including Ubuntu and Raspberry Pi OS, these nodes
+can be found under ``/dev/serial/by-id``.
+
+You can use such a device path directly in place of the numbered shorthands.
+Here is an example of a packet radio TNC configured as such:
+
+.. code:: text
+
+  [[Packet Radio KISS Interface]]
+    type = KISSInterface
+    interface_enabled = True
+    outgoing = true
+    port = /dev/serial/by-id/usb-FTDI_FT230X_Basic_UART_43891CKM-if00-port0
+    speed = 115200    
+    databits = 8
+    parity = none
+    stopbits = 1
+    preamble = 150
+    txtail = 10
+    persistence = 200
+    slottime = 20
+
+Using this methodology avoids potential naming mix-ups where physical devices
+might be plugged and unplugged in different orders, or when node name
+assignment varies from one boot to another.
+
+
+Run Reticulum as a Service
+==========================
+
+Instead of starting Reticulum manually, you can install ``rnsd`` as a system
+service and have it start automatically at boot.
+
+If you installed Reticulum with ``pip``, the ``rnsd`` program will most likely
+be located in a user-local installation path only, which means ``systemd`` will not
+be able to execute it. In this case, you can simply symlink the ``rnsd`` program
+into a directory that is in systemd's path:
+
+.. code:: text
+
+  sudo ln -s $(which rnsd) /usr/local/bin/
+
+You can then create the service file ``/etc/systemd/system/rnsd.service`` with the
+following content:
+
+.. code:: text
+
+  [Unit]
+  Description=Reticulum Network Stack Daemon
+  After=network.target
+  StartLimitIntervalSec=0
+
+  [Service]
+  Type=simple
+  Restart=always
+  RestartSec=3
+  User=USERNAMEHERE
+  ExecStart=rnsd --service
+
+  [Install]
+  WantedBy=multi-user.target
+
+Be sure to replace ``USERNAMEHERE`` with the user you want to run ``rnsd`` as.
+
+To manually start ``rnsd`` run:
+
+.. code:: text
+
+  sudo systemctl start rnsd
+
+If you want to automatically start ``rnsd`` at boot, run:
+
+.. code:: text
+
+  sudo systemctl enable rnsd

docs/manual/index.html

@@ -68,6 +68,11 @@ to participate in the development of Reticulum itself.</p>
 <li class="toctree-l3"><a class="reference internal" href="using.html#the-rnprobe-utility">The rnprobe Utility</a></li>
 </ul>
 </li>
+<li class="toctree-l2"><a class="reference internal" href="using.html#improving-system-configuration">Improving System Configuration</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="using.html#fixed-serial-port-names">Fixed Serial Port Names</a></li>
+<li class="toctree-l3"><a class="reference internal" href="using.html#run-reticulum-as-a-service">Run Reticulum as a Service</a></li>
+</ul>
+</li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks</a><ul>

docs/manual/using.html

@@ -184,6 +184,79 @@ optional arguments:
 </div>
 </div>
 </div>
+<div class="section" id="improving-system-configuration">
+<h2>Improving System Configuration<a class="headerlink" href="#improving-system-configuration" title="Permalink to this headline">¶</a></h2>
+<p>If you are setting up a system for permanent use with Reticulum, there is a
+few system configuration changes that can make this easier to administrate.
+These changes will be detailed here.</p>
+<div class="section" id="fixed-serial-port-names">
+<h3>Fixed Serial Port Names<a class="headerlink" href="#fixed-serial-port-names" title="Permalink to this headline">¶</a></h3>
+<p>On a Reticulum node with several serial port based interfaces, it can be
+beneficial to use the fixed name device nodes for the serial ports, instead
+of the dynamically allocated shorthands such as <code class="docutils literal notranslate"><span class="pre">/dev/ttyUSB0</span></code>. Under most
+Debian-based distributions, including Ubuntu and Raspberry Pi OS, these nodes
+can be found under <code class="docutils literal notranslate"><span class="pre">/dev/serial/by-id</span></code>.</p>
+<p>You can use such a device path directly in place of the numbered shorthands.
+Here is an example of a packet radio TNC configured as such:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>[[Packet Radio KISS Interface]]
+  type = KISSInterface
+  interface_enabled = True
+  outgoing = true
+  port = /dev/serial/by-id/usb-FTDI_FT230X_Basic_UART_43891CKM-if00-port0
+  speed = 115200
+  databits = 8
+  parity = none
+  stopbits = 1
+  preamble = 150
+  txtail = 10
+  persistence = 200
+  slottime = 20
+</pre></div>
+</div>
+<p>Using this methodology avoids potential naming mix-ups where physical devices
+might be plugged and unplugged in different orders, or when node name
+assignment varies from one boot to another.</p>
+</div>
+<div class="section" id="run-reticulum-as-a-service">
+<h3>Run Reticulum as a Service<a class="headerlink" href="#run-reticulum-as-a-service" title="Permalink to this headline">¶</a></h3>
+<p>Instead of starting Reticulum manually, you can install <code class="docutils literal notranslate"><span class="pre">rnsd</span></code> as a system
+service and have it start automatically at boot.</p>
+<p>If you installed Reticulum with <code class="docutils literal notranslate"><span class="pre">pip</span></code>, the <code class="docutils literal notranslate"><span class="pre">rnsd</span></code> program will most likely
+be located in a user-local installation path only, which means <code class="docutils literal notranslate"><span class="pre">systemd</span></code> will not
+be able to execute it. In this case, you can simply symlink the <code class="docutils literal notranslate"><span class="pre">rnsd</span></code> program
+into a directory that is in systemd’s path:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>sudo ln -s $(which rnsd) /usr/local/bin/
+</pre></div>
+</div>
+<p>You can then create the service file <code class="docutils literal notranslate"><span class="pre">/etc/systemd/system/rnsd.service</span></code> with the
+following content:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>[Unit]
+Description=Reticulum Network Stack Daemon
+After=network.target
+StartLimitIntervalSec=0
+
+[Service]
+Type=simple
+Restart=always
+RestartSec=3
+User=USERNAMEHERE
+ExecStart=rnsd --service
+
+[Install]
+WantedBy=multi-user.target
+</pre></div>
+</div>
+<p>Be sure to replace <code class="docutils literal notranslate"><span class="pre">USERNAMEHERE</span></code> with the user you want to run <code class="docutils literal notranslate"><span class="pre">rnsd</span></code> as.</p>
+<p>To manually start <code class="docutils literal notranslate"><span class="pre">rnsd</span></code> run:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>sudo systemctl start rnsd
+</pre></div>
+</div>
+<p>If you want to automatically start <code class="docutils literal notranslate"><span class="pre">rnsd</span></code> at boot, run:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>sudo systemctl enable rnsd
+</pre></div>
+</div>
+</div>
+</div>
 </div>
 
 
@@ -203,6 +276,11 @@ optional arguments:
 <li><a class="reference internal" href="#the-rnprobe-utility">The rnprobe Utility</a></li>
 </ul>
 </li>
+<li><a class="reference internal" href="#improving-system-configuration">Improving System Configuration</a><ul>
+<li><a class="reference internal" href="#fixed-serial-port-names">Fixed Serial Port Names</a></li>
+<li><a class="reference internal" href="#run-reticulum-as-a-service">Run Reticulum as a Service</a></li>
+</ul>
+</li>
 </ul>
 </li>
 </ul>

docs/source/using.rst

@@ -163,3 +163,94 @@ destinations will not have this option enabled, and will not be probable.
     --config CONFIG   path to alternative Reticulum config directory
     --version         show program's version number and exit
     -v, --verbose
+
+
+Improving System Configuration
+------------------------------
+
+If you are setting up a system for permanent use with Reticulum, there is a
+few system configuration changes that can make this easier to administrate.
+These changes will be detailed here.
+
+
+Fixed Serial Port Names
+=======================
+
+On a Reticulum node with several serial port based interfaces, it can be
+beneficial to use the fixed name device nodes for the serial ports, instead
+of the dynamically allocated shorthands such as ``/dev/ttyUSB0``. Under most
+Debian-based distributions, including Ubuntu and Raspberry Pi OS, these nodes
+can be found under ``/dev/serial/by-id``.
+
+You can use such a device path directly in place of the numbered shorthands.
+Here is an example of a packet radio TNC configured as such:
+
+.. code:: text
+
+  [[Packet Radio KISS Interface]]
+    type = KISSInterface
+    interface_enabled = True
+    outgoing = true
+    port = /dev/serial/by-id/usb-FTDI_FT230X_Basic_UART_43891CKM-if00-port0
+    speed = 115200    
+    databits = 8
+    parity = none
+    stopbits = 1
+    preamble = 150
+    txtail = 10
+    persistence = 200
+    slottime = 20
+
+Using this methodology avoids potential naming mix-ups where physical devices
+might be plugged and unplugged in different orders, or when node name
+assignment varies from one boot to another.
+
+
+Run Reticulum as a Service
+==========================
+
+Instead of starting Reticulum manually, you can install ``rnsd`` as a system
+service and have it start automatically at boot.
+
+If you installed Reticulum with ``pip``, the ``rnsd`` program will most likely
+be located in a user-local installation path only, which means ``systemd`` will not
+be able to execute it. In this case, you can simply symlink the ``rnsd`` program
+into a directory that is in systemd's path:
+
+.. code:: text
+
+  sudo ln -s $(which rnsd) /usr/local/bin/
+
+You can then create the service file ``/etc/systemd/system/rnsd.service`` with the
+following content:
+
+.. code:: text
+
+  [Unit]
+  Description=Reticulum Network Stack Daemon
+  After=network.target
+  StartLimitIntervalSec=0
+
+  [Service]
+  Type=simple
+  Restart=always
+  RestartSec=3
+  User=USERNAMEHERE
+  ExecStart=rnsd --service
+
+  [Install]
+  WantedBy=multi-user.target
+
+Be sure to replace ``USERNAMEHERE`` with the user you want to run ``rnsd`` as.
+
+To manually start ``rnsd`` run:
+
+.. code:: text
+
+  sudo systemctl start rnsd
+
+If you want to automatically start ``rnsd`` at boot, run:
+
+.. code:: text
+
+  sudo systemctl enable rnsd