interfaces.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="Building Networks" href="networks.html"><link rel="prev" title="Communications Hardware" href="hardware.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>Configuring Interfaces - 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"><a class="reference internal" href="using.html">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 current current-page"><a class="current reference internal" href="#">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="configuring-interfaces"> 264 <span id="interfaces-main"></span><h1>Configuring Interfaces<a class="headerlink" href="#configuring-interfaces" title="Link to this heading">¶</a></h1> 265 <p>Reticulum supports using many kinds of devices as networking interfaces, and 266 allows you to mix and match them in any way you choose. The number of distinct 267 network topologies you can create with Reticulum is more or less endless, but 268 common to them all is that you will need to define one or more <em>interfaces</em> 269 for Reticulum to use.</p> 270 <p>The following sections describe the interfaces currently available in Reticulum, 271 and gives example configurations for the respective interface types.</p> 272 <p>For a high-level overview of how networks can be formed over different interface 273 types, have a look at the <a class="reference internal" href="networks.html#networks-main"><span class="std std-ref">Building Networks</span></a> chapter of this 274 manual.</p> 275 <section id="custom-interfaces"> 276 <span id="interfaces-custom"></span><h2>Custom Interfaces<a class="headerlink" href="#custom-interfaces" title="Link to this heading">¶</a></h2> 277 <p>In addition to the built-in interface types, Reticulum is <strong>fully extensible</strong> with 278 custom, user- or community-supplied interfaces, and creating custom interface 279 modules is straightforward. Please see the <a class="reference internal" href="examples.html#example-custominterface"><span class="std std-ref">custom interface</span></a> 280 example for basic interface code to build upon.</p> 281 </section> 282 <section id="auto-interface"> 283 <span id="interfaces-auto"></span><h2>Auto Interface<a class="headerlink" href="#auto-interface" title="Link to this heading">¶</a></h2> 284 <p>The <code class="docutils literal notranslate"><span class="pre">AutoInterface</span></code> enables communication with other discoverable Reticulum 285 nodes over any kind of local Ethernet or WiFi-based medium. Even though it uses IPv6 for peer 286 discovery, and UDP for packet transport, it <strong>does not</strong> need any functional IP 287 infrastructure like routers or DHCP servers, on your physical network.</p> 288 <div class="admonition warning"> 289 <p class="admonition-title">Warning</p> 290 <p>If you have <strong>firewall</strong> software running on your computer, it may block traffic 291 required for <code class="docutils literal notranslate"><span class="pre">AutoInterface</span></code> to work. If this is the case, you will have to 292 allow UDP traffic on port <code class="docutils literal notranslate"><span class="pre">29716</span></code> and <code class="docutils literal notranslate"><span class="pre">42671</span></code>.</p> 293 </div> 294 <p>As long as there is at least some sort of switching medium present between peers (a 295 wired switch, a hub, a WiFi access point or similar, or simply two devices connected 296 directly by Ethernet cable), it will work without any configuration, setup or intermediary devices.</p> 297 <p>For <code class="docutils literal notranslate"><span class="pre">AutoInterface</span></code> peer discovery to work, it’s also required that link-local 298 IPv6 support is available on your system, which it should be by default in all 299 current operating systems, both desktop and mobile.</p> 300 <div class="admonition note"> 301 <p class="admonition-title">Note</p> 302 <p>Almost all current Ethernet and WiFi hardware will work without any kind 303 of configuration or setup with <code class="docutils literal notranslate"><span class="pre">AutoInterface</span></code>, but a small subset of 304 devices turn on options that limit device-to-device communication by default, 305 resulting in <code class="docutils literal notranslate"><span class="pre">AutoInterface</span></code> peer discovery being blocked. This issue is 306 most commonly seen on very cheap, ISP-supplied WiFi routers, and can sometimes 307 be turned off in the router configuration.</p> 308 </div> 309 <div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="c1"># This example demonstrates a bare-minimum setup</span> 310 <span class="c1"># of an Auto Interface. It will allow communica-</span> 311 <span class="c1"># tion with all other reachable devices on all</span> 312 <span class="c1"># usable physical ethernet-based devices that</span> 313 <span class="c1"># are available on the system.</span> 314 <span class="k">[[Default Interface]]</span> 315 <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> 316 <span class="w"> </span><span class="na">enabled</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span> 317 318 <span class="c1"># This example demonstrates an more specifically</span> 319 <span class="c1"># configured Auto Interface, that only uses spe-</span> 320 <span class="c1"># cific physical interfaces, and has a number of</span> 321 <span class="c1"># other configuration options set.</span> 322 <span class="k">[[Default Interface]]</span> 323 <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> 324 <span class="w"> </span><span class="na">enabled</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span> 325 326 <span class="w"> </span><span class="c1"># You can create multiple isolated Reticulum</span> 327 <span class="w"> </span><span class="c1"># networks on the same physical LAN by</span> 328 <span class="w"> </span><span class="c1"># specifying different Group IDs.</span> 329 <span class="w"> </span><span class="na">group_id</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">reticulum</span> 330 331 <span class="w"> </span><span class="c1"># You can also choose the multicast address type:</span> 332 <span class="w"> </span><span class="c1"># temporary (default, Temporary Multicast Address)</span> 333 <span class="w"> </span><span class="c1"># or permanent (Permanent Multicast Address)</span> 334 <span class="w"> </span><span class="na">multicast_address_type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">permanent</span> 335 336 <span class="w"> </span><span class="c1"># You can also select specifically which</span> 337 <span class="w"> </span><span class="c1"># kernel networking devices to use.</span> 338 <span class="w"> </span><span class="na">devices</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">wlan0,eth1</span> 339 340 <span class="w"> </span><span class="c1"># Or let AutoInterface use all suitable</span> 341 <span class="w"> </span><span class="c1"># devices except for a list of ignored ones.</span> 342 <span class="w"> </span><span class="na">ignored_devices</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">tun0,eth0</span> 343 </pre></div> 344 </div> 345 <p>If you are connected to the Internet with IPv6, and your provider will route 346 IPv6 multicast, you can potentially configure the Auto Interface to globally 347 autodiscover other Reticulum nodes within your selected Group ID. You can specify 348 the discovery scope by setting it to one of <code class="docutils literal notranslate"><span class="pre">link</span></code>, <code class="docutils literal notranslate"><span class="pre">admin</span></code>, <code class="docutils literal notranslate"><span class="pre">site</span></code>, 349 <code class="docutils literal notranslate"><span class="pre">organisation</span></code> or <code class="docutils literal notranslate"><span class="pre">global</span></code>.</p> 350 <div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[[Default Interface]]</span> 351 <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> 352 <span class="w"> </span><span class="na">enabled</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span> 353 354 <span class="w"> </span><span class="c1"># Configure global discovery</span> 355 356 <span class="w"> </span><span class="na">group_id</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">custom_network_name</span> 357 <span class="w"> </span><span class="na">discovery_scope</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">global</span> 358 359 <span class="w"> </span><span class="c1"># Other configuration options</span> 360 361 <span class="w"> </span><span class="na">discovery_port</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">48555</span> 362 <span class="w"> </span><span class="na">data_port</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">49555</span> 363 </pre></div> 364 </div> 365 </section> 366 <section id="backbone-interface"> 367 <span id="interfaces-backbone"></span><h2>Backbone Interface<a class="headerlink" href="#backbone-interface" title="Link to this heading">¶</a></h2> 368 <p>The Backbone interface is a very fast and resource efficient interface type, primarily 369 intended for interconnecting Reticulum instances over many different types of mediums. 370 It uses a kernel-event I/O backend, and can handle thousands of interfaces and/or clients 371 with relatively low system resource utilisation. <strong>This interface type is currently only 372 supported on Linux and Android</strong>.</p> 373 <div class="admonition note"> 374 <p class="admonition-title">Note</p> 375 <p>The Backbone Interface is fully compatible with the <code class="docutils literal notranslate"><span class="pre">TCPServerInterface</span></code> and <code class="docutils literal notranslate"><span class="pre">TCPClientInterface</span></code> 376 types, and they can be used interchangably, and cross-connect with each other. On systems that support 377 <code class="docutils literal notranslate"><span class="pre">BackboneInterface</span></code>, it is generally recommended to use it, unless you need specific options or 378 features that the TCP server and client interfaces provide.</p> 379 </div> 380 <p>While the goal is to support <em>all</em> socket types and I/O devices provided by the underlying 381 operating system, the initial release only provides support for TCP connections over IPv4 382 and IPv6.</p> 383 <p>For all types of connections over a <code class="docutils literal notranslate"><span class="pre">BackboneInterface</span></code>, Reticulum will gracefully 384 handle intermittency, link loss, and connections that come and go.</p> 385 <section id="listeners"> 386 <h3>Listeners<a class="headerlink" href="#listeners" title="Link to this heading">¶</a></h3> 387 <p>The following examples illustrates various ways to set up <code class="docutils literal notranslate"><span class="pre">BackboneInterface</span></code> listeners.</p> 388 <div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="c1"># This example demonstrates a backbone interface</span> 389 <span class="c1"># that listens for incoming connections on the</span> 390 <span class="c1"># specified IP address and port number.</span> 391 <span class="k">[[Backbone Listener]]</span> 392 <span class="w"> </span><span class="na">type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">BackboneInterface</span> 393 <span class="w"> </span><span class="na">enabled</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span> 394 <span class="w"> </span><span class="na">listen_on</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">0.0.0.0</span> 395 <span class="w"> </span><span class="na">port</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">4242</span> 396 397 <span class="c1"># Alternatively you can bind to a specific IP</span> 398 <span class="k">[[Backbone Listener]]</span> 399 <span class="w"> </span><span class="na">type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">BackboneInterface</span> 400 <span class="w"> </span><span class="na">enabled</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span> 401 <span class="w"> </span><span class="na">listen_on</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">10.0.0.88</span> 402 <span class="w"> </span><span class="na">port</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">4242</span> 403 404 <span class="c1"># Or a specific network device</span> 405 <span class="k">[[Backbone Listener]]</span> 406 <span class="w"> </span><span class="na">type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">BackboneInterface</span> 407 <span class="w"> </span><span class="na">enabled</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span> 408 <span class="w"> </span><span class="na">device</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">eth0</span> 409 <span class="w"> </span><span class="na">port</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">4242</span> 410 </pre></div> 411 </div> 412 <p>If you are using the interface on a device which has both IPv4 and IPv6 addresses available, 413 you can use the <code class="docutils literal notranslate"><span class="pre">prefer_ipv6</span></code> option to bind to the IPv6 address:</p> 414 <div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="c1"># This example demonstrates a backbone interface</span> 415 <span class="c1"># listening on the IPv6 address of a specified</span> 416 <span class="c1"># kernel networking device.</span> 417 <span class="k">[[Backbone Listener]]</span> 418 <span class="w"> </span><span class="na">type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">BackboneInterface</span> 419 <span class="w"> </span><span class="na">enabled</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span> 420 <span class="w"> </span><span class="na">prefer_ipv6</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span> 421 <span class="w"> </span><span class="na">device</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">eth0</span> 422 <span class="w"> </span><span class="na">port</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">4242</span> 423 </pre></div> 424 </div> 425 <p>To use the <code class="docutils literal notranslate"><span class="pre">BackboneInterface</span></code> over <a class="reference external" href="https://yggdrasil-network.github.io/">Yggdrasil</a>, you 426 can simply specify the Yggdrasil <code class="docutils literal notranslate"><span class="pre">tun</span></code> device and a listening port, like so:</p> 427 <div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="c1"># This example demonstrates a backbone interface</span> 428 <span class="c1"># listening for connections over Yggdrasil.</span> 429 <span class="k">[[Yggdrasil Backbone Interface]]</span> 430 <span class="w"> </span><span class="na">type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">BackboneInterface</span> 431 <span class="w"> </span><span class="na">enabled</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span> 432 <span class="w"> </span><span class="na">device</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">tun0</span> 433 <span class="w"> </span><span class="na">port</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">4343</span> 434 </pre></div> 435 </div> 436 </section> 437 <section id="connecting-remotes"> 438 <h3>Connecting Remotes<a class="headerlink" href="#connecting-remotes" title="Link to this heading">¶</a></h3> 439 <p>The following examples illustrates various ways to connect to remote <code class="docutils literal notranslate"><span class="pre">BackboneInterface</span></code> listeners. 440 As noted above, <code class="docutils literal notranslate"><span class="pre">BackboneInterface</span></code> interfaces can also connect to remote <code class="docutils literal notranslate"><span class="pre">TCPServerInterface</span></code>, 441 and as such these interface types can be used interchangably.</p> 442 <div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="c1"># Here's an example of a backbone interface that</span> 443 <span class="c1"># connects to a remote listener.</span> 444 <span class="k">[[Backbone Remote]]</span> 445 <span class="w"> </span><span class="na">type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">BackboneInterface</span> 446 <span class="w"> </span><span class="na">enabled</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span> 447 <span class="w"> </span><span class="na">remote</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">amsterdam.connect.reticulum.network</span> 448 <span class="w"> </span><span class="na">target_port</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">4251</span> 449 </pre></div> 450 </div> 451 <p>To connect to remotes over <a class="reference external" href="https://yggdrasil-network.github.io/">Yggdrasil</a>, simply 452 specify the target Yggdrasil IPv6 address and port, like so:</p> 453 <div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[[Yggdrasil Remote]]</span> 454 <span class="w"> </span><span class="na">type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">BackboneInterface</span> 455 <span class="w"> </span><span class="na">enabled</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span> 456 <span class="w"> </span><span class="na">target_host</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">201:5d78:af73:5caf:a4de:a79f:3278:71e5</span> 457 <span class="w"> </span><span class="na">target_port</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">4343</span> 458 </pre></div> 459 </div> 460 </section> 461 </section> 462 <section id="tcp-server-interface"> 463 <span id="interfaces-tcps"></span><h2>TCP Server Interface<a class="headerlink" href="#tcp-server-interface" title="Link to this heading">¶</a></h2> 464 <p>The TCP Server interface is suitable for allowing other peers to connect over 465 the Internet or private IPv4 and IPv6 networks. When a TCP server interface has been 466 configured, other Reticulum peers can connect to it with a TCP Client interface.</p> 467 <div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="c1"># This example demonstrates a TCP server interface.</span> 468 <span class="c1"># It will listen for incoming connections on all IP</span> 469 <span class="c1"># interfaces on port 4242.</span> 470 <span class="k">[[TCP Server Interface]]</span> 471 <span class="w"> </span><span class="na">type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">TCPServerInterface</span> 472 <span class="w"> </span><span class="na">enabled</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span> 473 <span class="w"> </span><span class="na">listen_ip</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">0.0.0.0</span> 474 <span class="w"> </span><span class="na">listen_port</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">4242</span> 475 476 <span class="c1"># Alternatively you can bind to a specific IP</span> 477 <span class="k">[[TCP Server Interface]]</span> 478 <span class="w"> </span><span class="na">type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">TCPServerInterface</span> 479 <span class="w"> </span><span class="na">enabled</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span> 480 <span class="w"> </span><span class="na">listen_ip</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">10.0.0.88</span> 481 <span class="w"> </span><span class="na">listen_port</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">4242</span> 482 483 <span class="c1"># Or a specific network device</span> 484 <span class="k">[[TCP Server Interface]]</span> 485 <span class="w"> </span><span class="na">type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">TCPServerInterface</span> 486 <span class="w"> </span><span class="na">enabled</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span> 487 <span class="w"> </span><span class="na">device</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">eth0</span> 488 <span class="w"> </span><span class="na">listen_port</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">4242</span> 489 </pre></div> 490 </div> 491 <p>If you are using the interface on a device which has both IPv4 and IPv6 addresses available, 492 you can use the <code class="docutils literal notranslate"><span class="pre">prefer_ipv6</span></code> option to bind to the IPv6 address:</p> 493 <div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="c1"># This example demonstrates a TCP server interface.</span> 494 <span class="c1"># It will listen for incoming connections on the</span> 495 <span class="c1"># specified IP address and port number.</span> 496 497 <span class="k">[[TCP Server Interface]]</span> 498 <span class="w"> </span><span class="na">type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">TCPServerInterface</span> 499 <span class="w"> </span><span class="na">enabled</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span> 500 <span class="w"> </span><span class="na">prefer_ipv6</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">True</span> 501 <span class="w"> </span><span class="na">device</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">eth0</span> 502 <span class="w"> </span><span class="na">port</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">4242</span> 503 </pre></div> 504 </div> 505 <p>To use the TCP Server Interface over <a class="reference external" href="https://yggdrasil-network.github.io/">Yggdrasil</a>, you 506 can simply specify the Yggdrasil <code class="docutils literal notranslate"><span class="pre">tun</span></code> device and a listening port, like so:</p> 507 <div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[[Yggdrasil TCP Server Interface]]</span> 508 <span class="w"> </span><span class="na">type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">TCPServerInterface</span> 509 <span class="w"> </span><span class="na">enabled</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span> 510 <span class="w"> </span><span class="na">device</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">tun0</span> 511 <span class="w"> </span><span class="na">listen_port</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">4343</span> 512 </pre></div> 513 </div> 514 <div class="admonition note"> 515 <p class="admonition-title">Note</p> 516 <p>The TCP interfaces support tunneling over I2P, but to do so reliably, 517 you must use the i2p_tunneled option:</p> 518 </div> 519 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">TCP</span> <span class="n">Server</span> <span class="n">on</span> <span class="n">I2P</span><span class="p">]]</span> 520 <span class="nb">type</span> <span class="o">=</span> <span class="n">TCPServerInterface</span> 521 <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span> 522 <span class="n">listen_ip</span> <span class="o">=</span> <span class="mf">127.0.0.1</span> 523 <span class="n">listen_port</span> <span class="o">=</span> <span class="mi">5001</span> 524 <span class="n">i2p_tunneled</span> <span class="o">=</span> <span class="n">yes</span> 525 </pre></div> 526 </div> 527 <p>In almost all cases, it is easier to use the dedicated <code class="docutils literal notranslate"><span class="pre">I2PInterface</span></code>, but for complete 528 control, and using I2P routers running on external systems, this option also exists.</p> 529 </section> 530 <section id="tcp-client-interface"> 531 <span id="interfaces-tcpc"></span><h2>TCP Client Interface<a class="headerlink" href="#tcp-client-interface" title="Link to this heading">¶</a></h2> 532 <p>To connect to a TCP server interface, you can use the TCP client 533 interface. Many TCP Client interfaces from different peers can connect to the 534 same TCP Server interface at the same time.</p> 535 <p>The TCP interface types can also tolerate intermittency in the IP link layer. 536 This means that Reticulum will gracefully handle IP links that go up and down, 537 and restore connectivity after a failure, once the other end of a TCP interface reappears.</p> 538 <div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="c1"># Here's an example of a TCP Client interface. The</span> 539 <span class="c1"># target_host can be a hostname or an IPv4 or IPv6 address.</span> 540 <span class="k">[[TCP Client Interface]]</span> 541 <span class="w"> </span><span class="na">type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">TCPClientInterface</span> 542 <span class="w"> </span><span class="na">enabled</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span> 543 <span class="w"> </span><span class="na">target_host</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">127.0.0.1</span> 544 <span class="w"> </span><span class="na">target_port</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">4242</span> 545 </pre></div> 546 </div> 547 <p>To use the TCP Client Interface over <a class="reference external" href="https://yggdrasil-network.github.io/">Yggdrasil</a>, simply 548 specify the target Yggdrasil IPv6 address and port, like so:</p> 549 <div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[[Yggdrasil TCP Client Interface]]</span> 550 <span class="w"> </span><span class="na">type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">TCPClientInterface</span> 551 <span class="w"> </span><span class="na">enabled</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span> 552 <span class="w"> </span><span class="na">target_host</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">201:5d78:af73:5caf:a4de:a79f:3278:71e5</span> 553 <span class="w"> </span><span class="na">target_port</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">4343</span> 554 </pre></div> 555 </div> 556 <p>It is also possible to use this interface type to connect via other programs 557 or hardware devices that expose a KISS interface on a TCP port, for example 558 software-based soundmodems. To do this, use the <code class="docutils literal notranslate"><span class="pre">kiss_framing</span></code> option:</p> 559 <div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="c1"># Here's an example of a TCP Client interface that connects</span> 560 <span class="c1"># to a software TNC soundmodem on a KISS over TCP port.</span> 561 562 <span class="k">[[TCP KISS Interface]]</span> 563 <span class="w"> </span><span class="na">type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">TCPClientInterface</span> 564 <span class="w"> </span><span class="na">enabled</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span> 565 <span class="w"> </span><span class="na">kiss_framing</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">True</span> 566 <span class="w"> </span><span class="na">target_host</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">127.0.0.1</span> 567 <span class="w"> </span><span class="na">target_port</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">8001</span> 568 <span class="w"> </span><span class="na">fixed_mtu</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">500</span> 569 </pre></div> 570 </div> 571 <p><strong>Caution!</strong> Only use the KISS framing option when connecting to external devices 572 and programs like soundmodems and similar over TCP. When using the 573 <code class="docutils literal notranslate"><span class="pre">TCPClientInterface</span></code> in conjunction with the <code class="docutils literal notranslate"><span class="pre">TCPServerInterface</span></code> you should 574 never enable <code class="docutils literal notranslate"><span class="pre">kiss_framing</span></code>, since this will disable internal reliability and 575 recovery mechanisms that greatly improves performance over unreliable and 576 intermittent TCP links.</p> 577 <p>For KISS devices that need only supports a particular MTU, you can use the 578 <code class="docutils literal notranslate"><span class="pre">fixed_mtu</span></code> option.</p> 579 <div class="admonition note"> 580 <p class="admonition-title">Note</p> 581 <p>The TCP interfaces support tunneling over I2P, but to do so reliably, 582 you must use the i2p_tunneled option:</p> 583 </div> 584 <div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[[TCP Client over I2P]]</span> 585 <span class="w"> </span><span class="na">type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">TCPClientInterface</span> 586 <span class="w"> </span><span class="na">enabled</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span> 587 <span class="w"> </span><span class="na">target_host</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">127.0.0.1</span> 588 <span class="w"> </span><span class="na">target_port</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">5001</span> 589 <span class="w"> </span><span class="na">i2p_tunneled</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span> 590 </pre></div> 591 </div> 592 </section> 593 <section id="udp-interface"> 594 <span id="interfaces-udp"></span><h2>UDP Interface<a class="headerlink" href="#udp-interface" title="Link to this heading">¶</a></h2> 595 <p>A UDP interface can be useful for communicating over IP networks, both 596 private and the internet. It can also allow broadcast communication 597 over IP networks, so it can provide an easy way to enable connectivity 598 with all other peers on a local area network.</p> 599 <div class="admonition warning"> 600 <p class="admonition-title">Warning</p> 601 <p>Using broadcast UDP traffic has performance implications, 602 especially on WiFi. If your goal is simply to enable easy communication 603 with all peers in your local Ethernet broadcast domain, the 604 <a class="reference internal" href="#interfaces-auto"><span class="std std-ref">Auto Interface</span></a> performs <em>much</em> better, and is even 605 easier to use.</p> 606 </div> 607 <div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="c1"># This example enables communication with other</span> 608 <span class="c1"># local Reticulum peers over UDP.</span> 609 610 <span class="k">[[UDP Interface]]</span> 611 <span class="w"> </span><span class="na">type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">UDPInterface</span> 612 <span class="w"> </span><span class="na">enabled</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span> 613 614 <span class="w"> </span><span class="na">listen_ip</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">0.0.0.0</span> 615 <span class="w"> </span><span class="na">listen_port</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">4242</span> 616 <span class="w"> </span><span class="na">forward_ip</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">255.255.255.255</span> 617 <span class="w"> </span><span class="na">forward_port</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">4242</span> 618 619 <span class="w"> </span><span class="c1"># The above configuration will allow communication</span> 620 <span class="w"> </span><span class="c1"># within the local broadcast domains of all local</span> 621 <span class="w"> </span><span class="c1"># IP interfaces.</span> 622 623 <span class="w"> </span><span class="c1"># Instead of specifying listen_ip, listen_port,</span> 624 <span class="w"> </span><span class="c1"># forward_ip and forward_port, you can also bind</span> 625 <span class="w"> </span><span class="c1"># to a specific network device like below.</span> 626 627 <span class="w"> </span><span class="c1"># device = eth0</span> 628 <span class="w"> </span><span class="c1"># port = 4242</span> 629 630 <span class="w"> </span><span class="c1"># Assuming the eth0 device has the address</span> 631 <span class="w"> </span><span class="c1"># 10.55.0.72/24, the above configuration would</span> 632 <span class="w"> </span><span class="c1"># be equivalent to the following manual setup.</span> 633 <span class="w"> </span><span class="c1"># Note that we are both listening and forwarding to</span> 634 <span class="w"> </span><span class="c1"># the broadcast address of the network segments.</span> 635 636 <span class="w"> </span><span class="c1"># listen_ip = 10.55.0.255</span> 637 <span class="w"> </span><span class="c1"># listen_port = 4242</span> 638 <span class="w"> </span><span class="c1"># forward_ip = 10.55.0.255</span> 639 <span class="w"> </span><span class="c1"># forward_port = 4242</span> 640 641 <span class="w"> </span><span class="c1"># You can of course also communicate only with</span> 642 <span class="w"> </span><span class="c1"># a single IP address</span> 643 644 <span class="w"> </span><span class="c1"># listen_ip = 10.55.0.15</span> 645 <span class="w"> </span><span class="c1"># listen_port = 4242</span> 646 <span class="w"> </span><span class="c1"># forward_ip = 10.55.0.16</span> 647 <span class="w"> </span><span class="c1"># forward_port = 4242</span> 648 </pre></div> 649 </div> 650 </section> 651 <section id="i2p-interface"> 652 <span id="interfaces-i2p"></span><h2>I2P Interface<a class="headerlink" href="#i2p-interface" title="Link to this heading">¶</a></h2> 653 <p>The I2P interface lets you connect Reticulum instances over the 654 <a class="reference external" href="https://i2pd.website">Invisible Internet Protocol</a>. This can be 655 especially useful in cases where you want to host a globally reachable 656 Reticulum instance, but do not have access to any public IP addresses, 657 have a frequently changing IP address, or have firewalls blocking 658 inbound traffic.</p> 659 <p>Using the I2P interface, you will get a globally reachable, portable 660 and persistent I2P address that your Reticulum instance can be reached 661 at.</p> 662 <p>To use the I2P interface, you must have an I2P router running 663 on your system. The easiest way to achieve this is to download and 664 install the <a class="reference external" href="https://github.com/PurpleI2P/i2pd/releases/latest">latest release</a> 665 of the <code class="docutils literal notranslate"><span class="pre">i2pd</span></code> package. For more details about I2P, see the 666 <a class="reference external" href="https://geti2p.net/en/about/intro">geti2p.net website</a>.</p> 667 <p>When an I2P router is running on your system, you can simply add 668 an I2P interface to Reticulum:</p> 669 <div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[[I2P]]</span> 670 <span class="w"> </span><span class="na">type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">I2PInterface</span> 671 <span class="w"> </span><span class="na">enabled</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span> 672 <span class="w"> </span><span class="na">connectable</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span> 673 </pre></div> 674 </div> 675 <p>On the first start, Reticulum will generate a new I2P address for the 676 interface and start listening for inbound traffic on it. This can take 677 a while the first time, especially if your I2P router was also just 678 started, and is not yet well-connected to the I2P network. When ready, 679 you should see I2P base32 address printed to your log file. You can 680 also inspect the status of the interface using the <code class="docutils literal notranslate"><span class="pre">rnstatus</span></code> utility.</p> 681 <p>To connect to other Reticulum instances over I2P, just add a comma-separated 682 list of I2P base32 addresses to the <code class="docutils literal notranslate"><span class="pre">peers</span></code> option of the interface:</p> 683 <div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[[I2P]]</span> 684 <span class="w"> </span><span class="na">type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">I2PInterface</span> 685 <span class="w"> </span><span class="na">enabled</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span> 686 <span class="w"> </span><span class="na">connectable</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span> 687 <span class="w"> </span><span class="na">peers</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">5urvjicpzi7q3ybztsef4i5ow2aq4soktfj7zedz53s47r54jnqq.b32.i2p</span> 688 </pre></div> 689 </div> 690 <p>It can take anywhere from a few seconds to a few minutes to establish 691 I2P connections to the desired peers, so Reticulum handles the process 692 in the background, and will output relevant events to the log.</p> 693 <div class="admonition note"> 694 <p class="admonition-title">Note</p> 695 <p>While the I2P interface is the simplest way to use 696 Reticulum over I2P, it is also possible to tunnel the TCP server and 697 client interfaces over I2P manually. This can be useful in situations 698 where more control is needed, but requires manual tunnel setup through 699 the I2P daemon configuration.</p> 700 </div> 701 <p>It is important to note that the two methods are <em>interchangably compatible</em>. 702 You can use the I2PInterface to connect to a TCPServerInterface that 703 was manually tunneled over I2P, for example. This offers a high degree 704 of flexibility in network setup, while retaining ease of use in simpler 705 use-cases.</p> 706 </section> 707 <section id="rnode-lora-interface"> 708 <span id="interfaces-rnode"></span><h2>RNode LoRa Interface<a class="headerlink" href="#rnode-lora-interface" title="Link to this heading">¶</a></h2> 709 <p>To use Reticulum over LoRa, the <a class="reference external" href="https://unsigned.io/rnode/">RNode</a> interface 710 can be used, and offers full control over LoRa parameters.</p> 711 <div class="admonition warning"> 712 <p class="admonition-title">Warning</p> 713 <p>Radio frequency spectrum is a legally controlled resource, and legislation 714 varies widely around the world. It is your responsibility to be aware of any 715 relevant regulation for your location, and to make decisions accordingly.</p> 716 </div> 717 <div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="c1"># Here's an example of how to add a LoRa interface</span> 718 <span class="c1"># using the RNode LoRa transceiver.</span> 719 720 <span class="k">[[RNode LoRa Interface]]</span> 721 <span class="w"> </span><span class="na">type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">RNodeInterface</span> 722 723 <span class="w"> </span><span class="c1"># Enable interface if you want use it!</span> 724 <span class="w"> </span><span class="na">enabled</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span> 725 726 <span class="w"> </span><span class="c1"># Serial port for the device</span> 727 <span class="w"> </span><span class="na">port</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">/dev/ttyUSB0</span> 728 729 <span class="w"> </span><span class="c1"># You can connect wirelessly to the</span> 730 <span class="w"> </span><span class="c1"># RNode device if it supports WiFi.</span> 731 732 <span class="w"> </span><span class="c1"># Connect by IP address</span> 733 <span class="w"> </span><span class="c1"># port = tcp://10.0.0.1</span> 734 735 <span class="w"> </span><span class="c1"># Or, connect by hostname</span> 736 <span class="w"> </span><span class="c1"># port = tcp://rnodef3b9.local</span> 737 738 <span class="w"> </span><span class="c1"># It is also possible to use BLE devices</span> 739 <span class="w"> </span><span class="c1"># instead of wired serial ports. The</span> 740 <span class="w"> </span><span class="c1"># target RNode must be paired with the</span> 741 <span class="w"> </span><span class="c1"># host device before connecting. BLE</span> 742 <span class="w"> </span><span class="c1"># devices can be connected by name,</span> 743 <span class="w"> </span><span class="c1"># BLE MAC address or by any available.</span> 744 745 <span class="w"> </span><span class="c1"># Connect to specific device by name</span> 746 <span class="w"> </span><span class="c1"># port = ble://RNode 3B87</span> 747 748 <span class="w"> </span><span class="c1"># Or by BLE MAC address</span> 749 <span class="w"> </span><span class="c1"># port = ble://F4:12:73:29:4E:89</span> 750 751 <span class="w"> </span><span class="c1"># Or connect to the first available,</span> 752 <span class="w"> </span><span class="c1"># paired device</span> 753 <span class="w"> </span><span class="c1"># port = ble://</span> 754 755 <span class="w"> </span><span class="c1"># Set frequency to 867.2 MHz</span> 756 <span class="w"> </span><span class="na">frequency</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">867200000</span> 757 758 <span class="w"> </span><span class="c1"># Set LoRa bandwidth to 125 KHz</span> 759 <span class="w"> </span><span class="na">bandwidth</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">125000</span> 760 761 <span class="w"> </span><span class="c1"># Set TX power to 7 dBm (5 mW)</span> 762 <span class="w"> </span><span class="na">txpower</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">7</span> 763 764 <span class="w"> </span><span class="c1"># Select spreading factor 8. Valid</span> 765 <span class="w"> </span><span class="c1"># range is 7 through 12, with 7</span> 766 <span class="w"> </span><span class="c1"># being the fastest and 12 having</span> 767 <span class="w"> </span><span class="c1"># the longest range.</span> 768 <span class="w"> </span><span class="na">spreadingfactor</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">8</span> 769 770 <span class="w"> </span><span class="c1"># Select coding rate 5. Valid range</span> 771 <span class="w"> </span><span class="c1"># is 5 throough 8, with 5 being the</span> 772 <span class="w"> </span><span class="c1"># fastest, and 8 the longest range.</span> 773 <span class="w"> </span><span class="na">codingrate</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">5</span> 774 775 <span class="w"> </span><span class="c1"># You can configure the RNode to send</span> 776 <span class="w"> </span><span class="c1"># out identification on the channel with</span> 777 <span class="w"> </span><span class="c1"># a set interval by configuring the</span> 778 <span class="w"> </span><span class="c1"># following two parameters.</span> 779 780 <span class="w"> </span><span class="c1"># id_callsign = MYCALL-0</span> 781 <span class="w"> </span><span class="c1"># id_interval = 600</span> 782 783 <span class="w"> </span><span class="c1"># For certain homebrew RNode interfaces</span> 784 <span class="w"> </span><span class="c1"># with low amounts of RAM, using packet</span> 785 <span class="w"> </span><span class="c1"># flow control can be useful. By default</span> 786 <span class="w"> </span><span class="c1"># it is disabled.</span> 787 788 <span class="w"> </span><span class="c1"># flow_control = False</span> 789 790 <span class="w"> </span><span class="c1"># It is possible to limit the airtime</span> 791 <span class="w"> </span><span class="c1"># utilisation of an RNode by using the</span> 792 <span class="w"> </span><span class="c1"># following two configuration options.</span> 793 <span class="w"> </span><span class="c1"># The short-term limit is applied in a</span> 794 <span class="w"> </span><span class="c1"># window of approximately 15 seconds,</span> 795 <span class="w"> </span><span class="c1"># and the long-term limit is enforced</span> 796 <span class="w"> </span><span class="c1"># over a rolling 60 minute window. Both</span> 797 <span class="w"> </span><span class="c1"># options are specified in percent.</span> 798 799 <span class="w"> </span><span class="c1"># airtime_limit_long = 1.5</span> 800 <span class="w"> </span><span class="c1"># airtime_limit_short = 33</span> 801 </pre></div> 802 </div> 803 </section> 804 <section id="rnode-multi-interface"> 805 <span id="interfaces-rnode-multi"></span><h2>RNode Multi Interface<a class="headerlink" href="#rnode-multi-interface" title="Link to this heading">¶</a></h2> 806 <p>For RNodes that support multiple LoRa transceivers, the RNode 807 Multi interface can be used to configure sub-interfaces individually.</p> 808 <div class="admonition warning"> 809 <p class="admonition-title">Warning</p> 810 <p>Radio frequency spectrum is a legally controlled resource, and legislation 811 varies widely around the world. It is your responsibility to be aware of any 812 relevant regulation for your location, and to make decisions accordingly.</p> 813 </div> 814 <div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="c1"># Here's an example of how to add an RNode Multi interface</span> 815 <span class="c1"># using the RNode LoRa transceiver.</span> 816 817 <span class="k">[[RNode Multi Interface]]</span> 818 <span class="na">type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">RNodeMultiInterface</span> 819 820 <span class="c1"># Enable interface if you want to use it!</span> 821 <span class="na">enabled</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span> 822 823 <span class="c1"># Serial port for the device</span> 824 <span class="na">port</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">/dev/ttyACM0</span> 825 826 <span class="c1"># You can configure the RNode to send</span> 827 <span class="c1"># out identification on the channel with</span> 828 <span class="c1"># a set interval by configuring the</span> 829 <span class="c1"># following two parameters.</span> 830 831 <span class="c1"># id_callsign = MYCALL-0</span> 832 <span class="c1"># id_interval = 600</span> 833 834 <span class="w"> </span><span class="c1"># A subinterface</span> 835 <span class="w"> </span><span class="k">[[[High Datarate]]]</span> 836 <span class="w"> </span><span class="c1"># Subinterfaces can be enabled and disabled in of themselves</span> 837 <span class="w"> </span><span class="na">enabled</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span> 838 839 <span class="w"> </span><span class="c1"># Set frequency to 2.4GHz</span> 840 <span class="w"> </span><span class="na">frequency</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">2400000000</span> 841 842 <span class="w"> </span><span class="c1"># Set LoRa bandwidth to 1625 KHz</span> 843 <span class="w"> </span><span class="na">bandwidth</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">1625000</span> 844 845 <span class="w"> </span><span class="c1"># Set TX power to 0 dBm (0.12 mW)</span> 846 <span class="w"> </span><span class="na">txpower</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">0</span> 847 848 <span class="w"> </span><span class="c1"># The virtual port, only the manufacturer</span> 849 <span class="w"> </span><span class="c1"># or the person who wrote the board config</span> 850 <span class="w"> </span><span class="c1"># can tell you what it will be for which</span> 851 <span class="w"> </span><span class="c1"># physical hardware interface</span> 852 <span class="w"> </span><span class="na">vport</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">1</span> 853 854 <span class="w"> </span><span class="c1"># Select spreading factor 5. Valid</span> 855 <span class="w"> </span><span class="c1"># range is 5 through 12, with 5</span> 856 <span class="w"> </span><span class="c1"># being the fastest and 12 having</span> 857 <span class="w"> </span><span class="c1"># the longest range.</span> 858 <span class="w"> </span><span class="na">spreadingfactor</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">5</span> 859 860 <span class="w"> </span><span class="c1"># Select coding rate 5. Valid range</span> 861 <span class="w"> </span><span class="c1"># is 5 throough 8, with 5 being the</span> 862 <span class="w"> </span><span class="c1"># fastest, and 8 the longest range.</span> 863 <span class="w"> </span><span class="na">codingrate</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">5</span> 864 865 <span class="w"> </span><span class="c1"># It is possible to limit the airtime</span> 866 <span class="w"> </span><span class="c1"># utilisation of an RNode by using the</span> 867 <span class="w"> </span><span class="c1"># following two configuration options.</span> 868 <span class="w"> </span><span class="c1"># The short-term limit is applied in a</span> 869 <span class="w"> </span><span class="c1"># window of approximately 15 seconds,</span> 870 <span class="w"> </span><span class="c1"># and the long-term limit is enforced</span> 871 <span class="w"> </span><span class="c1"># over a rolling 60 minute window. Both</span> 872 <span class="w"> </span><span class="c1"># options are specified in percent.</span> 873 874 <span class="w"> </span><span class="c1"># airtime_limit_long = 100</span> 875 <span class="w"> </span><span class="c1"># airtime_limit_short = 100</span> 876 877 <span class="w"> </span><span class="k">[[[Low Datarate]]]</span> 878 <span class="w"> </span><span class="c1"># Subinterfaces can be enabled and disabled in of themselves</span> 879 <span class="w"> </span><span class="na">enabled</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span> 880 881 <span class="w"> </span><span class="c1"># Set frequency to 865.6 MHz</span> 882 <span class="w"> </span><span class="na">frequency</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">865600000</span> 883 884 <span class="w"> </span><span class="c1"># The virtual port, only the manufacturer</span> 885 <span class="w"> </span><span class="c1"># or the person who wrote the board config</span> 886 <span class="w"> </span><span class="c1"># can tell you what it will be for which</span> 887 <span class="w"> </span><span class="c1"># physical hardware interface</span> 888 <span class="w"> </span><span class="na">vport</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">0</span> 889 890 <span class="w"> </span><span class="c1"># Set LoRa bandwidth to 125 KHz</span> 891 <span class="w"> </span><span class="na">bandwidth</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">125000</span> 892 893 <span class="w"> </span><span class="c1"># Set TX power to 0 dBm (0.12 mW)</span> 894 <span class="w"> </span><span class="na">txpower</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">0</span> 895 896 <span class="w"> </span><span class="c1"># Select spreading factor 7. Valid</span> 897 <span class="w"> </span><span class="c1"># range is 5 through 12, with 5</span> 898 <span class="w"> </span><span class="c1"># being the fastest and 12 having</span> 899 <span class="w"> </span><span class="c1"># the longest range.</span> 900 <span class="w"> </span><span class="na">spreadingfactor</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">7</span> 901 902 <span class="w"> </span><span class="c1"># Select coding rate 5. Valid range</span> 903 <span class="w"> </span><span class="c1"># is 5 throough 8, with 5 being the</span> 904 <span class="w"> </span><span class="c1"># fastest, and 8 the longest range.</span> 905 <span class="w"> </span><span class="na">codingrate</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">5</span> 906 907 <span class="w"> </span><span class="c1"># It is possible to limit the airtime</span> 908 <span class="w"> </span><span class="c1"># utilisation of an RNode by using the</span> 909 <span class="w"> </span><span class="c1"># following two configuration options.</span> 910 <span class="w"> </span><span class="c1"># The short-term limit is applied in a</span> 911 <span class="w"> </span><span class="c1"># window of approximately 15 seconds,</span> 912 <span class="w"> </span><span class="c1"># and the long-term limit is enforced</span> 913 <span class="w"> </span><span class="c1"># over a rolling 60 minute window. Both</span> 914 <span class="w"> </span><span class="c1"># options are specified in percent.</span> 915 916 <span class="w"> </span><span class="c1"># airtime_limit_long = 100</span> 917 <span class="w"> </span><span class="c1"># airtime_limit_short = 100</span> 918 </pre></div> 919 </div> 920 </section> 921 <section id="serial-interface"> 922 <span id="interfaces-serial"></span><h2>Serial Interface<a class="headerlink" href="#serial-interface" title="Link to this heading">¶</a></h2> 923 <p>Reticulum can be used over serial ports directly, or over any device with a 924 serial port, that will transparently pass data. Useful for communicating 925 directly over a wire-pair, or for using devices such as data radios and lasers.</p> 926 <div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[[Serial Interface]]</span> 927 <span class="w"> </span><span class="na">type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">SerialInterface</span> 928 <span class="w"> </span><span class="na">enabled</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span> 929 930 <span class="w"> </span><span class="c1"># Serial port for the device</span> 931 <span class="w"> </span><span class="na">port</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">/dev/ttyUSB0</span> 932 933 <span class="w"> </span><span class="c1"># Set the serial baud-rate and other</span> 934 <span class="w"> </span><span class="c1"># configuration parameters.</span> 935 <span class="w"> </span><span class="na">speed</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">115200</span> 936 <span class="w"> </span><span class="na">databits</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">8</span> 937 <span class="w"> </span><span class="na">parity</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">none</span> 938 <span class="w"> </span><span class="na">stopbits</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">1</span> 939 </pre></div> 940 </div> 941 </section> 942 <section id="pipe-interface"> 943 <span id="interfaces-pipe"></span><h2>Pipe Interface<a class="headerlink" href="#pipe-interface" title="Link to this heading">¶</a></h2> 944 <p>Using this interface, Reticulum can use any program as an interface via <cite>stdin</cite> and 945 <cite>stdout</cite>. This can be used to easily create virtual interfaces, or to interface with 946 custom hardware or other systems.</p> 947 <div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[[Pipe Interface]]</span> 948 <span class="w"> </span><span class="na">type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">PipeInterface</span> 949 <span class="w"> </span><span class="na">enabled</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span> 950 951 <span class="w"> </span><span class="c1"># External command to execute</span> 952 <span class="w"> </span><span class="na">command</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">netcat -l 5757</span> 953 954 <span class="w"> </span><span class="c1"># Optional respawn delay, in seconds</span> 955 <span class="w"> </span><span class="na">respawn_delay</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">5</span> 956 </pre></div> 957 </div> 958 <p>Reticulum will write all packets to <cite>stdin</cite> of the <code class="docutils literal notranslate"><span class="pre">command</span></code> option, and will 959 continuously read and scan its <cite>stdout</cite> for Reticulum packets. If <code class="docutils literal notranslate"><span class="pre">EOF</span></code> is reached, 960 Reticulum will try to respawn the program after waiting for <code class="docutils literal notranslate"><span class="pre">respawn_interval</span></code> seconds.</p> 961 </section> 962 <section id="kiss-interface"> 963 <span id="interfaces-kiss"></span><h2>KISS Interface<a class="headerlink" href="#kiss-interface" title="Link to this heading">¶</a></h2> 964 <p>With the KISS interface, you can use Reticulum over a variety of packet 965 radio modems and TNCs, including <a class="reference external" href="https://unsigned.io/openmodem/">OpenModem</a>. 966 KISS interfaces can also be configured to periodically send out beacons 967 for station identification purposes.</p> 968 <div class="admonition warning"> 969 <p class="admonition-title">Warning</p> 970 <p>Radio frequency spectrum is a legally controlled resource, and legislation 971 varies widely around the world. It is your responsibility to be aware of any 972 relevant regulation for your location, and to make decisions accordingly.</p> 973 </div> 974 <div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[[Packet Radio KISS Interface]]</span> 975 <span class="w"> </span><span class="na">type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">KISSInterface</span> 976 <span class="w"> </span><span class="na">enabled</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span> 977 978 <span class="w"> </span><span class="c1"># Serial port for the device</span> 979 <span class="w"> </span><span class="na">port</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">/dev/ttyUSB1</span> 980 981 <span class="w"> </span><span class="c1"># Set the serial baud-rate and other</span> 982 <span class="w"> </span><span class="c1"># configuration parameters.</span> 983 <span class="w"> </span><span class="na">speed</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">115200</span> 984 <span class="w"> </span><span class="na">databits</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">8</span> 985 <span class="w"> </span><span class="na">parity</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">none</span> 986 <span class="w"> </span><span class="na">stopbits</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">1</span> 987 988 <span class="w"> </span><span class="c1"># Set the modem preamble.</span> 989 <span class="w"> </span><span class="na">preamble</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">150</span> 990 991 <span class="w"> </span><span class="c1"># Set the modem TX tail.</span> 992 <span class="w"> </span><span class="na">txtail</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">10</span> 993 994 <span class="w"> </span><span class="c1"># Configure CDMA parameters. These</span> 995 <span class="w"> </span><span class="c1"># settings are reasonable defaults.</span> 996 <span class="w"> </span><span class="na">persistence</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">200</span> 997 <span class="w"> </span><span class="na">slottime</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">20</span> 998 999 <span class="w"> </span><span class="c1"># You can configure the interface to send</span> 1000 <span class="w"> </span><span class="c1"># out identification on the channel with</span> 1001 <span class="w"> </span><span class="c1"># a set interval by configuring the</span> 1002 <span class="w"> </span><span class="c1"># following two parameters. The KISS</span> 1003 <span class="w"> </span><span class="c1"># interface will only ID if the set</span> 1004 <span class="w"> </span><span class="c1"># interval has elapsed since it's last</span> 1005 <span class="w"> </span><span class="c1"># actual transmission. The interval is</span> 1006 <span class="w"> </span><span class="c1"># configured in seconds.</span> 1007 <span class="w"> </span><span class="c1"># This option is commented out and not</span> 1008 <span class="w"> </span><span class="c1"># used by default.</span> 1009 <span class="w"> </span><span class="c1"># id_callsign = MYCALL-0</span> 1010 <span class="w"> </span><span class="c1"># id_interval = 600</span> 1011 1012 <span class="w"> </span><span class="c1"># Whether to use KISS flow-control.</span> 1013 <span class="w"> </span><span class="c1"># This is useful for modems that have</span> 1014 <span class="w"> </span><span class="c1"># a small internal packet buffer, but</span> 1015 <span class="w"> </span><span class="c1"># support packet flow control instead.</span> 1016 <span class="w"> </span><span class="na">flow_control</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">false</span> 1017 </pre></div> 1018 </div> 1019 </section> 1020 <section id="ax-25-kiss-interface"> 1021 <span id="interfaces-ax25"></span><h2>AX.25 KISS Interface<a class="headerlink" href="#ax-25-kiss-interface" title="Link to this heading">¶</a></h2> 1022 <p>If you’re using Reticulum on amateur radio spectrum, you might want to 1023 use the AX.25 KISS interface. This way, Reticulum will automatically 1024 encapsulate it’s traffic in AX.25 and also identify your stations 1025 transmissions with your callsign and SSID.</p> 1026 <p>Only do this if you really need to! Reticulum doesn’t need the AX.25 1027 layer for anything, and it incurs extra overhead on every packet to 1028 encapsulate in AX.25.</p> 1029 <p>A more efficient way is to use the plain KISS interface with the 1030 beaconing functionality described above.</p> 1031 <div class="admonition warning"> 1032 <p class="admonition-title">Warning</p> 1033 <p>Radio frequency spectrum is a legally controlled resource, and legislation 1034 varies widely around the world. It is your responsibility to be aware of any 1035 relevant regulation for your location, and to make decisions accordingly.</p> 1036 </div> 1037 <div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[[Packet Radio AX.25 KISS Interface]]</span> 1038 <span class="w"> </span><span class="na">type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">AX25KISSInterface</span> 1039 1040 <span class="w"> </span><span class="c1"># Set the station callsign and SSID</span> 1041 <span class="w"> </span><span class="na">callsign</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">NO1CLL</span> 1042 <span class="w"> </span><span class="na">ssid</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">0</span> 1043 1044 <span class="w"> </span><span class="c1"># Enable interface if you want use it!</span> 1045 <span class="w"> </span><span class="na">enabled</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span> 1046 1047 <span class="w"> </span><span class="c1"># Serial port for the device</span> 1048 <span class="w"> </span><span class="na">port</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">/dev/ttyUSB2</span> 1049 1050 <span class="w"> </span><span class="c1"># Set the serial baud-rate and other</span> 1051 <span class="w"> </span><span class="c1"># configuration parameters.</span> 1052 <span class="w"> </span><span class="na">speed</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">115200</span> 1053 <span class="w"> </span><span class="na">databits</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">8</span> 1054 <span class="w"> </span><span class="na">parity</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">none</span> 1055 <span class="w"> </span><span class="na">stopbits</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">1</span> 1056 1057 <span class="w"> </span><span class="c1"># Set the modem preamble. A 150ms</span> 1058 <span class="w"> </span><span class="c1"># preamble should be a reasonable</span> 1059 <span class="w"> </span><span class="c1"># default, but may need to be</span> 1060 <span class="w"> </span><span class="c1"># increased for radios with slow-</span> 1061 <span class="w"> </span><span class="c1"># opening squelch and long TX/RX</span> 1062 <span class="w"> </span><span class="c1"># turnaround</span> 1063 <span class="w"> </span><span class="na">preamble</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">150</span> 1064 1065 <span class="w"> </span><span class="c1"># Set the modem TX tail. In most</span> 1066 <span class="w"> </span><span class="c1"># cases this should be kept as low</span> 1067 <span class="w"> </span><span class="c1"># as possible to not waste airtime.</span> 1068 <span class="w"> </span><span class="na">txtail</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">10</span> 1069 1070 <span class="w"> </span><span class="c1"># Configure CDMA parameters. These</span> 1071 <span class="w"> </span><span class="c1"># settings are reasonable defaults.</span> 1072 <span class="w"> </span><span class="na">persistence</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">200</span> 1073 <span class="w"> </span><span class="na">slottime</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">20</span> 1074 1075 <span class="w"> </span><span class="c1"># Whether to use KISS flow-control.</span> 1076 <span class="w"> </span><span class="c1"># This is useful for modems with a</span> 1077 <span class="w"> </span><span class="c1"># small internal packet buffer.</span> 1078 <span class="w"> </span><span class="na">flow_control</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">false</span> 1079 </pre></div> 1080 </div> 1081 </section> 1082 <section id="discoverable-interfaces"> 1083 <span id="interfaces-discoverable"></span><h2>Discoverable Interfaces<a class="headerlink" href="#discoverable-interfaces" title="Link to this heading">¶</a></h2> 1084 <p>Reticulum includes a powerful system for publishing your local interfaces to the wider network, allowing other peers to <a class="reference internal" href="using.html#using-interface-discovery"><span class="std std-ref">discover, validate, and automatically connect to them</span></a>. This feature is particularly useful for creating decentralized networks where peers can dynamically find entrypoints, such as public Internet gateways or local radio access points, without relying on static configuration files or centralized directories.</p> 1085 <p>When an interface is made <strong>discoverable</strong>, your Reticulum instance will periodically broadcast an announce packet containing the connection details and parameters required for other peers to establish a connection. These announces are propagated over the network using the standard Reticulum announce mechanism using the <code class="docutils literal notranslate"><span class="pre">rnstransport.discovery.interface</span></code> destination type.</p> 1086 <div class="admonition note"> 1087 <p class="admonition-title">Note</p> 1088 <p>To use the interface discovery functionality, the <code class="docutils literal notranslate"><span class="pre">LXMF</span></code> module must be installed in your Python environment. You can install it using pip:</p> 1089 <div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>pip<span class="w"> </span>install<span class="w"> </span>lxmf 1090 </pre></div> 1091 </div> 1092 </div> 1093 <section id="enabling-discovery"> 1094 <h3>Enabling Discovery<a class="headerlink" href="#enabling-discovery" title="Link to this heading">¶</a></h3> 1095 <p>Interface discovery is enabled on a per-interface basis. To make a specific interface discoverable, you must add the <code class="docutils literal notranslate"><span class="pre">discoverable</span></code> option to that interface’s configuration block and set it to <code class="docutils literal notranslate"><span class="pre">yes</span></code>.</p> 1096 <div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[[My Public Gateway]]</span> 1097 <span class="w"> </span><span class="na">type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">BackboneInterface</span> 1098 <span class="w"> </span><span class="na">...</span> 1099 <span class="w"> </span><span class="na">discoverable</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span> 1100 </pre></div> 1101 </div> 1102 <p>Once enabled, Reticulum will automatically handle the generation, signing, stamping, and broadcasting of the discovery announces. It is not <em>required</em> to enable Transport to publish interface discovery information, but for most use cases where you want others to connect to you, you will likely want <code class="docutils literal notranslate"><span class="pre">enable_transport</span></code> set to <code class="docutils literal notranslate"><span class="pre">yes</span></code> in the <code class="docutils literal notranslate"><span class="pre">[reticulum]</span></code> section of your configuration.</p> 1103 </section> 1104 <section id="discovery-parameters"> 1105 <h3>Discovery Parameters<a class="headerlink" href="#discovery-parameters" title="Link to this heading">¶</a></h3> 1106 <p>When <code class="docutils literal notranslate"><span class="pre">discoverable</span></code> is enabled, a variety of additional options become available to control how the interface is presented to the network. These parameters allow you to fine-tune the metadata, security requirements, and visibility of your interface.</p> 1107 <p><strong>Basic Metadata</strong></p> 1108 <dl class="simple"> 1109 <dt><code class="docutils literal notranslate"><span class="pre">discovery_name</span></code></dt><dd><p>A human-readable name for the interface. This name will be displayed to users on remote systems when they list discovered interfaces. If not specified, the interface name (the section header) will be used.</p> 1110 </dd> 1111 <dt><code class="docutils literal notranslate"><span class="pre">announce_interval</span></code></dt><dd><p>The interval in minutes between successive discovery announces for this interface. Default is 360 minutes (6 hours). For stable, long-running infrastructure, higher intervals (12 to 22 hours) are usually sufficient and reduce network load. Minimum allowed value is 5 minutes (but expect to have your announces throttled if using intervals below one hour).</p> 1112 </dd> 1113 </dl> 1114 <p><strong>Connectivity Specification</strong></p> 1115 <dl> 1116 <dt><code class="docutils literal notranslate"><span class="pre">reachable_on</span></code></dt><dd><p>Specifies the address that remote peers should use to connect to this interface.</p> 1117 <ul class="simple"> 1118 <li><p>For TCP and Backbone interfaces, this is typically the public IP address or hostname. Do not include the port, this is fetched automatically from the interface.</p></li> 1119 <li><p>For I2P interfaces, this is usually the I2P <code class="docutils literal notranslate"><span class="pre">b32</span></code> address. This value is fetched automatically from the <code class="docutils literal notranslate"><span class="pre">I2PInterface</span></code> once it is up and connected to the I2P network, so you should not set this manually, unless you absolutely know what you’re doing.</p></li> 1120 </ul> 1121 <p><strong>Dynamic Resolution:</strong> This option also accepts a path to an external executable script or binary. If a path is provided, Reticulum will execute the script and use its <code class="docutils literal notranslate"><span class="pre">stdout</span></code> as the reachability address. This is useful for devices behind dynamic DNS, NATs, or complex cloud environments where the external IP is not known locally. The script must simply print the address to stdout and exit.</p> 1122 </dd> 1123 </dl> 1124 <div class="admonition note"> 1125 <p class="admonition-title">Note</p> 1126 <p>When using an executable script for <code class="docutils literal notranslate"><span class="pre">reachable_on</span></code>, Reticulum expects the script to output only the IP address or hostname to <code class="docutils literal notranslate"><span class="pre">stdout</span></code>, followed by a newline character. Any additional output or errors may cause the resolution to fail. Ensure the script has executable permissions and is robust against temporary network failures.</p> 1127 </div> 1128 <p>A minimal example of a script that resolves the externally available, public IP of an internet-connected system could look like this:</p> 1129 <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="ch">#!/bin/bash</span> 1130 curl<span class="w"> </span>-s<span class="w"> </span>ip.me 1131 <span class="nb">exit</span><span class="w"> </span><span class="nv">$?</span> 1132 </pre></div> 1133 </div> 1134 <p>On a real system, you should make the script robust enough to deal with intermittent Internet or service failures, such that the script <em>always</em> returns a sensible value, or if not possible at least exits with a non-zero exit return code, so Reticulum knows the output is invalid.</p> 1135 <p><strong>Security & Cost</strong></p> 1136 <dl class="simple"> 1137 <dt><code class="docutils literal notranslate"><span class="pre">discovery_stamp_value</span></code></dt><dd><p>Defines the proof-of-work difficulty for the cryptographic stamp included in the announce. This value acts as a cost barrier to prevent network flooding. The default value is <code class="docutils literal notranslate"><span class="pre">14</span></code>. Increasing this value makes it computationally more expensive to generate an announce, which can be useful to prevent spam on very large networks, but it also increases CPU load on your system when generating announces. Stamps are cached, and only generated if interface information changes, or at instance restart. If you have the computational resources, it is generally advisable to use as high a stamp value as possible.</p> 1138 </dd> 1139 </dl> 1140 <p><strong>Privacy & Encryption</strong></p> 1141 <dl class="simple"> 1142 <dt><code class="docutils literal notranslate"><span class="pre">discovery_encrypt</span></code></dt><dd><p>If set to <code class="docutils literal notranslate"><span class="pre">yes</span></code>, the discovery announce payload will be encrypted. To decrypt the announce, remote peers must possess the <em>network identity</em> configured for your instance (see <code class="docutils literal notranslate"><span class="pre">network_identity</span></code> in the <code class="docutils literal notranslate"><span class="pre">[reticulum]</span></code> section). This allows you to publish private interfaces that are only discoverable to specific trusted networks.</p> 1143 </dd> 1144 </dl> 1145 <div class="admonition important"> 1146 <p class="admonition-title">Important</p> 1147 <p>If you enable <code class="docutils literal notranslate"><span class="pre">discovery_encrypt</span></code> but do not configure a valid <code class="docutils literal notranslate"><span class="pre">network_identity</span></code> in the <code class="docutils literal notranslate"><span class="pre">[reticulum]</span></code> section of your configuration, Reticulum will abort the interface discovery announce. Encryption requires a valid network identity key to function.</p> 1148 </div> 1149 <dl class="simple"> 1150 <dt><code class="docutils literal notranslate"><span class="pre">publish_ifac</span></code></dt><dd><p>If set to <code class="docutils literal notranslate"><span class="pre">yes</span></code>, the Interface Access Code (IFAC) name and passphrase for this interface will be included in the discovery announce. This allows peers to automatically configure the correct authentication parameters when connecting to the interface.</p> 1151 </dd> 1152 </dl> 1153 <p><strong>Physical Location</strong></p> 1154 <dl class="simple"> 1155 <dt><code class="docutils literal notranslate"><span class="pre">latitude</span></code>, <code class="docutils literal notranslate"><span class="pre">longitude</span></code>, <code class="docutils literal notranslate"><span class="pre">height</span></code></dt><dd><p>Optional physical coordinates for the interface. These are useful for mapping discovered interfaces geographically or for clients to automatically select the nearest access point. Coordinates should be in decimal degrees, height in meters.</p> 1156 </dd> 1157 </dl> 1158 <p><strong>Radio Parameters</strong></p> 1159 <p>For physical radio interfaces like <code class="docutils literal notranslate"><span class="pre">RNodeInterface</span></code> or <code class="docutils literal notranslate"><span class="pre">KISSInterface</span></code>, the following optional parameters allow you to broadcast the operating frequency and characteristics, allowing clients to verify compatibility before connecting:</p> 1160 <dl class="simple"> 1161 <dt><code class="docutils literal notranslate"><span class="pre">discovery_frequency</span></code></dt><dd><p>The operating frequency in Hz. Auto-configured on RNode interfaces. Necessary on KISS-based radio interfaces and <code class="docutils literal notranslate"><span class="pre">TCPClientInterfaces</span></code> connecting to radio modems.</p> 1162 </dd> 1163 <dt><code class="docutils literal notranslate"><span class="pre">discovery_bandwidth</span></code></dt><dd><p>The signal bandwidth in Hz. Auto-configured on RNode interfaces. Useful on KISS-based radio interfaces and <code class="docutils literal notranslate"><span class="pre">TCPClientInterfaces</span></code> connecting to radio modems.</p> 1164 </dd> 1165 <dt><code class="docutils literal notranslate"><span class="pre">discovery_modulation</span></code></dt><dd><p>The modulation type or scheme. Auto-configured on RNode interfaces, but highly advisable to include on other radio-based interfaces.</p> 1166 </dd> 1167 </dl> 1168 </section> 1169 <section id="interface-modes"> 1170 <h3>Interface Modes<a class="headerlink" href="#interface-modes" title="Link to this heading">¶</a></h3> 1171 <p>When you enable discovery on an interface, Reticulum enforces certain interface modes to ensure the interface is actually useful for remote peers.</p> 1172 <p>If an interface is configured as <code class="docutils literal notranslate"><span class="pre">discoverable</span></code>, but its mode is not explicitly set to <code class="docutils literal notranslate"><span class="pre">gateway</span></code> (for server-style interfaces like <code class="docutils literal notranslate"><span class="pre">BackboneInterface</span></code> or <code class="docutils literal notranslate"><span class="pre">TCPServerInterface</span></code>) or <code class="docutils literal notranslate"><span class="pre">access_point</span></code> (for radio interfaces like <code class="docutils literal notranslate"><span class="pre">RNodeInterface</span></code>), Reticulum will automatically configure the appropriate mode and log a notice.</p> 1173 <p>For example, if you enable discovery on a <code class="docutils literal notranslate"><span class="pre">RNodeInterface</span></code> without specifying the mode, Reticulum will automatically set it to <code class="docutils literal notranslate"><span class="pre">access_point</span></code> mode.</p> 1174 </section> 1175 <section id="security-considerations"> 1176 <h3>Security Considerations<a class="headerlink" href="#security-considerations" title="Link to this heading">¶</a></h3> 1177 <p>When making interfaces discoverable, you are effectively broadcasting an invitation to connect to your system. It is important to understand the security implications of the configuration options you choose.</p> 1178 <p><strong>Publishing Credentials</strong></p> 1179 <p>If you enable <code class="docutils literal notranslate"><span class="pre">publish_ifac</span> <span class="pre">=</span> <span class="pre">yes</span></code>, your interface’s authentication passphrase will be included in the announce. If you are operating a public network and want anyone to connect, this is acceptable. However, if you wish to restrict access to a specific group of users, you <strong>must</strong> enable <code class="docutils literal notranslate"><span class="pre">discovery_encrypt</span> <span class="pre">=</span> <span class="pre">yes</span></code>. This ensures that only peers possessing the correct <code class="docutils literal notranslate"><span class="pre">network_identity</span></code> can decode the passphrase.</p> 1180 <p><strong>Topology Exposure</strong></p> 1181 <p>A discoverable interface announces its presence, location (if configured), and capabilities to the network. Even if the connection details are encrypted, the <em>fact</em> that a connectable node exists within a certain network becomes public information. In high-security or scenarios requiring operational secrecy, consider the implications of advertising your infrastructure’s existence.</p> 1182 </section> 1183 <section id="example-configuration"> 1184 <h3>Example Configuration<a class="headerlink" href="#example-configuration" title="Link to this heading">¶</a></h3> 1185 <p>Below is an example configuration for a public backbone gateway. This configuration publishes a high-value, publicly discoverable interface, that anyone can connect to.</p> 1186 <div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[[My Public Gateway]]</span> 1187 <span class="w"> </span><span class="na">type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">BackboneInterface</span> 1188 <span class="w"> </span><span class="na">mode</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">gateway</span> 1189 <span class="w"> </span><span class="na">listen_on</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">0.0.0.0</span> 1190 <span class="w"> </span><span class="na">port</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">4242</span> 1191 1192 <span class="w"> </span><span class="c1"># Enable Discovery</span> 1193 <span class="w"> </span><span class="na">discoverable</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span> 1194 1195 <span class="w"> </span><span class="c1"># Interface Details</span> 1196 <span class="w"> </span><span class="na">discovery_name</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">Region A Public Entrypoint</span> 1197 <span class="w"> </span><span class="na">announce_interval</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">720</span> 1198 1199 <span class="w"> </span><span class="c1"># Use external script to resolve dynamic IP</span> 1200 <span class="w"> </span><span class="na">reachable_on</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">/usr/local/bin/get_external_ip.sh</span> 1201 1202 <span class="w"> </span><span class="c1"># Generate high stamp value</span> 1203 <span class="w"> </span><span class="na">discovery_stamp_value</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">24</span> 1204 1205 <span class="w"> </span><span class="c1"># Optional location data</span> 1206 <span class="w"> </span><span class="na">latitude</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">51.99714</span> 1207 <span class="w"> </span><span class="na">longitude</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">-0.74195</span> 1208 <span class="w"> </span><span class="na">height</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">15</span> 1209 </pre></div> 1210 </div> 1211 <p>The next example create an encrypted discovery-enabled interface, requiring a specific network identity to decode, and includes IFAC credentials for seamless authentication.</p> 1212 <div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[[My Private Gateway]]</span> 1213 <span class="w"> </span><span class="na">type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">BackboneInterface</span> 1214 <span class="w"> </span><span class="na">mode</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">gateway</span> 1215 <span class="w"> </span><span class="na">listen_on</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">0.0.0.0</span> 1216 <span class="w"> </span><span class="na">port</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">5858</span> 1217 <span class="w"> </span><span class="na">network_name</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">internal_1</span> 1218 <span class="w"> </span><span class="na">passphrase</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">Mevpekyafshak5Wr</span> 1219 1220 <span class="w"> </span><span class="c1"># Enable Discovery</span> 1221 <span class="w"> </span><span class="na">discoverable</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span> 1222 1223 <span class="w"> </span><span class="c1"># Interface Details</span> 1224 <span class="w"> </span><span class="na">discovery_name</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">Region A Private Backbone</span> 1225 <span class="w"> </span><span class="na">announce_interval</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">720</span> 1226 1227 <span class="w"> </span><span class="c1"># Use external script to resolve dynamic IP</span> 1228 <span class="w"> </span><span class="na">reachable_on</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">/usr/local/bin/get_external_ip.sh</span> 1229 1230 <span class="w"> </span><span class="c1"># Target stamp value</span> 1231 <span class="w"> </span><span class="na">discovery_stamp_value</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">22</span> 1232 1233 <span class="w"> </span><span class="c1"># Encrypt announces for our network only</span> 1234 <span class="w"> </span><span class="na">discovery_encrypt</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span> 1235 1236 <span class="w"> </span><span class="c1"># Include credentials so trusted</span> 1237 <span class="w"> </span><span class="c1"># peers can connect automatically</span> 1238 <span class="w"> </span><span class="na">publish_ifac</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span> 1239 1240 <span class="w"> </span><span class="c1"># Optional location data</span> 1241 <span class="w"> </span><span class="na">latitude</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">34.06915</span> 1242 <span class="w"> </span><span class="na">longitude</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">-118.44318</span> 1243 <span class="w"> </span><span class="na">height</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">15</span> 1244 </pre></div> 1245 </div> 1246 <p>In the <code class="docutils literal notranslate"><span class="pre">[reticulum]</span></code> section of your configuration, you would define the network identity used for encryption as follows:</p> 1247 <div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[reticulum]</span> 1248 <span class="na">...</span> 1249 <span class="c1"># The identity used to sign/encrypt discovery announces</span> 1250 <span class="na">network_identity</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">~/.reticulum/storage/identities/my_network_identity</span> 1251 <span class="na">...</span> 1252 </pre></div> 1253 </div> 1254 <p>With these configuration options applied, your Reticulum instance will actively participate in the network’s discovery ecosystem. Other peers running Reticulum with discovery enabled will be able to see your interface, validate its cryptographic stamp, and (depending on their configuration) automatically connect to it.</p> 1255 <p>For information on how to use these discovered interfaces and configure your system to auto-connect to them, refer to the <a class="reference internal" href="using.html#using-interface-discovery"><span class="std std-ref">Discovering Interfaces</span></a> chapter.</p> 1256 </section> 1257 </section> 1258 <section id="common-interface-options"> 1259 <span id="interfaces-options"></span><h2>Common Interface Options<a class="headerlink" href="#common-interface-options" title="Link to this heading">¶</a></h2> 1260 <p>A number of general configuration options are available on most interfaces. 1261 These can be used to control various aspects of interface behaviour.</p> 1262 <blockquote> 1263 <div><ul> 1264 <li><div class="line-block"> 1265 <div class="line">The <code class="docutils literal notranslate"><span class="pre">enabled</span></code> option tells Reticulum whether or not 1266 to bring up the interface. Defaults to <code class="docutils literal notranslate"><span class="pre">False</span></code>. For any 1267 interface to be brought up, the <code class="docutils literal notranslate"><span class="pre">enabled</span></code> option 1268 must be set to <code class="docutils literal notranslate"><span class="pre">True</span></code> or <code class="docutils literal notranslate"><span class="pre">Yes</span></code>.</div> 1269 </div> 1270 </li> 1271 <li><div class="line-block"> 1272 <div class="line">The <code class="docutils literal notranslate"><span class="pre">mode</span></code> option allows selecting the high-level behaviour 1273 of the interface from a number of options.</div> 1274 </div> 1275 <blockquote> 1276 <div><ul class="simple"> 1277 <li><p>The default value is <code class="docutils literal notranslate"><span class="pre">full</span></code>. In this mode, all discovery, 1278 meshing and transport functionality is available.</p></li> 1279 <li><p>In the <code class="docutils literal notranslate"><span class="pre">access_point</span></code> (or shorthand <code class="docutils literal notranslate"><span class="pre">ap</span></code>) mode, the 1280 interface will operate as a network access point. In this 1281 mode, announces will not be automatically broadcasted on 1282 the interface, and paths to destinations on the interface 1283 will have a much shorter expiry time. This mode is useful 1284 for creating interfaces that are mostly quiet, unless when 1285 someone is actually using them. An example of this could 1286 be a radio interface serving a wide area, where users are 1287 expected to connect momentarily, use the network, and then 1288 disappear again.</p></li> 1289 </ul> 1290 </div></blockquote> 1291 </li> 1292 <li><div class="line-block"> 1293 <div class="line">The <code class="docutils literal notranslate"><span class="pre">outgoing</span></code> option sets whether an interface is allowed 1294 to transmit. Defaults to <code class="docutils literal notranslate"><span class="pre">True</span></code>. If set to <code class="docutils literal notranslate"><span class="pre">False</span></code> or <code class="docutils literal notranslate"><span class="pre">No</span></code> 1295 the interface will only receive data, and never transmit.</div> 1296 </div> 1297 </li> 1298 <li><div class="line-block"> 1299 <div class="line">The <code class="docutils literal notranslate"><span class="pre">network_name</span></code> option sets the virtual network name for 1300 the interface. This allows multiple separate network segments 1301 to exist on the same physical channel or medium.</div> 1302 </div> 1303 </li> 1304 <li><div class="line-block"> 1305 <div class="line">The <code class="docutils literal notranslate"><span class="pre">passphrase</span></code> option sets an authentication passphrase on 1306 the interface. This option can be used in conjunction with the 1307 <code class="docutils literal notranslate"><span class="pre">network_name</span></code> option, or be used alone.</div> 1308 </div> 1309 </li> 1310 <li><div class="line-block"> 1311 <div class="line">The <code class="docutils literal notranslate"><span class="pre">ifac_size</span></code> option allows customising the length of the 1312 Interface Authentication Codes carried by each packet on named 1313 and/or authenticated network segments. It is set by default to 1314 a size suitable for the interface in question, but can be set 1315 to a custom size between 8 and 512 bits by using this option. 1316 In normal usage, this option should not be changed from the 1317 default.</div> 1318 </div> 1319 </li> 1320 <li><div class="line-block"> 1321 <div class="line">The <code class="docutils literal notranslate"><span class="pre">announce_cap</span></code> option lets you configure the maximum 1322 bandwidth to allocate, at any given time, to propagating 1323 announces and other network upkeep traffic. It is configured at 1324 2% by default, and should normally not need to be changed. Can 1325 be set to any value between <code class="docutils literal notranslate"><span class="pre">1</span></code> and <code class="docutils literal notranslate"><span class="pre">100</span></code>.</div> 1326 </div> 1327 <blockquote> 1328 <div><p><em>If an interface exceeds its announce cap, it will queue announces 1329 for later transmission. Reticulum will always prioritise propagating 1330 announces from nearby nodes first. This ensures that the local 1331 topology is prioritised, and that slow networks are not overwhelmed 1332 by interconnected fast networks.</em></p> 1333 <p><em>Destinations that are rapidly re-announcing will be down-prioritised 1334 further. Trying to get “first-in-line” by announce spamming will have 1335 the exact opposite effect: Getting moved to the back of the queue every 1336 time a new announce from the excessively announcing destination is received.</em></p> 1337 <p><em>This means that it is always beneficial to select a balanced 1338 announce rate, and not announce more often than is actually necesarry 1339 for your application to function.</em></p> 1340 </div></blockquote> 1341 </li> 1342 <li><div class="line-block"> 1343 <div class="line">The <code class="docutils literal notranslate"><span class="pre">bitrate</span></code> option configures the interface bitrate. 1344 Reticulum will use interface speeds reported by hardware, or 1345 try to guess a suitable rate when the hardware doesn’t report 1346 any. In most cases, the automatically found rate should be 1347 sufficient, but it can be configured by using the <code class="docutils literal notranslate"><span class="pre">bitrate</span></code> 1348 option, to set the interface speed in <em>bits per second</em>.</div> 1349 </div> 1350 </li> 1351 <li><div class="line-block"> 1352 <div class="line">The <code class="docutils literal notranslate"><span class="pre">bootstrap_only</span></code> option designates an interface as a temporary 1353 bridge for initial connectivity. If this option is enabled, the 1354 interface will be monitored and automatically detached once the 1355 number of auto-connected interfaces reaches the limit configured by 1356 <code class="docutils literal notranslate"><span class="pre">autoconnect_discovered_interfaces</span></code>. This is particularly useful 1357 for using a slow or expensive connection (such as a single LoRa 1358 link or a remote TCP tunnel) solely to discover better local 1359 infrastructure, which then supersedes the bootstrap interface.</div> 1360 </div> 1361 </li> 1362 </ul> 1363 </div></blockquote> 1364 </section> 1365 <section id="interfaces-modes"> 1366 <span id="id4"></span><h2>Interface Modes<a class="headerlink" href="#interfaces-modes" title="Link to this heading">¶</a></h2> 1367 <p>The optional <code class="docutils literal notranslate"><span class="pre">mode</span></code> setting is available on all interfaces, and allows 1368 selecting the high-level behaviour of the interface from a number of modes. 1369 These modes affect how Reticulum selects paths in the network, how announces 1370 are propagated, how long paths are valid and how paths are discovered.</p> 1371 <p>Configuring modes on interfaces is <strong>not</strong> strictly necessary, but can be useful 1372 when building or connecting to more complex networks. If your Reticulum 1373 instance is not running a Transport Node, it is rarely useful to configure 1374 interface modes, and in such cases interfaces should generally be left in 1375 the default mode.</p> 1376 <blockquote> 1377 <div><ul> 1378 <li><div class="line-block"> 1379 <div class="line">The default mode is <code class="docutils literal notranslate"><span class="pre">full</span></code>. In this mode, all discovery, 1380 meshing and transport functionality is activated.</div> 1381 </div> 1382 </li> 1383 <li><div class="line-block"> 1384 <div class="line">The <code class="docutils literal notranslate"><span class="pre">gateway</span></code> mode (or shorthand <code class="docutils literal notranslate"><span class="pre">gw</span></code>) also has all 1385 discovery, meshing and transport functionality available, 1386 but will additionally try to discover unknown paths on 1387 behalf of other nodes residing on the <code class="docutils literal notranslate"><span class="pre">gateway</span></code> interface. 1388 If Reticulum receives a path request for an unknown 1389 destination, from a node on a <code class="docutils literal notranslate"><span class="pre">gateway</span></code> interface, it 1390 will try to discover this path via all other active interfaces, 1391 and forward the discovered path to the requestor if one is 1392 found.</div> 1393 </div> 1394 <div class="line-block"> 1395 <div class="line">If you want to allow other nodes to widely resolve paths or connect 1396 to a network via an interface, it might be useful to put it in this 1397 mode. By creating a chain of <code class="docutils literal notranslate"><span class="pre">gateway</span></code> interfaces, other 1398 nodes will be able to immediately discover paths to any 1399 destination along the chain.</div> 1400 </div> 1401 <div class="line-block"> 1402 <div class="line"><em>Please note!</em> It is the interface <em>facing the clients</em> that 1403 must be put into <code class="docutils literal notranslate"><span class="pre">gateway</span></code> mode for this to work, not 1404 the interface facing the wider network (for this, the <code class="docutils literal notranslate"><span class="pre">boundary</span></code> 1405 mode can be useful, though).</div> 1406 </div> 1407 </li> 1408 <li><div class="line-block"> 1409 <div class="line">In the <code class="docutils literal notranslate"><span class="pre">access_point</span></code> (or shorthand <code class="docutils literal notranslate"><span class="pre">ap</span></code>) mode, the 1410 interface will operate as a network access point. In this 1411 mode, announces will not be automatically broadcasted on 1412 the interface, and paths to destinations on the interface 1413 will have a much shorter expiry time. In addition, path 1414 requests from clients on the access point interface will 1415 be handled in the same way as the <code class="docutils literal notranslate"><span class="pre">gateway</span></code> interface.</div> 1416 </div> 1417 <div class="line-block"> 1418 <div class="line">This mode is useful for creating interfaces that remain 1419 quiet, until someone actually starts using them. An example 1420 of this could be a radio interface serving a wide area, 1421 where users are expected to connect momentarily, use the 1422 network, and then disappear again.</div> 1423 </div> 1424 </li> 1425 <li><div class="line-block"> 1426 <div class="line">The <code class="docutils literal notranslate"><span class="pre">roaming</span></code> mode should be used on interfaces that are 1427 roaming (physically mobile), seen from the perspective of 1428 other nodes in the network. As an example, if a vehicle is 1429 equipped with an external LoRa interface, and an internal, 1430 WiFi-based interface, that serves devices that are moving 1431 <em>with</em> the vehicle, the external LoRa interface should be 1432 configured as <code class="docutils literal notranslate"><span class="pre">roaming</span></code>, and the internal interface can 1433 be left in the default mode. With transport enabled, such 1434 a setup will allow all internal devices to reach each other, 1435 and all other devices that are available on the LoRa side 1436 of the network, when they are in range. Devices on the LoRa 1437 side of the network will also be able to reach devices 1438 internal to the vehicle, when it is in range. Paths via 1439 <code class="docutils literal notranslate"><span class="pre">roaming</span></code> interfaces also expire faster.</div> 1440 </div> 1441 </li> 1442 <li><div class="line-block"> 1443 <div class="line">The purpose of the <code class="docutils literal notranslate"><span class="pre">boundary</span></code> mode is to specify interfaces 1444 that establish connectivity with network segments that are 1445 significantly different than the one this node exists on. 1446 As an example, if a Reticulum instance is part of a LoRa-based 1447 network, but also has a high-speed connection to a 1448 public Transport Node available on the Internet, the interface 1449 connecting over the Internet should be set to <code class="docutils literal notranslate"><span class="pre">boundary</span></code> mode.</div> 1450 </div> 1451 </li> 1452 </ul> 1453 </div></blockquote> 1454 <p>For a table describing the impact of all modes on announce propagation, 1455 please see the <a class="reference internal" href="understanding.html#understanding-announcepropagation"><span class="std std-ref">Announce Propagation Rules</span></a> section.</p> 1456 </section> 1457 <section id="announce-rate-control"> 1458 <span id="interfaces-announcerates"></span><h2>Announce Rate Control<a class="headerlink" href="#announce-rate-control" title="Link to this heading">¶</a></h2> 1459 <p>The built-in announce control mechanisms and the default <code class="docutils literal notranslate"><span class="pre">announce_cap</span></code> 1460 option described above are sufficient most of the time, but in some cases, especially on fast 1461 interfaces, it may be useful to control the target announce rate. Using the 1462 <code class="docutils literal notranslate"><span class="pre">announce_rate_target</span></code>, <code class="docutils literal notranslate"><span class="pre">announce_rate_grace</span></code> and <code class="docutils literal notranslate"><span class="pre">announce_rate_penalty</span></code> 1463 options, this can be done on a per-interface basis, and moderates the <em>rate at 1464 which received announces are re-broadcasted to other interfaces</em>.</p> 1465 <blockquote> 1466 <div><ul> 1467 <li><div class="line-block"> 1468 <div class="line">The <code class="docutils literal notranslate"><span class="pre">announce_rate_target</span></code> option sets the minimum amount of time, 1469 in seconds, that should pass between received announces, for any one 1470 destination. As an example, setting this value to <code class="docutils literal notranslate"><span class="pre">3600</span></code> means that 1471 announces <em>received</em> on this interface will only be re-transmitted and 1472 propagated to other interfaces once every hour, no matter how often they 1473 are received.</div> 1474 </div> 1475 </li> 1476 <li><div class="line-block"> 1477 <div class="line">The optional <code class="docutils literal notranslate"><span class="pre">announce_rate_grace</span></code> defines the number of times a destination 1478 can violate the announce rate before the target rate is enforced.</div> 1479 </div> 1480 </li> 1481 <li><div class="line-block"> 1482 <div class="line">The optional <code class="docutils literal notranslate"><span class="pre">announce_rate_penalty</span></code> configures an extra amount of 1483 time that is added to the normal rate target. As an example, if a penalty 1484 of <code class="docutils literal notranslate"><span class="pre">7200</span></code> seconds is defined, once the rate target is enforced, the 1485 destination in question will only have its announces propagated every 1486 3 hours, until it lowers its actual announce rate to within the target.</div> 1487 </div> 1488 </li> 1489 </ul> 1490 </div></blockquote> 1491 <p>These mechanisms, in conjunction with the <code class="docutils literal notranslate"><span class="pre">annouce_cap</span></code> mechanisms mentioned 1492 above means that it is essential to select a balanced announce strategy for 1493 your destinations. The more balanced you can make this decision, the easier 1494 it will be for your destinations to make it into slower networks that many hops 1495 away. Or you can prioritise only reaching high-capacity networks with more frequent 1496 announces.</p> 1497 <p>Current statistics and information about announce rates can be viewed using the 1498 <code class="docutils literal notranslate"><span class="pre">rnpath</span> <span class="pre">-r</span></code> command.</p> 1499 <p>It is important to note that there is no one right or wrong way to set up announce 1500 rates. Slower networks will naturally tend towards using less frequent announces to 1501 conserve bandwidth, while very fast networks can support applications that 1502 need very frequent announces. Reticulum implements these mechanisms to ensure 1503 that a large span of network types can seamlessly <em>co-exist</em> and interconnect.</p> 1504 </section> 1505 <section id="new-destination-rate-limiting"> 1506 <span id="interfaces-ingress-control"></span><h2>New Destination Rate Limiting<a class="headerlink" href="#new-destination-rate-limiting" title="Link to this heading">¶</a></h2> 1507 <p>On public interfaces, where anyone may connect and announce new destinations, 1508 it can be useful to control the rate at which announces for <em>new</em> destinations are 1509 processed.</p> 1510 <p>If a large influx of announces for newly created or previously unknown destinations 1511 occur within a short amount of time, Reticulum will place these announces on hold, 1512 so that announce traffic for known and previously established destinations can 1513 continue to be processed without interruptions.</p> 1514 <p>After the burst subsides, and an additional waiting period has passed, the held 1515 announces will be released at a slow rate, until the hold queue is cleared. This 1516 also means, that should a node decide to connect to a public interface, announce 1517 a large amount of bogus destinations, and then disconnect, these destination will 1518 never make it into path tables and waste network bandwidth on retransmitted 1519 announces.</p> 1520 <p><strong>It’s important to note</strong> that the ingress control works at the level of <em>individual 1521 sub-interfaces</em>. As an example, this means that one client on a <a class="reference internal" href="#interfaces-tcps"><span class="std std-ref">TCP Server Interface</span></a> 1522 cannot disrupt processing of incoming announces for other connected clients on the same 1523 <a class="reference internal" href="#interfaces-tcps"><span class="std std-ref">TCP Server Interface</span></a>. All other clients on the same interface will still have new announces 1524 processed without interruption.</p> 1525 <p>By default, Reticulum will handle this automatically, and ingress announce 1526 control will be enabled on interface where it is sensible to do so. It should 1527 generally not be neccessary to modify the ingress control configuration, 1528 but all the parameters are exposed for configuration if needed.</p> 1529 <blockquote> 1530 <div><ul> 1531 <li><div class="line-block"> 1532 <div class="line">The <code class="docutils literal notranslate"><span class="pre">ingress_control</span></code> option tells Reticulum whether or not 1533 to enable announce ingress control on the interface. Defaults to 1534 <code class="docutils literal notranslate"><span class="pre">True</span></code>.</div> 1535 </div> 1536 </li> 1537 <li><div class="line-block"> 1538 <div class="line">The <code class="docutils literal notranslate"><span class="pre">ic_new_time</span></code> option configures how long (in seconds) an 1539 interface is considered newly spawned. Defaults to <code class="docutils literal notranslate"><span class="pre">2*60*60</span></code> seconds. This 1540 option is useful on publicly accessible interfaces that spawn new 1541 sub-interfaces when a new client connects.</div> 1542 </div> 1543 </li> 1544 <li><div class="line-block"> 1545 <div class="line">The <code class="docutils literal notranslate"><span class="pre">ic_burst_freq_new</span></code> option sets the maximum announce ingress 1546 frequency for newly spawned interfaces. Defaults to <code class="docutils literal notranslate"><span class="pre">3.5</span></code> 1547 announces per second.</div> 1548 </div> 1549 </li> 1550 <li><div class="line-block"> 1551 <div class="line">The <code class="docutils literal notranslate"><span class="pre">ic_burst_freq</span></code> option sets the maximum announce ingress 1552 frequency for other interfaces. Defaults to <code class="docutils literal notranslate"><span class="pre">12</span></code> announces 1553 per second.</div> 1554 </div> 1555 <blockquote> 1556 <div><p><em>If an interface exceeds its burst frequency, incoming announces 1557 for unknown destinations will be temporarily held in a queue, and 1558 not processed until later.</em></p> 1559 </div></blockquote> 1560 </li> 1561 <li><div class="line-block"> 1562 <div class="line">The <code class="docutils literal notranslate"><span class="pre">ic_max_held_announces</span></code> option sets the maximum amount of 1563 unique announces that will be held in the queue. Any additional 1564 unique announces will be dropped. Defaults to <code class="docutils literal notranslate"><span class="pre">256</span></code> announces.</div> 1565 </div> 1566 </li> 1567 <li><div class="line-block"> 1568 <div class="line">The <code class="docutils literal notranslate"><span class="pre">ic_burst_hold</span></code> option sets how much time (in seconds) must 1569 pass after the burst frequency drops below its threshold, for the 1570 announce burst to be considered cleared. Defaults to <code class="docutils literal notranslate"><span class="pre">60</span></code> 1571 seconds.</div> 1572 </div> 1573 </li> 1574 <li><div class="line-block"> 1575 <div class="line">The <code class="docutils literal notranslate"><span class="pre">ic_burst_penalty</span></code> option sets how much time (in seconds) must 1576 pass after the burst is considered cleared, before held announces can 1577 start being released from the queue. Defaults to <code class="docutils literal notranslate"><span class="pre">5*60</span></code> 1578 seconds.</div> 1579 </div> 1580 </li> 1581 <li><div class="line-block"> 1582 <div class="line">The <code class="docutils literal notranslate"><span class="pre">ic_held_release_interval</span></code> option sets how much time (in seconds) 1583 must pass between releasing each held announce from the queue. Defaults 1584 to <code class="docutils literal notranslate"><span class="pre">30</span></code> seconds.</div> 1585 </div> 1586 </li> 1587 </ul> 1588 </div></blockquote> 1589 </section> 1590 </section> 1591 1592 </article> 1593 </div> 1594 <footer> 1595 1596 <div class="related-pages"> 1597 <a class="next-page" href="networks.html"> 1598 <div class="page-info"> 1599 <div class="context"> 1600 <span>Next</span> 1601 </div> 1602 <div class="title">Building Networks</div> 1603 </div> 1604 <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg> 1605 </a> 1606 <a class="prev-page" href="hardware.html"> 1607 <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg> 1608 <div class="page-info"> 1609 <div class="context"> 1610 <span>Previous</span> 1611 </div> 1612 1613 <div class="title">Communications Hardware</div> 1614 1615 </div> 1616 </a> 1617 </div> 1618 <div class="bottom-of-page"> 1619 <div class="left-details"> 1620 <div class="copyright"> 1621 Copyright © 2025, Mark Qvist 1622 </div> 1623 Generated with <a href="https://www.sphinx-doc.org/">Sphinx</a> and 1624 <a href="https://github.com/pradyunsg/furo">Furo</a> 1625 1626 </div> 1627 <div class="right-details"> 1628 1629 </div> 1630 </div> 1631 1632 </footer> 1633 </div> 1634 <aside class="toc-drawer"> 1635 1636 1637 <div class="toc-sticky toc-scroll"> 1638 <div class="toc-title-container"> 1639 <span class="toc-title"> 1640 On this page 1641 </span> 1642 </div> 1643 <div class="toc-tree-container"> 1644 <div class="toc-tree"> 1645 <ul> 1646 <li><a class="reference internal" href="#">Configuring Interfaces</a><ul> 1647 <li><a class="reference internal" href="#custom-interfaces">Custom Interfaces</a></li> 1648 <li><a class="reference internal" href="#auto-interface">Auto Interface</a></li> 1649 <li><a class="reference internal" href="#backbone-interface">Backbone Interface</a><ul> 1650 <li><a class="reference internal" href="#listeners">Listeners</a></li> 1651 <li><a class="reference internal" href="#connecting-remotes">Connecting Remotes</a></li> 1652 </ul> 1653 </li> 1654 <li><a class="reference internal" href="#tcp-server-interface">TCP Server Interface</a></li> 1655 <li><a class="reference internal" href="#tcp-client-interface">TCP Client Interface</a></li> 1656 <li><a class="reference internal" href="#udp-interface">UDP Interface</a></li> 1657 <li><a class="reference internal" href="#i2p-interface">I2P Interface</a></li> 1658 <li><a class="reference internal" href="#rnode-lora-interface">RNode LoRa Interface</a></li> 1659 <li><a class="reference internal" href="#rnode-multi-interface">RNode Multi Interface</a></li> 1660 <li><a class="reference internal" href="#serial-interface">Serial Interface</a></li> 1661 <li><a class="reference internal" href="#pipe-interface">Pipe Interface</a></li> 1662 <li><a class="reference internal" href="#kiss-interface">KISS Interface</a></li> 1663 <li><a class="reference internal" href="#ax-25-kiss-interface">AX.25 KISS Interface</a></li> 1664 <li><a class="reference internal" href="#discoverable-interfaces">Discoverable Interfaces</a><ul> 1665 <li><a class="reference internal" href="#enabling-discovery">Enabling Discovery</a></li> 1666 <li><a class="reference internal" href="#discovery-parameters">Discovery Parameters</a></li> 1667 <li><a class="reference internal" href="#interface-modes">Interface Modes</a></li> 1668 <li><a class="reference internal" href="#security-considerations">Security Considerations</a></li> 1669 <li><a class="reference internal" href="#example-configuration">Example Configuration</a></li> 1670 </ul> 1671 </li> 1672 <li><a class="reference internal" href="#common-interface-options">Common Interface Options</a></li> 1673 <li><a class="reference internal" href="#interfaces-modes">Interface Modes</a></li> 1674 <li><a class="reference internal" href="#announce-rate-control">Announce Rate Control</a></li> 1675 <li><a class="reference internal" href="#new-destination-rate-limiting">New Destination Rate Limiting</a></li> 1676 </ul> 1677 </li> 1678 </ul> 1679 1680 </div> 1681 </div> 1682 </div> 1683 1684 1685 </aside> 1686 </div> 1687 </div><script src="_static/documentation_options.js?v=cb7bf70b"></script> 1688 <script src="_static/doctools.js?v=9bcbadda"></script> 1689 <script src="_static/sphinx_highlight.js?v=dc90522c"></script> 1690 <script src="_static/scripts/furo.js?v=46bd48cc"></script> 1691 <script src="_static/clipboard.min.js?v=a7894cd8"></script> 1692 <script src="_static/copybutton.js?v=f281be69"></script> 1693 </body> 1694 </html>