using.html
1 <!doctype html> 2 <html class="no-js" lang="en" data-content_root="./"> 3 <head><meta charset="utf-8"> 4 <meta name="viewport" content="width=device-width,initial-scale=1"> 5 <meta name="color-scheme" content="light dark"><meta name="viewport" content="width=device-width, initial-scale=1" /> 6 <link rel="index" title="Index" href="genindex.html"><link rel="search" title="Search" href="search.html"><link rel="next" title="Understanding Reticulum" href="understanding.html"><link rel="prev" title="Programs Using Reticulum" href="software.html"> 7 <link rel="prefetch" href="_static/rns_logo_512.png" as="image"> 8 9 <!-- Generated with Sphinx 8.2.3 and Furo 2025.09.25.dev1 --> 10 <title>Using Reticulum on Your System - Reticulum Network Stack 1.1.3 documentation</title> 11 <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d111a655" /> 12 <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=580074bf" /> 13 <link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" /> 14 <link rel="stylesheet" type="text/css" href="_static/styles/furo-extensions.css?v=8dab3a3b" /> 15 <link rel="stylesheet" type="text/css" href="_static/custom.css?v=bb3cebc5" /> 16 17 18 19 20 <style> 21 body { 22 --color-code-background: #f2f2f2; 23 --color-code-foreground: #1e1e1e; 24 25 } 26 @media not print { 27 body[data-theme="dark"] { 28 --color-code-background: #202020; 29 --color-code-foreground: #d0d0d0; 30 --color-background-primary: #202b38; 31 --color-background-secondary: #161f27; 32 --color-foreground-primary: #dbdbdb; 33 --color-foreground-secondary: #a9b1ba; 34 --color-brand-primary: #41adff; 35 --color-background-hover: #161f27; 36 --color-api-name: #ffbe85; 37 --color-api-pre-name: #efae75; 38 39 } 40 @media (prefers-color-scheme: dark) { 41 body:not([data-theme="light"]) { 42 --color-code-background: #202020; 43 --color-code-foreground: #d0d0d0; 44 --color-background-primary: #202b38; 45 --color-background-secondary: #161f27; 46 --color-foreground-primary: #dbdbdb; 47 --color-foreground-secondary: #a9b1ba; 48 --color-brand-primary: #41adff; 49 --color-background-hover: #161f27; 50 --color-api-name: #ffbe85; 51 --color-api-pre-name: #efae75; 52 53 } 54 } 55 } 56 </style></head> 57 <body> 58 59 <script> 60 document.body.dataset.theme = localStorage.getItem("theme") || "auto"; 61 </script> 62 63 64 <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> 65 <symbol id="svg-toc" viewBox="0 0 24 24"> 66 <title>Contents</title> 67 <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 1024 1024"> 68 <path d="M408 442h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8zm-8 204c0 4.4 3.6 8 8 8h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56zm504-486H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zm0 632H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zM115.4 518.9L271.7 642c5.8 4.6 14.4.5 14.4-6.9V388.9c0-7.4-8.5-11.5-14.4-6.9L115.4 505.1a8.74 8.74 0 0 0 0 13.8z"/> 69 </svg> 70 </symbol> 71 <symbol id="svg-menu" viewBox="0 0 24 24"> 72 <title>Menu</title> 73 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" 74 stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-menu"> 75 <line x1="3" y1="12" x2="21" y2="12"></line> 76 <line x1="3" y1="6" x2="21" y2="6"></line> 77 <line x1="3" y1="18" x2="21" y2="18"></line> 78 </svg> 79 </symbol> 80 <symbol id="svg-arrow-right" viewBox="0 0 24 24"> 81 <title>Expand</title> 82 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" 83 stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-chevron-right"> 84 <polyline points="9 18 15 12 9 6"></polyline> 85 </svg> 86 </symbol> 87 <symbol id="svg-sun" viewBox="0 0 24 24"> 88 <title>Light mode</title> 89 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" 90 stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="feather-sun"> 91 <circle cx="12" cy="12" r="5"></circle> 92 <line x1="12" y1="1" x2="12" y2="3"></line> 93 <line x1="12" y1="21" x2="12" y2="23"></line> 94 <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line> 95 <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line> 96 <line x1="1" y1="12" x2="3" y2="12"></line> 97 <line x1="21" y1="12" x2="23" y2="12"></line> 98 <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line> 99 <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line> 100 </svg> 101 </symbol> 102 <symbol id="svg-moon" viewBox="0 0 24 24"> 103 <title>Dark mode</title> 104 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" 105 stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-moon"> 106 <path stroke="none" d="M0 0h24v24H0z" fill="none" /> 107 <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z" /> 108 </svg> 109 </symbol> 110 <symbol id="svg-sun-with-moon" viewBox="0 0 24 24"> 111 <title>Auto light/dark, in light mode</title> 112 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" 113 stroke-width="1" stroke-linecap="round" stroke-linejoin="round" 114 class="icon-custom-derived-from-feather-sun-and-tabler-moon"> 115 <path style="opacity: 50%" d="M 5.411 14.504 C 5.471 14.504 5.532 14.504 5.591 14.504 C 3.639 16.319 4.383 19.569 6.931 20.352 C 7.693 20.586 8.512 20.551 9.25 20.252 C 8.023 23.207 4.056 23.725 2.11 21.184 C 0.166 18.642 1.702 14.949 4.874 14.536 C 5.051 14.512 5.231 14.5 5.411 14.5 L 5.411 14.504 Z"/> 116 <line x1="14.5" y1="3.25" x2="14.5" y2="1.25"/> 117 <line x1="14.5" y1="15.85" x2="14.5" y2="17.85"/> 118 <line x1="10.044" y1="5.094" x2="8.63" y2="3.68"/> 119 <line x1="19" y1="14.05" x2="20.414" y2="15.464"/> 120 <line x1="8.2" y1="9.55" x2="6.2" y2="9.55"/> 121 <line x1="20.8" y1="9.55" x2="22.8" y2="9.55"/> 122 <line x1="10.044" y1="14.006" x2="8.63" y2="15.42"/> 123 <line x1="19" y1="5.05" x2="20.414" y2="3.636"/> 124 <circle cx="14.5" cy="9.55" r="3.6"/> 125 </svg> 126 </symbol> 127 <symbol id="svg-moon-with-sun" viewBox="0 0 24 24"> 128 <title>Auto light/dark, in dark mode</title> 129 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" 130 stroke-width="1" stroke-linecap="round" stroke-linejoin="round" 131 class="icon-custom-derived-from-feather-sun-and-tabler-moon"> 132 <path d="M 8.282 7.007 C 8.385 7.007 8.494 7.007 8.595 7.007 C 5.18 10.184 6.481 15.869 10.942 17.24 C 12.275 17.648 13.706 17.589 15 17.066 C 12.851 22.236 5.91 23.143 2.505 18.696 C -0.897 14.249 1.791 7.786 7.342 7.063 C 7.652 7.021 7.965 7 8.282 7 L 8.282 7.007 Z"/> 133 <line style="opacity: 50%" x1="18" y1="3.705" x2="18" y2="2.5"/> 134 <line style="opacity: 50%" x1="18" y1="11.295" x2="18" y2="12.5"/> 135 <line style="opacity: 50%" x1="15.316" y1="4.816" x2="14.464" y2="3.964"/> 136 <line style="opacity: 50%" x1="20.711" y1="10.212" x2="21.563" y2="11.063"/> 137 <line style="opacity: 50%" x1="14.205" y1="7.5" x2="13.001" y2="7.5"/> 138 <line style="opacity: 50%" x1="21.795" y1="7.5" x2="23" y2="7.5"/> 139 <line style="opacity: 50%" x1="15.316" y1="10.184" x2="14.464" y2="11.036"/> 140 <line style="opacity: 50%" x1="20.711" y1="4.789" x2="21.563" y2="3.937"/> 141 <circle style="opacity: 50%" cx="18" cy="7.5" r="2.169"/> 142 </svg> 143 </symbol> 144 <symbol id="svg-pencil" viewBox="0 0 24 24"> 145 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" 146 stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-pencil-code"> 147 <path d="M4 20h4l10.5 -10.5a2.828 2.828 0 1 0 -4 -4l-10.5 10.5v4" /> 148 <path d="M13.5 6.5l4 4" /> 149 <path d="M20 21l2 -2l-2 -2" /> 150 <path d="M17 17l-2 2l2 2" /> 151 </svg> 152 </symbol> 153 <symbol id="svg-eye" viewBox="0 0 24 24"> 154 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" 155 stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-eye-code"> 156 <path stroke="none" d="M0 0h24v24H0z" fill="none" /> 157 <path d="M10 12a2 2 0 1 0 4 0a2 2 0 0 0 -4 0" /> 158 <path 159 d="M11.11 17.958c-3.209 -.307 -5.91 -2.293 -8.11 -5.958c2.4 -4 5.4 -6 9 -6c3.6 0 6.6 2 9 6c-.21 .352 -.427 .688 -.647 1.008" /> 160 <path d="M20 21l2 -2l-2 -2" /> 161 <path d="M17 17l-2 2l2 2" /> 162 </svg> 163 </symbol> 164 </svg> 165 166 <input type="checkbox" class="sidebar-toggle" name="__navigation" id="__navigation" aria-label="Toggle site navigation sidebar"> 167 <input type="checkbox" class="sidebar-toggle" name="__toc" id="__toc" aria-label="Toggle table of contents sidebar"> 168 <label class="overlay sidebar-overlay" for="__navigation"></label> 169 <label class="overlay toc-overlay" for="__toc"></label> 170 171 <a class="skip-to-content muted-link" href="#furo-main-content">Skip to content</a> 172 173 174 175 <div class="page"> 176 <header class="mobile-header"> 177 <div class="header-left"> 178 <label class="nav-overlay-icon" for="__navigation"> 179 <span class="icon"><svg><use href="#svg-menu"></use></svg></span> 180 </label> 181 </div> 182 <div class="header-center"> 183 <a href="index.html"><div class="brand">Reticulum Network Stack 1.1.3 documentation</div></a> 184 </div> 185 <div class="header-right"> 186 <div class="theme-toggle-container theme-toggle-header"> 187 <button class="theme-toggle" aria-label="Toggle Light / Dark / Auto color theme"> 188 <svg class="theme-icon-when-auto-light"><use href="#svg-sun-with-moon"></use></svg> 189 <svg class="theme-icon-when-auto-dark"><use href="#svg-moon-with-sun"></use></svg> 190 <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg> 191 <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg> 192 </button> 193 </div> 194 <label class="toc-overlay-icon toc-header-icon" for="__toc"> 195 <span class="icon"><svg><use href="#svg-toc"></use></svg></span> 196 </label> 197 </div> 198 </header> 199 <aside class="sidebar-drawer"> 200 <div class="sidebar-container"> 201 202 <div class="sidebar-sticky"><a class="sidebar-brand" href="index.html"> 203 <div class="sidebar-logo-container"> 204 <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/> 205 </div> 206 207 <span class="sidebar-brand-text">Reticulum Network Stack 1.1.3 documentation</span> 208 209 </a><form class="sidebar-search-container" method="get" action="search.html" role="search"> 210 <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search"> 211 <input type="hidden" name="check_keywords" value="yes"> 212 <input type="hidden" name="area" value="default"> 213 </form> 214 <div id="searchbox"></div><div class="sidebar-scroll"><div class="sidebar-tree"> 215 <ul class="current"> 216 <li class="toctree-l1"><a class="reference internal" href="whatis.html">What is Reticulum?</a></li> 217 <li class="toctree-l1"><a class="reference internal" href="gettingstartedfast.html">Getting Started Fast</a></li> 218 <li class="toctree-l1"><a class="reference internal" href="zen.html">Zen of Reticulum</a></li> 219 <li class="toctree-l1"><a class="reference internal" href="software.html">Programs Using Reticulum</a></li> 220 <li class="toctree-l1 current current-page"><a class="current reference internal" href="#">Using Reticulum on Your System</a></li> 221 <li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li> 222 <li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li> 223 <li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li> 224 <li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks</a></li> 225 <li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a></li> 226 <li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a></li> 227 <li class="toctree-l1"><a class="reference internal" href="license.html">Reticulum License</a></li> 228 </ul> 229 <ul> 230 <li class="toctree-l1"><a class="reference internal" href="reference.html">API Reference</a></li> 231 </ul> 232 233 </div> 234 </div> 235 236 </div> 237 238 </div> 239 </aside> 240 <div class="main"> 241 <div class="content"> 242 <div class="article-container"> 243 <a href="#" class="back-to-top muted-link"> 244 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"> 245 <path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8v12z"></path> 246 </svg> 247 <span>Back to top</span> 248 </a> 249 <div class="content-icon-container"> 250 <div class="theme-toggle-container theme-toggle-content"> 251 <button class="theme-toggle" aria-label="Toggle Light / Dark / Auto color theme"> 252 <svg class="theme-icon-when-auto-light"><use href="#svg-sun-with-moon"></use></svg> 253 <svg class="theme-icon-when-auto-dark"><use href="#svg-moon-with-sun"></use></svg> 254 <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg> 255 <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg> 256 </button> 257 </div> 258 <label class="toc-overlay-icon toc-content-icon" for="__toc"> 259 <span class="icon"><svg><use href="#svg-toc"></use></svg></span> 260 </label> 261 </div> 262 <article role="main" id="furo-main-content"> 263 <section id="using-reticulum-on-your-system"> 264 <span id="using-main"></span><h1>Using Reticulum on Your System<a class="headerlink" href="#using-reticulum-on-your-system" title="Link to this heading">¶</a></h1> 265 <p>Reticulum is not installed as a driver or kernel module, as one might expect 266 of a networking stack. Instead, Reticulum is distributed as a Python module, 267 containing the networking core, and a set of utility and daemon programs.</p> 268 <p>This means that no special privileges are required to install or use it. It 269 is also very light-weight, and easy to transfer to, and install on new systems.</p> 270 <p>When you have Reticulum installed, any program or application that uses Reticulum 271 will automatically load and initialise Reticulum when it starts, if it is not 272 already running.</p> 273 <p>In many cases, this approach is sufficient. When any program needs to use 274 Reticulum, it is loaded, initialised, interfaces are brought up, and the 275 program can now communicate over any Reticulum networks available. If another 276 program starts up and also wants access to the same Reticulum network, the already 277 running instance is simply shared. This works for any number of programs running 278 concurrently, and is very easy to use, but depending on your use case, there 279 are other options.</p> 280 <section id="configuration-data"> 281 <h2>Configuration & Data<a class="headerlink" href="#configuration-data" title="Link to this heading">¶</a></h2> 282 <p>Reticulum stores all information that it needs to function in a single file-system 283 directory. When Reticulum is started, it will look for a valid configuration 284 directory in the following places:</p> 285 <ul class="simple"> 286 <li><p><code class="docutils literal notranslate"><span class="pre">/etc/reticulum</span></code></p></li> 287 <li><p><code class="docutils literal notranslate"><span class="pre">~/.config/reticulum</span></code></p></li> 288 <li><p><code class="docutils literal notranslate"><span class="pre">~/.reticulum</span></code></p></li> 289 </ul> 290 <p>If no existing configuration directory is found, the directory <code class="docutils literal notranslate"><span class="pre">~/.reticulum</span></code> 291 is created, and the default configuration will be automatically created here. 292 You can move it to one of the other locations if you wish.</p> 293 <p>It is also possible to use completely arbitrary configuration directories by 294 specifying the relevant command-line parameters when running Reticulum-based 295 programs. You can also run multiple separate Reticulum instances on the same 296 physical system, either in isolation from each other, or connected together.</p> 297 <p>In most cases, a single physical system will only need to run one Reticulum 298 instance. This can either be launched at boot, as a system service, or simply 299 be brought up when a program needs it. In either case, any number of programs 300 running on the same system will automatically share the same Reticulum instance, 301 if the configuration allows for it, which it does by default.</p> 302 <p>The entire configuration of Reticulum is found in the <code class="docutils literal notranslate"><span class="pre">~/.reticulum/config</span></code> 303 file. When Reticulum is first started on a new system, a basic, but fully functional 304 configuration file is created. The default configuration looks like this:</p> 305 <div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="c1"># This is the default Reticulum config file.</span> 306 <span class="c1"># You should probably edit it to include any additional,</span> 307 <span class="c1"># interfaces and settings you might need.</span> 308 309 <span class="c1"># Only the most basic options are included in this default</span> 310 <span class="c1"># configuration. To see a more verbose, and much longer,</span> 311 <span class="c1"># configuration example, you can run the command:</span> 312 <span class="c1"># rnsd --exampleconfig</span> 313 314 315 <span class="k">[reticulum]</span> 316 317 <span class="c1"># If you enable Transport, your system will route traffic</span> 318 <span class="c1"># for other peers, pass announces and serve path requests.</span> 319 <span class="c1"># This should be done for systems that are suited to act</span> 320 <span class="c1"># as transport nodes, ie. if they are stationary and</span> 321 <span class="c1"># always-on. This directive is optional and can be removed</span> 322 <span class="c1"># for brevity.</span> 323 324 <span class="na">enable_transport</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">No</span> 325 326 327 <span class="c1"># By default, the first program to launch the Reticulum</span> 328 <span class="c1"># Network Stack will create a shared instance, that other</span> 329 <span class="c1"># programs can communicate with. Only the shared instance</span> 330 <span class="c1"># opens all the configured interfaces directly, and other</span> 331 <span class="c1"># local programs communicate with the shared instance over</span> 332 <span class="c1"># a local socket. This is completely transparent to the</span> 333 <span class="c1"># user, and should generally be turned on. This directive</span> 334 <span class="c1"># is optional and can be removed for brevity.</span> 335 336 <span class="na">share_instance</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">Yes</span> 337 338 339 <span class="c1"># If you want to run multiple *different* shared instances</span> 340 <span class="c1"># on the same system, you will need to specify different</span> 341 <span class="c1"># instance names for each. On platforms supporting domain</span> 342 <span class="c1"># sockets, this can be done with the instance_name option:</span> 343 344 <span class="na">instance_name</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">default</span> 345 346 <span class="c1"># Some platforms don't support domain sockets, and if that</span> 347 <span class="c1"># is the case, you can isolate different instances by</span> 348 <span class="c1"># specifying a unique set of ports for each:</span> 349 350 <span class="c1"># shared_instance_port = 37428</span> 351 <span class="c1"># instance_control_port = 37429</span> 352 353 354 <span class="c1"># If you want to explicitly use TCP for shared instance</span> 355 <span class="c1"># communication, instead of domain sockets, this is also</span> 356 <span class="c1"># possible, by using the following option:</span> 357 358 <span class="c1"># shared_instance_type = tcp</span> 359 360 361 <span class="c1"># On systems where running instances may not have access</span> 362 <span class="c1"># to the same shared Reticulum configuration directory,</span> 363 <span class="c1"># it is still possible to allow full interactivity for</span> 364 <span class="c1"># running instances, by manually specifying a shared RPC</span> 365 <span class="c1"># key. In almost all cases, this option is not needed, but</span> 366 <span class="c1"># it can be useful on operating systems such as Android.</span> 367 <span class="c1"># The key must be specified as bytes in hexadecimal.</span> 368 369 <span class="c1"># rpc_key = e5c032d3ec4e64a6aca9927ba8ab73336780f6d71790</span> 370 371 372 <span class="c1"># It is possible to allow remote management of Reticulum</span> 373 <span class="c1"># systems using the various built-in utilities, such as</span> 374 <span class="c1"># rnstatus and rnpath. You will need to specify one or</span> 375 <span class="c1"># more Reticulum Identity hashes for authenticating the</span> 376 <span class="c1"># queries from client programs. For this purpose, you can</span> 377 <span class="c1"># use existing identity files, or generate new ones with</span> 378 <span class="c1"># the rnid utility.</span> 379 380 <span class="c1"># enable_remote_management = yes</span> 381 <span class="c1"># remote_management_allowed = 9fb6d773498fb3feda407ed8ef2c3229, 2d882c5586e548d79b5af27bca1776dc</span> 382 383 384 <span class="c1"># You can configure Reticulum to panic and forcibly close</span> 385 <span class="c1"># if an unrecoverable interface error occurs, such as the</span> 386 <span class="c1"># hardware device for an interface disappearing. This is</span> 387 <span class="c1"># an optional directive, and can be left out for brevity.</span> 388 <span class="c1"># This behaviour is disabled by default.</span> 389 390 <span class="c1"># panic_on_interface_error = No</span> 391 392 393 <span class="c1"># When Transport is enabled, it is possible to allow the</span> 394 <span class="c1"># Transport Instance to respond to probe requests from</span> 395 <span class="c1"># the rnprobe utility. This can be a useful tool to test</span> 396 <span class="c1"># connectivity. When this option is enabled, the probe</span> 397 <span class="c1"># destination will be generated from the Identity of the</span> 398 <span class="c1"># Transport Instance, and printed to the log at startup.</span> 399 <span class="c1"># Optional, and disabled by default.</span> 400 401 <span class="c1"># respond_to_probes = No</span> 402 403 404 <span class="k">[logging]</span> 405 <span class="c1"># Valid log levels are 0 through 7:</span> 406 <span class="c1"># 0: Log only critical information</span> 407 <span class="c1"># 1: Log errors and lower log levels</span> 408 <span class="c1"># 2: Log warnings and lower log levels</span> 409 <span class="c1"># 3: Log notices and lower log levels</span> 410 <span class="c1"># 4: Log info and lower (this is the default)</span> 411 <span class="c1"># 5: Verbose logging</span> 412 <span class="c1"># 6: Debug logging</span> 413 <span class="c1"># 7: Extreme logging</span> 414 415 <span class="na">loglevel</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">4</span> 416 417 418 <span class="c1"># The interfaces section defines the physical and virtual</span> 419 <span class="c1"># interfaces Reticulum will use to communicate on. This</span> 420 <span class="c1"># section will contain examples for a variety of interface</span> 421 <span class="c1"># types. You can modify these or use them as a basis for</span> 422 <span class="c1"># your own config, or simply remove the unused ones.</span> 423 424 <span class="k">[interfaces]</span> 425 426 <span class="w"> </span><span class="c1"># This interface enables communication with other</span> 427 <span class="w"> </span><span class="c1"># link-local Reticulum nodes over UDP. It does not</span> 428 <span class="w"> </span><span class="c1"># need any functional IP infrastructure like routers</span> 429 <span class="w"> </span><span class="c1"># or DHCP servers, but will require that at least link-</span> 430 <span class="w"> </span><span class="c1"># local IPv6 is enabled in your operating system, which</span> 431 <span class="w"> </span><span class="c1"># should be enabled by default in almost any OS. See</span> 432 <span class="w"> </span><span class="c1"># the Reticulum Manual for more configuration options.</span> 433 434 <span class="w"> </span><span class="k">[[Default Interface]]</span> 435 <span class="w"> </span><span class="na">type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">AutoInterface</span> 436 <span class="w"> </span><span class="na">interface_enabled</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">True</span> 437 </pre></div> 438 </div> 439 <p>If Reticulum infrastructure already exists locally, you probably don’t need to 440 change anything, and you may already be connected to a wider network. If not, 441 you will probably need to add relevant <em>interfaces</em> to the configuration, in 442 order to communicate with other systems.</p> 443 <p>You can generate a much more verbose configuration example by running the command:</p> 444 <p><code class="docutils literal notranslate"><span class="pre">rnsd</span> <span class="pre">--exampleconfig</span></code></p> 445 <p>The output includes examples for most interface types supported 446 by Reticulum, along with additional options and configuration parameters.</p> 447 <p>It is a good idea to read the comments and explanations in the above default config. 448 It will teach you the basic concepts you need to understand to configure your network. 449 Once you have done that, take a look at the <a class="reference internal" href="interfaces.html#interfaces-main"><span class="std std-ref">Interfaces</span></a> chapter 450 of this manual.</p> 451 </section> 452 <section id="included-utility-programs"> 453 <h2>Included Utility Programs<a class="headerlink" href="#included-utility-programs" title="Link to this heading">¶</a></h2> 454 <p>Reticulum includes a range of useful utilities, both for managing your Reticulum 455 networks, and for carrying out common tasks over Reticulum networks, such as 456 transferring files to remote systems, and executing commands and programs remotely.</p> 457 <p>If you often use Reticulum from several different programs, or simply want 458 Reticulum to stay available all the time, for example if you are hosting 459 a transport node, you might want to run Reticulum as a separate service that 460 other programs, applications and services can utilise.</p> 461 <section id="the-rnsd-utility"> 462 <h3>The rnsd Utility<a class="headerlink" href="#the-rnsd-utility" title="Link to this heading">¶</a></h3> 463 <p>It is very easy to run Reticulum as a service. Simply run the included <code class="docutils literal notranslate"><span class="pre">rnsd</span></code> command. 464 When <code class="docutils literal notranslate"><span class="pre">rnsd</span></code> is running, it will keep all configured interfaces open, handle transport if 465 it is enabled, and allow any other programs to immediately utilise the 466 Reticulum network it is configured for.</p> 467 <p>You can even run multiple instances of <code class="docutils literal notranslate"><span class="pre">rnsd</span></code> with different configurations on 468 the same system.</p> 469 <p><strong>Usage Examples</strong></p> 470 <p>Run <code class="docutils literal notranslate"><span class="pre">rnsd</span></code>:</p> 471 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnsd 472 473 [2023-08-18 17:59:56] [Notice] Started rnsd version 0.5.8 474 </pre></div> 475 </div> 476 <p>Run <code class="docutils literal notranslate"><span class="pre">rnsd</span></code> in service mode, ensuring all logging output is sent directly to file:</p> 477 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnsd -s 478 </pre></div> 479 </div> 480 <p>Generate a verbose and detailed configuration example, with explanations of all the 481 various configuration options, and interface configuration examples:</p> 482 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnsd --exampleconfig 483 </pre></div> 484 </div> 485 <p><strong>All Command-Line Options</strong></p> 486 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnsd.py [-h] [--config CONFIG] [-v] [-q] [-s] [--exampleconfig] [--version] 487 488 Reticulum Network Stack Daemon 489 490 options: 491 -h, --help show this help message and exit 492 --config CONFIG path to alternative Reticulum config directory 493 -v, --verbose 494 -q, --quiet 495 -s, --service rnsd is running as a service and should log to file 496 -i, --interactive drop into interactive shell after initialisation 497 --exampleconfig print verbose configuration example to stdout and exit 498 --version show program's version number and exit 499 </pre></div> 500 </div> 501 <p>You can easily add <code class="docutils literal notranslate"><span class="pre">rnsd</span></code> as an always-on service by <a class="reference internal" href="#using-systemd"><span class="std std-ref">configuring a service</span></a>.</p> 502 </section> 503 <section id="the-rnstatus-utility"> 504 <h3>The rnstatus Utility<a class="headerlink" href="#the-rnstatus-utility" title="Link to this heading">¶</a></h3> 505 <p>Using the <code class="docutils literal notranslate"><span class="pre">rnstatus</span></code> utility, you can view the status of configured Reticulum 506 interfaces, similar to the <code class="docutils literal notranslate"><span class="pre">ifconfig</span></code> program.</p> 507 <p><strong>Usage Examples</strong></p> 508 <p>Run <code class="docutils literal notranslate"><span class="pre">rnstatus</span></code>:</p> 509 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnstatus 510 511 Shared Instance[37428] 512 Status : Up 513 Serving : 1 program 514 Rate : 1.00 Gbps 515 Traffic : 83.13 KB↑ 516 86.10 KB↓ 517 518 AutoInterface[Local] 519 Status : Up 520 Mode : Full 521 Rate : 10.00 Mbps 522 Peers : 1 reachable 523 Traffic : 63.23 KB↑ 524 80.17 KB↓ 525 526 TCPInterface[RNS Testnet Dublin/dublin.connect.reticulum.network:4965] 527 Status : Up 528 Mode : Full 529 Rate : 10.00 Mbps 530 Traffic : 187.27 KB↑ 531 74.17 KB↓ 532 533 RNodeInterface[RNode UHF] 534 Status : Up 535 Mode : Access Point 536 Rate : 1.30 kbps 537 Access : 64-bit IFAC by <…e702c42ba8> 538 Traffic : 8.49 KB↑ 539 9.23 KB↓ 540 541 Reticulum Transport Instance <5245a8efe1788c6a1cd36144a270e13b> running 542 </pre></div> 543 </div> 544 <p>Filter output to only show some interfaces:</p> 545 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnstatus rnode 546 547 RNodeInterface[RNode UHF] 548 Status : Up 549 Mode : Access Point 550 Rate : 1.30 kbps 551 Access : 64-bit IFAC by <…e702c42ba8> 552 Traffic : 8.49 KB↑ 553 9.23 KB↓ 554 555 Reticulum Transport Instance <5245a8efe1788c6a1cd36144a270e13b> running 556 </pre></div> 557 </div> 558 <p><strong>All Command-Line Options</strong></p> 559 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnstatus [-h] [--config CONFIG] [--version] [-a] [-A] 560 [-l] [-t] [-s SORT] [-r] [-j] [-R hash] [-i path] 561 [-w seconds] [-d] [-D] [-m] [-I seconds] [-v] [filter] 562 563 Reticulum Network Stack Status 564 565 positional arguments: 566 filter only display interfaces with names including filter 567 568 options: 569 -h, --help show this help message and exit 570 --config CONFIG path to alternative Reticulum config directory 571 --version show program's version number and exit 572 -a, --all show all interfaces 573 -A, --announce-stats show announce stats 574 -l, --link-stats show link stats 575 -t, --totals display traffic totals 576 -s, --sort SORT sort interfaces by [rate, traffic, rx, tx, rxs, txs, 577 announces, arx, atx, held] 578 -r, --reverse reverse sorting 579 -j, --json output in JSON format 580 -R hash transport identity hash of remote instance to get status from 581 -i path path to identity used for remote management 582 -w seconds timeout before giving up on remote queries 583 -d, --discovered list discovered interfaces 584 -D show details and config entries for discovered interfaces 585 -m, --monitor continuously monitor status 586 -I, --monitor-interval seconds 587 refresh interval for monitor mode (default: 1) 588 -v, --verbose 589 </pre></div> 590 </div> 591 <div class="admonition note"> 592 <p class="admonition-title">Note</p> 593 <p>When using <code class="docutils literal notranslate"><span class="pre">-R</span></code> to query a remote transport instance, you must also specify <code class="docutils literal notranslate"><span class="pre">-i</span></code> with the path to a management identity file that is authorized for remote management on the target system.</p> 594 </div> 595 </section> 596 <section id="the-rnid-utility"> 597 <h3>The rnid Utility<a class="headerlink" href="#the-rnid-utility" title="Link to this heading">¶</a></h3> 598 <p>With the <code class="docutils literal notranslate"><span class="pre">rnid</span></code> utility, you can generate, manage and view Reticulum Identities. 599 The program can also calculate Destination hashes, and perform encryption and 600 decryption of files.</p> 601 <p>Using <code class="docutils literal notranslate"><span class="pre">rnid</span></code>, it is possible to asymmetrically encrypt files and information for 602 any Reticulum destination hash, and also to create and verify cryptographic signatures.</p> 603 <p><strong>Usage Examples</strong></p> 604 <p>Generate a new Identity:</p> 605 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnid -g ./new_identity 606 </pre></div> 607 </div> 608 <p>Display Identity key information:</p> 609 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnid -i ./new_identity -p 610 611 Loaded Identity <984b74a3f768bef236af4371e6f248cd> from new_id 612 Public Key : 0f4259fef4521ab75a3409e353fe9073eb10783b4912a6a9937c57bf44a62c1e 613 Private Key : Hidden 614 </pre></div> 615 </div> 616 <p>Encrypt a file for an LXMF user:</p> 617 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnid -i 8dd57a738226809646089335a6b03695 -e my_file.txt 618 619 Recalled Identity <bc7291552be7a58f361522990465165c> for destination <8dd57a738226809646089335a6b03695> 620 Encrypting my_file.txt 621 File my_file.txt encrypted for <bc7291552be7a58f361522990465165c> to my_file.txt.rfe 622 </pre></div> 623 </div> 624 <p>If the Identity for the destination is not already known, you can fetch it from the network by using the <code class="docutils literal notranslate"><span class="pre">-R</span></code> command-line option:</p> 625 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnid -R -i 30602def3b3506a28ed33db6f60cc6c9 -e my_file.txt 626 627 Requesting unknown Identity for <30602def3b3506a28ed33db6f60cc6c9>... 628 Received Identity <2b489d06eaf7c543808c76a5332a447d> for destination <30602def3b3506a28ed33db6f60cc6c9> from the network 629 Encrypting my_file.txt 630 File my_file.txt encrypted for <2b489d06eaf7c543808c76a5332a447d> to my_file.txt.rfe 631 </pre></div> 632 </div> 633 <p>Decrypt a file using the Reticulum Identity it was encrypted for:</p> 634 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnid -i ./my_identity -d my_file.txt.rfe 635 636 Loaded Identity <2225fdeecaf6e2db4556c3c2d7637294> from ./my_identity 637 Decrypting ./my_file.txt.rfe... 638 File ./my_file.txt.rfe decrypted with <2225fdeecaf6e2db4556c3c2d7637294> to ./my_file.txt 639 </pre></div> 640 </div> 641 <p><strong>All Command-Line Options</strong></p> 642 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnid.py [-h] [--config path] [-i identity] [-g path] [-v] [-q] [-a aspects] 643 [-H aspects] [-e path] [-d path] [-s path] [-V path] [-r path] [-w path] 644 [-f] [-R] [-t seconds] [-p] [-P] [--version] 645 646 Reticulum Identity & Encryption Utility 647 648 options: 649 -h, --help show this help message and exit 650 --config path path to alternative Reticulum config directory 651 -i, --identity identity 652 hexadecimal Reticulum identity or destination hash, or path to Identity file 653 -g, --generate file generate a new Identity 654 -m, --import identity_data 655 import Reticulum identity in hex, base32 or base64 format 656 -x, --export export identity to hex, base32 or base64 format 657 -v, --verbose increase verbosity 658 -q, --quiet decrease verbosity 659 -a, --announce aspects 660 announce a destination based on this Identity 661 -H, --hash aspects show destination hashes for other aspects for this Identity 662 -e, --encrypt file encrypt file 663 -d, --decrypt file decrypt file 664 -s, --sign path sign file 665 -V, --validate path validate signature 666 -r, --read file input file path 667 -w, --write file output file path 668 -f, --force write output even if it overwrites existing files 669 -R, --request request unknown Identities from the network 670 -t seconds identity request timeout before giving up 671 -p, --print-identity print identity info and exit 672 -P, --print-private allow displaying private keys 673 -b, --base64 Use base64-encoded input and output 674 -B, --base32 Use base32-encoded input and output 675 --version show program's version number and exit 676 </pre></div> 677 </div> 678 </section> 679 <section id="the-rnpath-utility"> 680 <span id="utility-rnpath"></span><h3>The rnpath Utility<a class="headerlink" href="#the-rnpath-utility" title="Link to this heading">¶</a></h3> 681 <p>With the <code class="docutils literal notranslate"><span class="pre">rnpath</span></code> utility, you can look up and view paths for 682 destinations on the Reticulum network.</p> 683 <p><strong>Usage Examples</strong></p> 684 <p>Resolve path to a destination:</p> 685 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnpath c89b4da064bf66d280f0e4d8abfd9806 686 687 Path found, destination <c89b4da064bf66d280f0e4d8abfd9806> is 4 hops away via <f53a1c4278e0726bb73fcc623d6ce763> on TCPInterface[Testnet/dublin.connect.reticulum.network:4965] 688 </pre></div> 689 </div> 690 <p><strong>All Command-Line Options</strong></p> 691 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnpath [-h] [--config CONFIG] [--version] [-t] [-m hops] [-r] [-d] [-D] 692 [-x] [-w seconds] [-R hash] [-i path] [-W seconds] [-b] [-B] [-U] 693 [--duration DURATION] [--reason REASON] [-p] [-j] [-v] 694 [destination] [list_filter] 695 696 Reticulum Path Management Utility 697 698 positional arguments: 699 destination hexadecimal hash of the destination 700 list_filter filter for remote blackhole list view 701 702 options: 703 -h, --help show this help message and exit 704 --config CONFIG path to alternative Reticulum config directory 705 --version show program's version number and exit 706 -t, --table show all known paths 707 -m, --max hops maximum hops to filter path table by 708 -r, --rates show announce rate info 709 -d, --drop remove the path to a destination 710 -D, --drop-announces drop all queued announces 711 -x, --drop-via drop all paths via specified transport instance 712 -w seconds timeout before giving up 713 -R hash transport identity hash of remote instance to manage 714 -i path path to identity used for remote management 715 -W seconds timeout before giving up on remote queries 716 -b, --blackholed list blackholed identities 717 -B, --blackhole blackhole identity 718 -U, --unblackhole unblackhole identity 719 --duration DURATION duration of blackhole enforcement in hours 720 --reason REASON reason for blackholing identity 721 -p, --blackholed-list 722 view published blackhole list for remote transport instance 723 -j, --json output in JSON format 724 -v, --verbose 725 </pre></div> 726 </div> 727 </section> 728 <section id="the-rnprobe-utility"> 729 <h3>The rnprobe Utility<a class="headerlink" href="#the-rnprobe-utility" title="Link to this heading">¶</a></h3> 730 <p>The <code class="docutils literal notranslate"><span class="pre">rnprobe</span></code> utility lets you probe a destination for connectivity, similar 731 to the <code class="docutils literal notranslate"><span class="pre">ping</span></code> program. Please note that probes will only be answered if the 732 specified destination is configured to send proofs for received packets. Many 733 destinations will not have this option enabled, so most destinations will not 734 be probable.</p> 735 <p>You can enable a probe-reply destination on Reticulum Transport Instances by 736 setting the <code class="docutils literal notranslate"><span class="pre">respond_to_probes</span></code> configuration directive. Reticulum will then 737 print the probe destination to the log on Transport Instance startup.</p> 738 <p><strong>Usage Examples</strong></p> 739 <p>Probe a destination:</p> 740 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnprobe rnstransport.probe 2d03725b327348980d570f739a3a5708 741 742 Sent 16 byte probe to <2d03725b327348980d570f739a3a5708> 743 Valid reply received from <2d03725b327348980d570f739a3a5708> 744 Round-trip time is 38.469 milliseconds over 2 hops 745 </pre></div> 746 </div> 747 <p>Send a larger probe:</p> 748 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnprobe rnstransport.probe 2d03725b327348980d570f739a3a5708 -s 256 749 750 Sent 16 byte probe to <2d03725b327348980d570f739a3a5708> 751 Valid reply received from <2d03725b327348980d570f739a3a5708> 752 Round-trip time is 38.781 milliseconds over 2 hops 753 </pre></div> 754 </div> 755 <p>If the interface that receives the probe replies supports reporting radio 756 parameters such as <strong>RSSI</strong> and <strong>SNR</strong>, the <code class="docutils literal notranslate"><span class="pre">rnprobe</span></code> utility will print 757 these as part of the result as well.</p> 758 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnprobe rnstransport.probe e7536ee90bd4a440e130490b87a25124 759 760 Sent 16 byte probe to <e7536ee90bd4a440e130490b87a25124> 761 Valid reply received from <e7536ee90bd4a440e130490b87a25124> 762 Round-trip time is 1.809 seconds over 1 hop [RSSI -73 dBm] [SNR 12.0 dB] 763 </pre></div> 764 </div> 765 <p><strong>All Command-Line Options</strong></p> 766 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnprobe [-h] [--config CONFIG] [-s SIZE] [-n PROBES] 767 [-t seconds] [-w seconds] [--version] [-v] 768 [full_name] [destination_hash] 769 770 Reticulum Probe Utility 771 772 positional arguments: 773 full_name full destination name in dotted notation 774 destination_hash hexadecimal hash of the destination 775 776 options: 777 -h, --help show this help message and exit 778 --config CONFIG path to alternative Reticulum config directory 779 -s SIZE, --size SIZE size of probe packet payload in bytes 780 -n PROBES, --probes PROBES 781 number of probes to send 782 -t seconds, --timeout seconds 783 timeout before giving up 784 -w seconds, --wait seconds 785 time between each probe 786 --version show program's version number and exit 787 -v, --verbose 788 </pre></div> 789 </div> 790 </section> 791 <section id="the-rncp-utility"> 792 <h3>The rncp Utility<a class="headerlink" href="#the-rncp-utility" title="Link to this heading">¶</a></h3> 793 <p>The <code class="docutils literal notranslate"><span class="pre">rncp</span></code> utility is a simple file transfer tool. Using it, you can transfer 794 files through Reticulum.</p> 795 <p><strong>Usage Examples</strong></p> 796 <p>Run rncp on the receiving system, specifying which identities are allowed to send files:</p> 797 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rncp --listen -a 1726dbad538775b5bf9b0ea25a4079c8 -a c50cc4e4f7838b6c31f60ab9032cbc62 798 </pre></div> 799 </div> 800 <p>You can also specify allowed identity hashes (one per line) in the file ~/.rncp/allowed_identities 801 and simply running the program in listener mode:</p> 802 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rncp --listen 803 </pre></div> 804 </div> 805 <p>From another system, copy a file to the receiving system:</p> 806 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rncp ~/path/to/file.tgz 73cbd378bb0286ed11a707c13447bb1e 807 </pre></div> 808 </div> 809 <p>Or fetch a file from the remote system:</p> 810 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rncp --fetch ~/path/to/file.tgz 73cbd378bb0286ed11a707c13447bb1e 811 </pre></div> 812 </div> 813 <p>The default identity file is stored in <code class="docutils literal notranslate"><span class="pre">~/.reticulum/identities/rncp</span></code>, but you can use 814 another one, which will be created if it does not already exist</p> 815 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rncp ~/path/to/file.tgz 73cbd378bb0286ed11a707c13447bb1e -i /path/to/identity 816 </pre></div> 817 </div> 818 <p><strong>All Command-Line Options</strong></p> 819 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rncp [-h] [--config path] [-v] [-q] [-S] [-l] [-F] [-f] 820 [-j path] [-b seconds] [-a allowed_hash] [-n] [-p] 821 [-i identity] [-w seconds] [--version] [file] [destination] 822 823 Reticulum File Transfer Utility 824 825 positional arguments: 826 file file to be transferred 827 destination hexadecimal hash of the receiver 828 829 options: 830 -h, --help show this help message and exit 831 --config path path to alternative Reticulum config directory 832 -v, --verbose increase verbosity 833 -q, --quiet decrease verbosity 834 -S, --silent disable transfer progress output 835 -l, --listen listen for incoming transfer requests 836 -C, --no-compress disable automatic compression 837 -F, --allow-fetch allow authenticated clients to fetch files 838 -f, --fetch fetch file from remote listener instead of sending 839 -j, --jail path restrict fetch requests to specified path 840 -s, --save path save received files in specified path 841 -O, --overwrite Allow overwriting received files, instead of adding postfix 842 -b seconds announce interval, 0 to only announce at startup 843 -a allowed_hash allow this identity (or add in ~/.rncp/allowed_identities) 844 -n, --no-auth accept requests from anyone 845 -p, --print-identity print identity and destination info and exit 846 -i identity path to identity to use 847 -w seconds sender timeout before giving up 848 -P, --phy-rates display physical layer transfer rates 849 --version show program's version number and exit 850 </pre></div> 851 </div> 852 </section> 853 <section id="the-rnx-utility"> 854 <h3>The rnx Utility<a class="headerlink" href="#the-rnx-utility" title="Link to this heading">¶</a></h3> 855 <p>The <code class="docutils literal notranslate"><span class="pre">rnx</span></code> utility is a basic remote command execution program. It allows you to 856 execute commands on remote systems over Reticulum, and to view returned command 857 output. For a fully interactive remote shell solution, be sure to also take a look 858 at the <a class="reference external" href="https://github.com/acehoss/rnsh">rnsh</a> program.</p> 859 <p><strong>Usage Examples</strong></p> 860 <p>Run rnx on the listening system, specifying which identities are allowed to execute commands:</p> 861 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnx --listen -a 941bed5e228775e5a8079fc38b1ccf3f -a 1b03013c25f1c2ca068a4f080b844a10 862 </pre></div> 863 </div> 864 <p>From another system, run a command on the remote:</p> 865 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnx 7a55144adf826958a9529a3bcf08b149 "cat /proc/cpuinfo" 866 </pre></div> 867 </div> 868 <p>Or enter the interactive mode pseudo-shell:</p> 869 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnx 7a55144adf826958a9529a3bcf08b149 -x 870 </pre></div> 871 </div> 872 <p>The default identity file is stored in <code class="docutils literal notranslate"><span class="pre">~/.reticulum/identities/rnx</span></code>, but you can use 873 another one, which will be created if it does not already exist</p> 874 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnx 7a55144adf826958a9529a3bcf08b149 -i /path/to/identity -x 875 </pre></div> 876 </div> 877 <p><strong>All Command-Line Options</strong></p> 878 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnx [-h] [--config path] [-v] [-q] [-p] [-l] [-i identity] [-x] [-b] [-n] [-N] 879 [-d] [-m] [-a allowed_hash] [-w seconds] [-W seconds] [--stdin STDIN] 880 [--stdout STDOUT] [--stderr STDERR] [--version] [destination] [command] 881 882 Reticulum Remote Execution Utility 883 884 positional arguments: 885 destination hexadecimal hash of the listener 886 command command to be execute 887 888 optional arguments: 889 -h, --help show this help message and exit 890 --config path path to alternative Reticulum config directory 891 -v, --verbose increase verbosity 892 -q, --quiet decrease verbosity 893 -p, --print-identity print identity and destination info and exit 894 -l, --listen listen for incoming commands 895 -i identity path to identity to use 896 -x, --interactive enter interactive mode 897 -b, --no-announce don't announce at program start 898 -a allowed_hash accept from this identity 899 -n, --noauth accept files from anyone 900 -N, --noid don't identify to listener 901 -d, --detailed show detailed result output 902 -m mirror exit code of remote command 903 -w seconds connect and request timeout before giving up 904 -W seconds max result download time 905 --stdin STDIN pass input to stdin 906 --stdout STDOUT max size in bytes of returned stdout 907 --stderr STDERR max size in bytes of returned stderr 908 --version show program's version number and exit 909 </pre></div> 910 </div> 911 </section> 912 <section id="the-rnodeconf-utility"> 913 <h3>The rnodeconf Utility<a class="headerlink" href="#the-rnodeconf-utility" title="Link to this heading">¶</a></h3> 914 <p>The <code class="docutils literal notranslate"><span class="pre">rnodeconf</span></code> utility allows you to inspect and configure existing <a class="reference internal" href="hardware.html#rnode-main"><span class="std std-ref">RNodes</span></a>, and 915 to create and provision new <a class="reference internal" href="hardware.html#rnode-main"><span class="std std-ref">RNodes</span></a> from any supported hardware devices.</p> 916 <p><strong>All Command-Line Options</strong></p> 917 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnodeconf [-h] [-i] [-a] [-u] [-U] [--fw-version version] 918 [--fw-url url] [--nocheck] [-e] [-E] [-C] 919 [--baud-flash baud_flash] [-N] [-T] [-b] [-B] [-p] [-D i] 920 [--display-addr byte] [--freq Hz] [--bw Hz] [--txp dBm] 921 [--sf factor] [--cr rate] [--eeprom-backup] [--eeprom-dump] 922 [--eeprom-wipe] [-P] [--trust-key hexbytes] [--version] [-f] 923 [-r] [-k] [-S] [-H FIRMWARE_HASH] [--platform platform] 924 [--product product] [--model model] [--hwrev revision] 925 [port] 926 927 RNode Configuration and firmware utility. This program allows you to change 928 various settings and startup modes of RNode. It can also install, flash and 929 update the firmware on supported devices. 930 931 positional arguments: 932 port serial port where RNode is attached 933 934 options: 935 -h, --help show this help message and exit 936 -i, --info Show device info 937 -a, --autoinstall Automatic installation on various supported devices 938 -u, --update Update firmware to the latest version 939 -U, --force-update Update to specified firmware even if version matches or is older than installed version 940 --fw-version version Use a specific firmware version for update or autoinstall 941 --fw-url url Use an alternate firmware download URL 942 --nocheck Don't check for firmware updates online 943 -e, --extract Extract firmware from connected RNode for later use 944 -E, --use-extracted Use the extracted firmware for autoinstallation or update 945 -C, --clear-cache Clear locally cached firmware files 946 --baud-flash baud_flash 947 Set specific baud rate when flashing device. Default is 921600 948 -N, --normal Switch device to normal mode 949 -T, --tnc Switch device to TNC mode 950 -b, --bluetooth-on Turn device bluetooth on 951 -B, --bluetooth-off Turn device bluetooth off 952 -p, --bluetooth-pair Put device into bluetooth pairing mode 953 -D, --display i Set display intensity (0-255) 954 -t, --timeout s Set display timeout in seconds, 0 to disable 955 -R, --rotation rotation 956 Set display rotation, valid values are 0 through 3 957 --display-addr byte Set display address as hex byte (00 - FF) 958 --recondition-display 959 Start display reconditioning 960 --np i Set NeoPixel intensity (0-255) 961 --freq Hz Frequency in Hz for TNC mode 962 --bw Hz Bandwidth in Hz for TNC mode 963 --txp dBm TX power in dBm for TNC mode 964 --sf factor Spreading factor for TNC mode (7 - 12) 965 --cr rate Coding rate for TNC mode (5 - 8) 966 -x, --ia-enable Enable interference avoidance 967 -X, --ia-disable Disable interference avoidance 968 -c, --config Print device configuration 969 --eeprom-backup Backup EEPROM to file 970 --eeprom-dump Dump EEPROM to console 971 --eeprom-wipe Unlock and wipe EEPROM 972 -P, --public Display public part of signing key 973 --trust-key hexbytes Public key to trust for device verification 974 --version Print program version and exit 975 -f, --flash Flash firmware and bootstrap EEPROM 976 -r, --rom Bootstrap EEPROM without flashing firmware 977 -k, --key Generate a new signing key and exit 978 -S, --sign Display public part of signing key 979 -H, --firmware-hash FIRMWARE_HASH 980 Set installed firmware hash 981 --platform platform Platform specification for device bootstrap 982 --product product Product specification for device bootstrap 983 --model model Model code for device bootstrap 984 --hwrev revision Hardware revision for device bootstrap 985 </pre></div> 986 </div> 987 <p>For more information on how to create your own RNodes, please read the <a class="reference internal" href="hardware.html#rnode-creating"><span class="std std-ref">Creating RNodes</span></a> 988 section of this manual.</p> 989 </section> 990 </section> 991 <section id="discovering-interfaces"> 992 <span id="using-interface-discovery"></span><h2>Discovering Interfaces<a class="headerlink" href="#discovering-interfaces" title="Link to this heading">¶</a></h2> 993 <p>Reticulum includes built-in functionality for discovering connectable interfaces over Reticulum itself. This is particularly useful in situations where you want to do one or more of the following:</p> 994 <ul class="simple"> 995 <li><p>Discover connectable entrypoints available on the Internet</p></li> 996 <li><p>Find connectable radio access points in the physical world</p></li> 997 <li><p>Maintain connectivity to RNS instances with unknown or changing IP addresses</p></li> 998 </ul> 999 <p>Discovered interfaces can be <strong>auto-connected</strong> by Reticulum, which makes it possible to create setups where an arbitrary interface can act simply as a bootstrap connection, that can be torn down again once more suitable interfaces have been discovered and connected.</p> 1000 <p>The interface discovery mechanism uses announces sent over Reticulum itself, and supports both publicly readable interfaces and private, encrypted discovery, that can only be decoded by specified <em>network identities</em>. It is also possible to specify which network identities should be considered valid sources for discovered interfaces, so that interfaces published by unknown entities are ignored.</p> 1001 <div class="admonition note"> 1002 <p class="admonition-title">Note</p> 1003 <p>A <em>network identity</em> is a normal Reticulum identity keyset that can be used by 1004 one or more transport nodes to identify them as belonging to the same overall 1005 network. In the context of interface discovery, this makes it easy to manage 1006 connecting to only the particular networks you care about, even if those networks 1007 utilize many individual physical transport node.</p> 1008 <p>This also makes it convenient to auto-connect discovered interfaces only for networks you have some level of trust in.</p> 1009 </div> 1010 <p>For information on how to make your interfaces discoverable, see the <a class="reference internal" href="interfaces.html#interfaces-discoverable"><span class="std std-ref">Discoverable Interfaces</span></a> chapter of this manual. The current section will focus on how to actually <em>discover and connect to</em> interfaces available on the network.</p> 1011 <p>In its most basic form, enabling interface discovery is as simple as setting <code class="docutils literal notranslate"><span class="pre">discover_interfaces</span></code> to <code class="docutils literal notranslate"><span class="pre">true</span></code> in your Reticulum config:</p> 1012 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>[reticulum] 1013 ... 1014 discover_interfaces = yes 1015 ... 1016 </pre></div> 1017 </div> 1018 <p>Once this option is enabled, your RNS instance will start listening for interface discovery announces, and store them for later use or inspection. You can list discovered interfaces with the <code class="docutils literal notranslate"><span class="pre">rnstatus</span></code> utility:</p> 1019 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnstatus -d 1020 1021 Name Type Status Last Heard Value Location 1022 ------------------------------------------------------------------------- 1023 Sideband Hub Backbone ✓ Available 1h ago 16 46.2316, 6.0536 1024 RNS Amsterdam Backbone ✓ Available 32m ago 16 52.3865, 4.9037 1025 </pre></div> 1026 </div> 1027 <p>You can view more detailed information about discovered interfaces, including configuration snippets for pasting directly into your <code class="docutils literal notranslate"><span class="pre">[interfaces]</span></code> config, by using the <code class="docutils literal notranslate"><span class="pre">rnstatus</span> <span class="pre">-D</span></code> option:</p> 1028 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnstatus -D sideband 1029 1030 Transport ID : 521c87a83afb8f29e4455e77930b973b 1031 Name : Sideband Hub 1032 Type : BackboneInterface 1033 Status : Available 1034 Transport : Enabled 1035 Distance : 2 hops 1036 Discovered : 9h and 40m ago 1037 Last Heard : 1h and 15m ago 1038 Location : 46.2316, 6.0536 1039 Address : sideband.connect.reticulum.network:7822 1040 Stamp Value : 16 1041 1042 Configuration Entry: 1043 [[Sideband Hub]] 1044 type = BackboneInterface 1045 enabled = yes 1046 remote = sideband.connect.reticulum.network 1047 target_port = 7822 1048 transport_identity = 521c87a83afb8f29e4455e77930b973b 1049 </pre></div> 1050 </div> 1051 <p>In addition to providing local interface discovery information and control, the <code class="docutils literal notranslate"><span class="pre">rnstatus</span></code> utility can export discovered interface data in machine-readable JSON format using the <code class="docutils literal notranslate"><span class="pre">rnstatus</span> <span class="pre">-d</span> <span class="pre">--json</span></code> option. This can be useful for exporting the data to external applications such as status pages, access point maps and similar.</p> 1052 <p>To control what sources are considered valid for discovered sources, additional 1053 configuration options can be specified for the interface discovery system.</p> 1054 <ul class="simple"> 1055 <li><p>The <code class="docutils literal notranslate"><span class="pre">interface_discovery_sources</span></code> option is a list of the network or transport identities from which interfaces will be accepted. If this option is set, all others will be ignored. If this option is not set, discovered interfaces will be accepted from any source, but are still subject to stamp value requirements.</p></li> 1056 <li><p>The <code class="docutils literal notranslate"><span class="pre">required_discovery_value</span></code> options specifies the minimum stamp value required for the interface announce to be considered valid. To make it computationally difficult to spam the network with a large number of defunct or malicious interfaces, each announced interface requires a valid cryptographical stamp, of configurable difficulty value.</p></li> 1057 <li><p>The <code class="docutils literal notranslate"><span class="pre">autoconnect_discovered_interfaces</span></code> value defaults to <code class="docutils literal notranslate"><span class="pre">0</span></code>, and specifies the maximum number of discovered interfaces that should be auto-connected at any given time. If set to a number greater than <code class="docutils literal notranslate"><span class="pre">0</span></code>, Reticulum automatically manages discovered interface connections, and will bring discovered interfaces up and down based on availability. You can at any time add discovered interfaces to your configuration manually, to persistently keep them available.</p></li> 1058 <li><p>The <code class="docutils literal notranslate"><span class="pre">network_identity</span></code> option specifies the <em>network identity</em> for this RNS instance. This identity is used both to sign (and potentially encrypt) <em>outgoing</em> interface discovery announces, and to decrypt incoming discovery information.</p></li> 1059 </ul> 1060 <p>The configuration snippet below contains an example of setting these additional configuration options:</p> 1061 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>[reticulum] 1062 ... 1063 discover_interfaces = yes 1064 interface_discovery_sources = 521c87a83afb8f29e4455e77930b973b 1065 required_discovery_value = 16 1066 autoconnect_discovered_interfaces = 3 1067 network_identity = ~/.reticulum/storage/identities/my_network 1068 ... 1069 </pre></div> 1070 </div> 1071 </section> 1072 <section id="remote-management"> 1073 <h2>Remote Management<a class="headerlink" href="#remote-management" title="Link to this heading">¶</a></h2> 1074 <p>It is possible to allow remote management of Reticulum 1075 systems using the various built-in utilities, such as 1076 <code class="docutils literal notranslate"><span class="pre">rnstatus</span></code> and <code class="docutils literal notranslate"><span class="pre">rnpath</span></code>. To do so, you will need to set 1077 the <code class="docutils literal notranslate"><span class="pre">enable_remote_management</span></code> directive in the <code class="docutils literal notranslate"><span class="pre">[reticulum]</span></code> 1078 section of the configuration file. You will also need to specify 1079 one or more Reticulum Identity hashes for authenticating the 1080 queries from client programs. For this purpose, you can use 1081 existing identity files, or generate new ones with the rnid utility.</p> 1082 <p>The following is a truncated example of enabling remote management 1083 in the Reticulum configuration file:</p> 1084 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>[reticulum] 1085 ... 1086 enable_remote_management = yes 1087 remote_management_allowed = 9fb6d773498fb3feda407ed8ef2c3229, 2d882c5586e548d79b5af27bca1776dc 1088 ... 1089 </pre></div> 1090 </div> 1091 <p>For a complete example configuration, you can run <code class="docutils literal notranslate"><span class="pre">rnsd</span> <span class="pre">--exampleconfig</span></code>.</p> 1092 </section> 1093 <section id="blackhole-management"> 1094 <span id="using-blackhole-management"></span><h2>Blackhole Management<a class="headerlink" href="#blackhole-management" title="Link to this heading">¶</a></h2> 1095 <p>Reticulum networks are fundamentally permissionless and open, allowing anyone with a compatible interface to participate. While this openness is essential for a resilient and decentralized network, it also exposes the network to potential abuse, such as peers flooding the network with excessive announce broadcasts or other forms of resource exhaustion.</p> 1096 <p>The <strong>Blackhole</strong> system provides tools to help manage this problem. It allows operators and individual users to block specific identities at the Transport layer, preventing them from propagating announces through your node, and for other nodes to reach them through your network.</p> 1097 <div class="admonition important"> 1098 <p class="admonition-title">Important</p> 1099 <p>There is fundamentally <strong>no way</strong> to <em>globally</em> block or censor any identity or destination in Reticulum networks. The blackhole functionality will prevent announces from (and traffic to) all destinations associated with the blackholed identity <em>on your own network segments only</em>.</p> 1100 <p>This provides users and operators with control over what they want to allow <em>on their own network segments</em>, but there is no way to globally censor or remove an identity, as long as <em>someone</em> is willing to provide transport for it.</p> 1101 </div> 1102 <p>This functionality serves a dual purpose:</p> 1103 <ul class="simple"> 1104 <li><p><strong>For Individual Users:</strong> It offers a simple way to maintain a quiet and efficient local network by manually blocking spammy or unwanted peers.</p></li> 1105 <li><p><strong>For Network Operators:</strong> It enables the creation of federated, community-wide security standards. By publishing and sharing blackhole lists, operators can protect large infrastructures and distribute spam filtering rules across the mesh without manual intervention.</p></li> 1106 </ul> 1107 <section id="local-blackhole-management"> 1108 <h3>Local Blackhole Management<a class="headerlink" href="#local-blackhole-management" title="Link to this heading">¶</a></h3> 1109 <p>The most immediate way to manage unwanted identities is through manual configuration using the <code class="docutils literal notranslate"><span class="pre">rnpath</span></code> utility. This allows you to instantly block or unblock specific identities on your local Transport Instance.</p> 1110 <p><strong>Blackholing an Identity</strong></p> 1111 <p>To block an identity, use the <code class="docutils literal notranslate"><span class="pre">-B</span></code> (or <code class="docutils literal notranslate"><span class="pre">--blackhole</span></code>) flag followed by the identity hash. You can optionally specify a duration and a reason, which are useful for logging and future reference.</p> 1112 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnpath -B 3a4f8b9c1d2e3f4g5h6i7j8k9l0m1n2o 1113 </pre></div> 1114 </div> 1115 <p>You can also add a duration (in hours) and a reason:</p> 1116 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnpath -B 3a4f8b9c1d2e3f4g5h6i7j8k9l0m1n2o --duration 24 --reason "Excessive announces" 1117 </pre></div> 1118 </div> 1119 <p><strong>Lifting Blackholes</strong></p> 1120 <p>To remove an identity from the blackhole, use the <code class="docutils literal notranslate"><span class="pre">-U</span></code> (or <code class="docutils literal notranslate"><span class="pre">--unblackhole</span></code>) flag:</p> 1121 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnpath -U 3a4f8b9c1d2e3f4g5h6i7j8k9l0m1n2o 1122 </pre></div> 1123 </div> 1124 <p><strong>Viewing the Blackhole List</strong></p> 1125 <p>To see all identities currently blackholed on your local instance, use the <code class="docutils literal notranslate"><span class="pre">-b</span></code> (or <code class="docutils literal notranslate"><span class="pre">--blackholed</span></code>) flag:</p> 1126 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnpath -b 1127 1128 <3a4f8b9c1d2e3f4g5h6i7j8k9l0m1n2o> blackholed for 23h, 56m (Excessive announces) 1129 <399ea050ce0eed1816c300bcb0840938> blackholed indefinitely (Announce spam) 1130 <d56a4fa02c0a77b3575935aedd90bdb2> blackholed indefinitely (Announce spam) 1131 <2b9ec651326d9bc274119054c70fb75e> blackholed indefinitely (Announce spam) 1132 <1178a8f1fad405bf2ad153bf5036bdfd> blackholed indefinitely (Announce spam) 1133 </pre></div> 1134 </div> 1135 </section> 1136 <section id="automated-list-sourcing"> 1137 <h3>Automated List Sourcing<a class="headerlink" href="#automated-list-sourcing" title="Link to this heading">¶</a></h3> 1138 <p>Manually blocking identities is effective for immediate threats, but maintaining an up-to-date blocklist for a large network is impractical. Reticulum supports <strong>automated list sourcing</strong>, allowing your node to subscribe to blackhole lists maintained by trusted peers, or a central authority you manage yourself.</p> 1139 <div class="admonition warning"> 1140 <p class="admonition-title">Warning</p> 1141 <p><strong>Verify Before Subscribing!</strong> Subscribing to a blackhole source is a powerful action that grants that source the ability to dictate who you can communicate with. Before adding a source to your configuration, verify that the maintainer aligns with your usage policy and values. Blindly subscribing to untrusted lists could inadvertently block legitimate peers or essential services.</p> 1142 </div> 1143 <p>When enabled, your Transport Instance will periodically (approximately once per hour) connect to configured sources, retrieve their latest blackhole lists, and automatically merge them into your local blocklist. This provides “set-and-forget” protection for both individual users and large networks.</p> 1144 <p><strong>Configuration</strong></p> 1145 <p>To enable automated sourcing, add the <code class="docutils literal notranslate"><span class="pre">blackhole_sources</span></code> option to the <code class="docutils literal notranslate"><span class="pre">[reticulum]</span></code> section of your configuration file. This option accepts a comma-separated list of Transport Identity hashes that you trust to provide valid blackhole lists.</p> 1146 <div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[reticulum]</span> 1147 <span class="na">...</span> 1148 <span class="c1"># Automatically fetch blackhole lists from these trusted sources</span> 1149 <span class="na">blackhole_sources</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">521c87a83afb8f29e4455e77930b973b, 68a4aa91ac350c4087564e8a69f84e86</span> 1150 <span class="na">...</span> 1151 </pre></div> 1152 </div> 1153 <p><strong>How It Works</strong></p> 1154 <ol class="arabic simple"> 1155 <li><p>When enabled, the <code class="docutils literal notranslate"><span class="pre">BlackholeUpdater</span></code> service runs in the background.</p></li> 1156 <li><p>For every identity hash listed in <code class="docutils literal notranslate"><span class="pre">blackhole_sources</span></code>, it attempts to establish a temporary link to its associated``rnstransport.info.blackhole`` destination.</p></li> 1157 <li><p>It requests the <code class="docutils literal notranslate"><span class="pre">/list</span></code> path, which returns a dictionary of blackholed identities and their associated metadata.</p></li> 1158 <li><p>The received list is merged with your local <code class="docutils literal notranslate"><span class="pre">blackholed_identities</span></code> database.</p></li> 1159 <li><p>The lists are persisted to disk, ensuring they survive restarts.</p></li> 1160 </ol> 1161 <div class="admonition note"> 1162 <p class="admonition-title">Note</p> 1163 <p>You can verify the external lists you are subscribed to, and their contents, without importing them by using <code class="docutils literal notranslate"><span class="pre">rnpath</span> <span class="pre">-p</span></code>. See the <a class="reference internal" href="#utility-rnpath"><span class="std std-ref">rnpath utility documentation</span></a> for details on querying remote blackhole lists.</p> 1164 </div> 1165 </section> 1166 <section id="publishing-blackhole-lists"> 1167 <h3>Publishing Blackhole Lists<a class="headerlink" href="#publishing-blackhole-lists" title="Link to this heading">¶</a></h3> 1168 <p>If you are operating a public gateway, a community hub, or simply wish to share your blackhole list with others, you can configure your instance to act as a blackhole list publisher. This allows other nodes to subscribe to <em>your</em> definitions of unwanted traffic.</p> 1169 <p><strong>Enabling Publishing</strong></p> 1170 <p>To publish your local blackhole list, enable the <code class="docutils literal notranslate"><span class="pre">publish_blackhole</span></code> option in the <code class="docutils literal notranslate"><span class="pre">[reticulum]</span></code> section:</p> 1171 <div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[reticulum]</span> 1172 <span class="na">...</span> 1173 <span class="na">publish_blackhole</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span> 1174 <span class="na">...</span> 1175 </pre></div> 1176 </div> 1177 <p>When this is enabled, your Transport Instance will register a request handler at <code class="docutils literal notranslate"><span class="pre">rnstransport.info.blackhole</span></code>. Any peer that connects to this destination and requests <code class="docutils literal notranslate"><span class="pre">/list</span></code> will receive the complete set of identities currently present in your local blackhole database.</p> 1178 <p><strong>Federation and Trust</strong></p> 1179 <p>The blackhole system relies on the trust relationship between the subscriber and the publisher. By subscribing to a source, you are implicitly trusting that source to only block identities that are genuinely detrimental to the network.</p> 1180 <p>As the ecosystem matures, this system is designed to integrate with <strong>Network Identities</strong>. This allows communities to verify that a published blackhole list is actually provided by a specific network or organization with a certain level of reputation and trustworthiness, adding a layer of cryptographic trust to the federation process. This prevents malicious actors from publishing fake lists intended to censor legitimate traffic.</p> 1181 <p>For operators, this creates a scalable model where maintaining a single high-quality blocklist can protect thousands of downstream peers, drastically reducing the administrative.</p> 1182 </section> 1183 </section> 1184 <section id="improving-system-configuration"> 1185 <h2>Improving System Configuration<a class="headerlink" href="#improving-system-configuration" title="Link to this heading">¶</a></h2> 1186 <p>If you are setting up a system for permanent use with Reticulum, there is a 1187 few system configuration changes that can make this easier to administrate. 1188 These changes will be detailed here.</p> 1189 <section id="fixed-serial-port-names"> 1190 <h3>Fixed Serial Port Names<a class="headerlink" href="#fixed-serial-port-names" title="Link to this heading">¶</a></h3> 1191 <p>On a Reticulum instance with several serial port based interfaces, it can be 1192 beneficial to use the fixed device names for the serial ports, instead 1193 of the dynamically allocated shorthands such as <code class="docutils literal notranslate"><span class="pre">/dev/ttyUSB0</span></code>. Under most 1194 Debian-based distributions, including Ubuntu and Raspberry Pi OS, these nodes 1195 can be found under <code class="docutils literal notranslate"><span class="pre">/dev/serial/by-id</span></code>.</p> 1196 <p>You can use such a device path directly in place of the numbered shorthands. 1197 Here is an example of a packet radio TNC configured as such:</p> 1198 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>[[Packet Radio KISS Interface]] 1199 type = KISSInterface 1200 interface_enabled = True 1201 outgoing = true 1202 port = /dev/serial/by-id/usb-FTDI_FT230X_Basic_UART_43891CKM-if00-port0 1203 speed = 115200 1204 databits = 8 1205 parity = none 1206 stopbits = 1 1207 preamble = 150 1208 txtail = 10 1209 persistence = 200 1210 slottime = 20 1211 </pre></div> 1212 </div> 1213 <p>Using this methodology avoids potential naming mix-ups where physical devices 1214 might be plugged and unplugged in different orders, or when device name 1215 assignment varies from one boot to another.</p> 1216 </section> 1217 <section id="reticulum-as-a-system-service"> 1218 <span id="using-systemd"></span><h3>Reticulum as a System Service<a class="headerlink" href="#reticulum-as-a-system-service" title="Link to this heading">¶</a></h3> 1219 <p>Instead of starting Reticulum manually, you can install <code class="docutils literal notranslate"><span class="pre">rnsd</span></code> as a system 1220 service and have it start automatically at boot.</p> 1221 <section id="systemwide-service"> 1222 <h4>Systemwide Service<a class="headerlink" href="#systemwide-service" title="Link to this heading">¶</a></h4> 1223 <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 1224 be located in a user-local installation path only, which means <code class="docutils literal notranslate"><span class="pre">systemd</span></code> will not 1225 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 1226 into a directory that is in systemd’s path:</p> 1227 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>sudo ln -s $(which rnsd) /usr/local/bin/ 1228 </pre></div> 1229 </div> 1230 <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 1231 following content:</p> 1232 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>[Unit] 1233 Description=Reticulum Network Stack Daemon 1234 After=multi-user.target 1235 1236 [Service] 1237 # If you run Reticulum on WiFi devices, 1238 # or other devices that need some extra 1239 # time to initialise, you might want to 1240 # add a short delay before Reticulum is 1241 # started by systemd: 1242 # ExecStartPre=/bin/sleep 10 1243 Type=simple 1244 Restart=always 1245 RestartSec=3 1246 User=USERNAMEHERE 1247 ExecStart=rnsd --service 1248 1249 [Install] 1250 WantedBy=multi-user.target 1251 </pre></div> 1252 </div> 1253 <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> 1254 <p>To manually start <code class="docutils literal notranslate"><span class="pre">rnsd</span></code> run:</p> 1255 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>sudo systemctl start rnsd 1256 </pre></div> 1257 </div> 1258 <p>If you want to automatically start <code class="docutils literal notranslate"><span class="pre">rnsd</span></code> at boot, run:</p> 1259 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>sudo systemctl enable rnsd 1260 </pre></div> 1261 </div> 1262 </section> 1263 <section id="userspace-service"> 1264 <h4>Userspace Service<a class="headerlink" href="#userspace-service" title="Link to this heading">¶</a></h4> 1265 <p>Alternatively you can use a user systemd service instead of a system wide one. This way the whole setup can be done as a regular user. 1266 Create a user systemd service files <code class="docutils literal notranslate"><span class="pre">~/.config/systemd/user/rnsd.service</span></code> with the following content:</p> 1267 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>[Unit] 1268 Description=Reticulum Network Stack Daemon 1269 After=default.target 1270 1271 [Service] 1272 # If you run Reticulum on WiFi devices, 1273 # or other devices that need some extra 1274 # time to initialise, you might want to 1275 # add a short delay before Reticulum is 1276 # started by systemd: 1277 # ExecStartPre=/bin/sleep 10 1278 Type=simple 1279 Restart=always 1280 RestartSec=3 1281 ExecStart=RNS_BIN_DIR/rnsd --service 1282 1283 [Install] 1284 WantedBy=default.target 1285 </pre></div> 1286 </div> 1287 <p>Replace <code class="docutils literal notranslate"><span class="pre">RNS_BIN_DIR</span></code> with the path to your Reticulum binary directory (eg. /home/USERNAMEHERE/rns/bin).</p> 1288 <p>Start user service:</p> 1289 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>systemctl --user daemon-reload 1290 systemctl --user start rnsd.service 1291 </pre></div> 1292 </div> 1293 <p>If you want to automatically start <code class="docutils literal notranslate"><span class="pre">rnsd</span></code> without having to log in as the USERNAMEHERE, do:</p> 1294 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>sudo loginctl enable-linger USERNAMEHERE 1295 systemctl --user enable rnsd.service 1296 </pre></div> 1297 </div> 1298 </section> 1299 </section> 1300 </section> 1301 </section> 1302 1303 </article> 1304 </div> 1305 <footer> 1306 1307 <div class="related-pages"> 1308 <a class="next-page" href="understanding.html"> 1309 <div class="page-info"> 1310 <div class="context"> 1311 <span>Next</span> 1312 </div> 1313 <div class="title">Understanding Reticulum</div> 1314 </div> 1315 <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg> 1316 </a> 1317 <a class="prev-page" href="software.html"> 1318 <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg> 1319 <div class="page-info"> 1320 <div class="context"> 1321 <span>Previous</span> 1322 </div> 1323 1324 <div class="title">Programs Using Reticulum</div> 1325 1326 </div> 1327 </a> 1328 </div> 1329 <div class="bottom-of-page"> 1330 <div class="left-details"> 1331 <div class="copyright"> 1332 Copyright © 2025, Mark Qvist 1333 </div> 1334 Generated with <a href="https://www.sphinx-doc.org/">Sphinx</a> and 1335 <a href="https://github.com/pradyunsg/furo">Furo</a> 1336 1337 </div> 1338 <div class="right-details"> 1339 1340 </div> 1341 </div> 1342 1343 </footer> 1344 </div> 1345 <aside class="toc-drawer"> 1346 1347 1348 <div class="toc-sticky toc-scroll"> 1349 <div class="toc-title-container"> 1350 <span class="toc-title"> 1351 On this page 1352 </span> 1353 </div> 1354 <div class="toc-tree-container"> 1355 <div class="toc-tree"> 1356 <ul> 1357 <li><a class="reference internal" href="#">Using Reticulum on Your System</a><ul> 1358 <li><a class="reference internal" href="#configuration-data">Configuration & Data</a></li> 1359 <li><a class="reference internal" href="#included-utility-programs">Included Utility Programs</a><ul> 1360 <li><a class="reference internal" href="#the-rnsd-utility">The rnsd Utility</a></li> 1361 <li><a class="reference internal" href="#the-rnstatus-utility">The rnstatus Utility</a></li> 1362 <li><a class="reference internal" href="#the-rnid-utility">The rnid Utility</a></li> 1363 <li><a class="reference internal" href="#the-rnpath-utility">The rnpath Utility</a></li> 1364 <li><a class="reference internal" href="#the-rnprobe-utility">The rnprobe Utility</a></li> 1365 <li><a class="reference internal" href="#the-rncp-utility">The rncp Utility</a></li> 1366 <li><a class="reference internal" href="#the-rnx-utility">The rnx Utility</a></li> 1367 <li><a class="reference internal" href="#the-rnodeconf-utility">The rnodeconf Utility</a></li> 1368 </ul> 1369 </li> 1370 <li><a class="reference internal" href="#discovering-interfaces">Discovering Interfaces</a></li> 1371 <li><a class="reference internal" href="#remote-management">Remote Management</a></li> 1372 <li><a class="reference internal" href="#blackhole-management">Blackhole Management</a><ul> 1373 <li><a class="reference internal" href="#local-blackhole-management">Local Blackhole Management</a></li> 1374 <li><a class="reference internal" href="#automated-list-sourcing">Automated List Sourcing</a></li> 1375 <li><a class="reference internal" href="#publishing-blackhole-lists">Publishing Blackhole Lists</a></li> 1376 </ul> 1377 </li> 1378 <li><a class="reference internal" href="#improving-system-configuration">Improving System Configuration</a><ul> 1379 <li><a class="reference internal" href="#fixed-serial-port-names">Fixed Serial Port Names</a></li> 1380 <li><a class="reference internal" href="#reticulum-as-a-system-service">Reticulum as a System Service</a><ul> 1381 <li><a class="reference internal" href="#systemwide-service">Systemwide Service</a></li> 1382 <li><a class="reference internal" href="#userspace-service">Userspace Service</a></li> 1383 </ul> 1384 </li> 1385 </ul> 1386 </li> 1387 </ul> 1388 </li> 1389 </ul> 1390 1391 </div> 1392 </div> 1393 </div> 1394 1395 1396 </aside> 1397 </div> 1398 </div><script src="_static/documentation_options.js?v=cb7bf70b"></script> 1399 <script src="_static/doctools.js?v=9bcbadda"></script> 1400 <script src="_static/sphinx_highlight.js?v=dc90522c"></script> 1401 <script src="_static/scripts/furo.js?v=46bd48cc"></script> 1402 <script src="_static/clipboard.min.js?v=a7894cd8"></script> 1403 <script src="_static/copybutton.js?v=f281be69"></script> 1404 </body> 1405 </html>