interfaces.html
1 <!doctype html> 2 <html class="no-js" lang="en"> 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 8 <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29.dev1"/> 9 <title>Configuring Interfaces - Reticulum Network Stack 1.0.0 documentation</title> 10 <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> 11 <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=189ec851f9bb375a2509b67be1f64f0cf212b702" /> 12 <link rel="stylesheet" type="text/css" href="_static/copybutton.css" /> 13 <link rel="stylesheet" type="text/css" href="_static/styles/furo-extensions.css?digest=30d1aed668e5c3a91c3e3bf6a60b675221979f0e" /> 14 <link rel="stylesheet" type="text/css" href="_static/custom.css" /> 15 16 17 18 19 <style> 20 body { 21 --color-code-background: #f8f8f8; 22 --color-code-foreground: black; 23 24 } 25 @media not print { 26 body[data-theme="dark"] { 27 --color-code-background: #202020; 28 --color-code-foreground: #d0d0d0; 29 --color-background-primary: #202b38; 30 --color-background-secondary: #161f27; 31 --color-foreground-primary: #dbdbdb; 32 --color-foreground-secondary: #a9b1ba; 33 --color-brand-primary: #41adff; 34 --color-background-hover: #161f27; 35 --color-api-name: #ffbe85; 36 --color-api-pre-name: #efae75; 37 38 } 39 @media (prefers-color-scheme: dark) { 40 body:not([data-theme="light"]) { 41 --color-code-background: #202020; 42 --color-code-foreground: #d0d0d0; 43 --color-background-primary: #202b38; 44 --color-background-secondary: #161f27; 45 --color-foreground-primary: #dbdbdb; 46 --color-foreground-secondary: #a9b1ba; 47 --color-brand-primary: #41adff; 48 --color-background-hover: #161f27; 49 --color-api-name: #ffbe85; 50 --color-api-pre-name: #efae75; 51 52 } 53 } 54 } 55 </style></head> 56 <body> 57 58 <script> 59 document.body.dataset.theme = localStorage.getItem("theme") || "auto"; 60 </script> 61 62 63 <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> 64 <symbol id="svg-toc" viewBox="0 0 24 24"> 65 <title>Contents</title> 66 <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 1024 1024"> 67 <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"/> 68 </svg> 69 </symbol> 70 <symbol id="svg-menu" viewBox="0 0 24 24"> 71 <title>Menu</title> 72 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" 73 stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-menu"> 74 <line x1="3" y1="12" x2="21" y2="12"></line> 75 <line x1="3" y1="6" x2="21" y2="6"></line> 76 <line x1="3" y1="18" x2="21" y2="18"></line> 77 </svg> 78 </symbol> 79 <symbol id="svg-arrow-right" viewBox="0 0 24 24"> 80 <title>Expand</title> 81 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" 82 stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-chevron-right"> 83 <polyline points="9 18 15 12 9 6"></polyline> 84 </svg> 85 </symbol> 86 <symbol id="svg-sun" viewBox="0 0 24 24"> 87 <title>Light mode</title> 88 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" 89 stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="feather-sun"> 90 <circle cx="12" cy="12" r="5"></circle> 91 <line x1="12" y1="1" x2="12" y2="3"></line> 92 <line x1="12" y1="21" x2="12" y2="23"></line> 93 <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line> 94 <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line> 95 <line x1="1" y1="12" x2="3" y2="12"></line> 96 <line x1="21" y1="12" x2="23" y2="12"></line> 97 <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line> 98 <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line> 99 </svg> 100 </symbol> 101 <symbol id="svg-moon" viewBox="0 0 24 24"> 102 <title>Dark mode</title> 103 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" 104 stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-moon"> 105 <path stroke="none" d="M0 0h24v24H0z" fill="none" /> 106 <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" /> 107 </svg> 108 </symbol> 109 <symbol id="svg-sun-half" viewBox="0 0 24 24"> 110 <title>Auto light/dark mode</title> 111 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" 112 stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-shadow"> 113 <path stroke="none" d="M0 0h24v24H0z" fill="none"/> 114 <circle cx="12" cy="12" r="9" /> 115 <path d="M13 12h5" /> 116 <path d="M13 15h4" /> 117 <path d="M13 18h1" /> 118 <path d="M13 9h4" /> 119 <path d="M13 6h1" /> 120 </svg> 121 </symbol> 122 </svg> 123 124 <input type="checkbox" class="sidebar-toggle" name="__navigation" id="__navigation"> 125 <input type="checkbox" class="sidebar-toggle" name="__toc" id="__toc"> 126 <label class="overlay sidebar-overlay" for="__navigation"> 127 <div class="visually-hidden">Hide navigation sidebar</div> 128 </label> 129 <label class="overlay toc-overlay" for="__toc"> 130 <div class="visually-hidden">Hide table of contents sidebar</div> 131 </label> 132 133 134 135 <div class="page"> 136 <header class="mobile-header"> 137 <div class="header-left"> 138 <label class="nav-overlay-icon" for="__navigation"> 139 <div class="visually-hidden">Toggle site navigation sidebar</div> 140 <i class="icon"><svg><use href="#svg-menu"></use></svg></i> 141 </label> 142 </div> 143 <div class="header-center"> 144 <a href="index.html"><div class="brand">Reticulum Network Stack 1.0.0 documentation</div></a> 145 </div> 146 <div class="header-right"> 147 <div class="theme-toggle-container theme-toggle-header"> 148 <button class="theme-toggle"> 149 <div class="visually-hidden">Toggle Light / Dark / Auto color theme</div> 150 <svg class="theme-icon-when-auto"><use href="#svg-sun-half"></use></svg> 151 <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg> 152 <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg> 153 </button> 154 </div> 155 <label class="toc-overlay-icon toc-header-icon" for="__toc"> 156 <div class="visually-hidden">Toggle table of contents sidebar</div> 157 <i class="icon"><svg><use href="#svg-toc"></use></svg></i> 158 </label> 159 </div> 160 </header> 161 <aside class="sidebar-drawer"> 162 <div class="sidebar-container"> 163 164 <div class="sidebar-sticky"><a class="sidebar-brand centered" href="index.html"> 165 166 <div class="sidebar-logo-container"> 167 <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/> 168 </div> 169 170 <span class="sidebar-brand-text">Reticulum Network Stack 1.0.0 documentation</span> 171 172 </a><form class="sidebar-search-container" method="get" action="search.html" role="search"> 173 <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search"> 174 <input type="hidden" name="check_keywords" value="yes"> 175 <input type="hidden" name="area" value="default"> 176 </form> 177 <div id="searchbox"></div><div class="sidebar-scroll"><div class="sidebar-tree"> 178 <ul class="current"> 179 <li class="toctree-l1"><a class="reference internal" href="whatis.html">What is Reticulum?</a></li> 180 <li class="toctree-l1"><a class="reference internal" href="gettingstartedfast.html">Getting Started Fast</a></li> 181 <li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li> 182 <li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li> 183 <li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li> 184 <li class="toctree-l1 current current-page"><a class="current reference internal" href="#">Configuring Interfaces</a></li> 185 <li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks</a></li> 186 <li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a></li> 187 <li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a></li> 188 </ul> 189 <ul> 190 <li class="toctree-l1"><a class="reference internal" href="reference.html">API Reference</a></li> 191 </ul> 192 193 </div> 194 </div> 195 196 </div> 197 198 </div> 199 </aside> 200 <div class="main"> 201 <div class="content"> 202 <div class="article-container"> 203 <a href="#" class="back-to-top muted-link"> 204 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"> 205 <path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8v12z"></path> 206 </svg> 207 <span>Back to top</span> 208 </a> 209 <div class="content-icon-container"> 210 <div class="theme-toggle-container theme-toggle-content"> 211 <button class="theme-toggle"> 212 <div class="visually-hidden">Toggle Light / Dark / Auto color theme</div> 213 <svg class="theme-icon-when-auto"><use href="#svg-sun-half"></use></svg> 214 <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg> 215 <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg> 216 </button> 217 </div> 218 <label class="toc-overlay-icon toc-content-icon" for="__toc"> 219 <div class="visually-hidden">Toggle table of contents sidebar</div> 220 <i class="icon"><svg><use href="#svg-toc"></use></svg></i> 221 </label> 222 </div> 223 <article role="main"> 224 <section id="configuring-interfaces"> 225 <span id="interfaces-main"></span><h1>Configuring Interfaces<a class="headerlink" href="#configuring-interfaces" title="Permalink to this heading">#</a></h1> 226 <p>Reticulum supports using many kinds of devices as networking interfaces, and 227 allows you to mix and match them in any way you choose. The number of distinct 228 network topologies you can create with Reticulum is more or less endless, but 229 common to them all is that you will need to define one or more <em>interfaces</em> 230 for Reticulum to use.</p> 231 <p>The following sections describe the interfaces currently available in Reticulum, 232 and gives example configurations for the respective interface types.</p> 233 <p>For a high-level overview of how networks can be formed over different interface 234 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 235 manual.</p> 236 <section id="custom-interfaces"> 237 <span id="interfaces-custom"></span><h2>Custom Interfaces<a class="headerlink" href="#custom-interfaces" title="Permalink to this heading">#</a></h2> 238 <p>In addition to the built-in interface types, Reticulum is <strong>fully extensible</strong> with 239 custom, user- or community-supplied interfaces, and creating custom interface 240 modules is straightforward. Please see the <a class="reference internal" href="examples.html#example-custominterface"><span class="std std-ref">custom interface</span></a> 241 example for basic interface code to build upon.</p> 242 </section> 243 <section id="auto-interface"> 244 <span id="interfaces-auto"></span><h2>Auto Interface<a class="headerlink" href="#auto-interface" title="Permalink to this heading">#</a></h2> 245 <p>The <code class="docutils literal notranslate"><span class="pre">AutoInterface</span></code> enables communication with other discoverable Reticulum 246 nodes over any kind of local Ethernet or WiFi-based medium. Even though it uses IPv6 for peer 247 discovery, and UDP for packet transport, it <strong>does not</strong> need any functional IP 248 infrastructure like routers or DHCP servers, on your physical network.</p> 249 <p>As long as there is at least some sort of switching medium present between peers (a 250 wired switch, a hub, a WiFi access point or similar, or simply two devices connected 251 directly by Ethernet cable), it will work without any configuration, setup or intermediary devices.</p> 252 <p>For <code class="docutils literal notranslate"><span class="pre">AutoInterface</span></code> peer discovery to work, it’s also required that link-local 253 IPv6 support is available on your system, which it should be by default in all 254 current operating systems, both desktop and mobile.</p> 255 <div class="admonition note"> 256 <p class="admonition-title">Note</p> 257 <p>Almost all current Ethernet and WiFi hardware will work without any kind 258 of configuration or setup with <code class="docutils literal notranslate"><span class="pre">AutoInterface</span></code>, but a small subset of 259 devices turn on options that limit device-to-device communication by default, 260 resulting in <code class="docutils literal notranslate"><span class="pre">AutoInterface</span></code> peer discovery being blocked. This issue is 261 most commonly seen on very cheap, ISP-supplied WiFi routers, and can sometimes 262 be turned off in the router configuration.</p> 263 </div> 264 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># This example demonstrates a bare-minimum setup</span> 265 <span class="c1"># of an Auto Interface. It will allow communica-</span> 266 <span class="c1"># tion with all other reachable devices on all</span> 267 <span class="c1"># usable physical ethernet-based devices that</span> 268 <span class="c1"># are available on the system.</span> 269 <span class="p">[[</span><span class="n">Default</span> <span class="n">Interface</span><span class="p">]]</span> 270 <span class="nb">type</span> <span class="o">=</span> <span class="n">AutoInterface</span> 271 <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span> 272 273 <span class="c1"># This example demonstrates an more specifically</span> 274 <span class="c1"># configured Auto Interface, that only uses spe-</span> 275 <span class="c1"># cific physical interfaces, and has a number of</span> 276 <span class="c1"># other configuration options set.</span> 277 <span class="p">[[</span><span class="n">Default</span> <span class="n">Interface</span><span class="p">]]</span> 278 <span class="nb">type</span> <span class="o">=</span> <span class="n">AutoInterface</span> 279 <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span> 280 281 <span class="c1"># You can create multiple isolated Reticulum</span> 282 <span class="c1"># networks on the same physical LAN by</span> 283 <span class="c1"># specifying different Group IDs.</span> 284 <span class="n">group_id</span> <span class="o">=</span> <span class="n">reticulum</span> 285 286 <span class="c1"># You can also choose the multicast address type:</span> 287 <span class="c1"># temporary (default, Temporary Multicast Address)</span> 288 <span class="c1"># or permanent (Permanent Multicast Address)</span> 289 <span class="n">multicast_address_type</span> <span class="o">=</span> <span class="n">permanent</span> 290 291 <span class="c1"># You can also select specifically which</span> 292 <span class="c1"># kernel networking devices to use.</span> 293 <span class="n">devices</span> <span class="o">=</span> <span class="n">wlan0</span><span class="p">,</span><span class="n">eth1</span> 294 295 <span class="c1"># Or let AutoInterface use all suitable</span> 296 <span class="c1"># devices except for a list of ignored ones.</span> 297 <span class="n">ignored_devices</span> <span class="o">=</span> <span class="n">tun0</span><span class="p">,</span><span class="n">eth0</span> 298 </pre></div> 299 </div> 300 <p>If you are connected to the Internet with IPv6, and your provider will route 301 IPv6 multicast, you can potentially configure the Auto Interface to globally 302 autodiscover other Reticulum nodes within your selected Group ID. You can specify 303 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>, 304 <code class="docutils literal notranslate"><span class="pre">organisation</span></code> or <code class="docutils literal notranslate"><span class="pre">global</span></code>.</p> 305 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">Default</span> <span class="n">Interface</span><span class="p">]]</span> 306 <span class="nb">type</span> <span class="o">=</span> <span class="n">AutoInterface</span> 307 <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span> 308 309 <span class="c1"># Configure global discovery</span> 310 311 <span class="n">group_id</span> <span class="o">=</span> <span class="n">custom_network_name</span> 312 <span class="n">discovery_scope</span> <span class="o">=</span> <span class="k">global</span> 313 314 <span class="c1"># Other configuration options</span> 315 316 <span class="n">discovery_port</span> <span class="o">=</span> <span class="mi">48555</span> 317 <span class="n">data_port</span> <span class="o">=</span> <span class="mi">49555</span> 318 </pre></div> 319 </div> 320 </section> 321 <section id="backbone-interface"> 322 <span id="interfaces-backbone"></span><h2>Backbone Interface<a class="headerlink" href="#backbone-interface" title="Permalink to this heading">#</a></h2> 323 <p>The Backbone interface is a very fast and resource efficient interface type, primarily 324 intended for interconnecting Reticulum instances over many different types of mediums. 325 It uses a kernel-event I/O backend, and can handle thousands of interfaces and/or clients 326 with relatively low system resource utilisation. <strong>This interface type is currently only 327 supported on Linux and Android</strong>.</p> 328 <div class="admonition note"> 329 <p class="admonition-title">Note</p> 330 <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> 331 types, and they can be used interchangably, and cross-connect with each other. On systems that support 332 <code class="docutils literal notranslate"><span class="pre">BackboneInterface</span></code>, it is generally recommended to use it, unless you need specific options or 333 features that the TCP server and client interfaces provide.</p> 334 </div> 335 <p>While the goal is to support <em>all</em> socket types and I/O devices provided by the underlying 336 operating system, the initial release only provides support for TCP connections over IPv4 337 and IPv6.</p> 338 <p>For all types of connections over a <code class="docutils literal notranslate"><span class="pre">BackboneInterface</span></code>, Reticulum will gracefully 339 handle intermittency, link loss, and connections that come and go.</p> 340 <section id="listeners"> 341 <h3>Listeners<a class="headerlink" href="#listeners" title="Permalink to this heading">#</a></h3> 342 <p>The following examples illustrates various ways to set up <code class="docutils literal notranslate"><span class="pre">BackboneInterface</span></code> listeners.</p> 343 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># This example demonstrates a backbone interface</span> 344 <span class="c1"># that listens for incoming connections on the</span> 345 <span class="c1"># specified IP address and port number.</span> 346 <span class="p">[[</span><span class="n">Backbone</span> <span class="n">Listener</span><span class="p">]]</span> 347 <span class="nb">type</span> <span class="o">=</span> <span class="n">BackboneInterface</span> 348 <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span> 349 <span class="n">listen_on</span> <span class="o">=</span> <span class="mf">0.0.0.0</span> 350 <span class="n">port</span> <span class="o">=</span> <span class="mi">4242</span> 351 352 <span class="c1"># Alternatively you can bind to a specific IP</span> 353 <span class="p">[[</span><span class="n">Backbone</span> <span class="n">Listener</span><span class="p">]]</span> 354 <span class="nb">type</span> <span class="o">=</span> <span class="n">BackboneInterface</span> 355 <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span> 356 <span class="n">listen_on</span> <span class="o">=</span> <span class="mf">10.0.0.88</span> 357 <span class="n">port</span> <span class="o">=</span> <span class="mi">4242</span> 358 359 <span class="c1"># Or a specific network device</span> 360 <span class="p">[[</span><span class="n">Backbone</span> <span class="n">Listener</span><span class="p">]]</span> 361 <span class="nb">type</span> <span class="o">=</span> <span class="n">BackboneInterface</span> 362 <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span> 363 <span class="n">device</span> <span class="o">=</span> <span class="n">eth0</span> 364 <span class="n">port</span> <span class="o">=</span> <span class="mi">4242</span> 365 </pre></div> 366 </div> 367 <p>If you are using the interface on a device which has both IPv4 and IPv6 addresses available, 368 you can use the <code class="docutils literal notranslate"><span class="pre">prefer_ipv6</span></code> option to bind to the IPv6 address:</p> 369 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># This example demonstrates a backbone interface</span> 370 <span class="c1"># listening on the IPv6 address of a specified</span> 371 <span class="c1"># kernel networking device.</span> 372 <span class="p">[[</span><span class="n">Backbone</span> <span class="n">Listener</span><span class="p">]]</span> 373 <span class="nb">type</span> <span class="o">=</span> <span class="n">BackboneInterface</span> 374 <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span> 375 <span class="n">prefer_ipv6</span> <span class="o">=</span> <span class="n">yes</span> 376 <span class="n">device</span> <span class="o">=</span> <span class="n">eth0</span> 377 <span class="n">port</span> <span class="o">=</span> <span class="mi">4242</span> 378 </pre></div> 379 </div> 380 <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 381 can simply specify the Yggdrasil <code class="docutils literal notranslate"><span class="pre">tun</span></code> device and a listening port, like so:</p> 382 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># This example demonstrates a backbone interface</span> 383 <span class="c1"># listening for connections over Yggdrasil.</span> 384 <span class="p">[[</span><span class="n">Yggdrasil</span> <span class="n">Backbone</span> <span class="n">Interface</span><span class="p">]]</span> 385 <span class="nb">type</span> <span class="o">=</span> <span class="n">BackboneInterface</span> 386 <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span> 387 <span class="n">device</span> <span class="o">=</span> <span class="n">tun0</span> 388 <span class="n">port</span> <span class="o">=</span> <span class="mi">4343</span> 389 </pre></div> 390 </div> 391 </section> 392 <section id="connecting-remotes"> 393 <h3>Connecting Remotes<a class="headerlink" href="#connecting-remotes" title="Permalink to this heading">#</a></h3> 394 <p>The following examples illustrates various ways to connect to remote <code class="docutils literal notranslate"><span class="pre">BackboneInterface</span></code> listeners. 395 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>, 396 and as such these interface types can be used interchangably.</p> 397 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Here's an example of a backbone interface that</span> 398 <span class="c1"># connects to a remote listener.</span> 399 <span class="p">[[</span><span class="n">Backbone</span> <span class="n">Remote</span><span class="p">]]</span> 400 <span class="nb">type</span> <span class="o">=</span> <span class="n">BackboneInterface</span> 401 <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span> 402 <span class="n">remote</span> <span class="o">=</span> <span class="n">amsterdam</span><span class="o">.</span><span class="n">connect</span><span class="o">.</span><span class="n">reticulum</span><span class="o">.</span><span class="n">network</span> 403 <span class="n">target_port</span> <span class="o">=</span> <span class="mi">4251</span> 404 </pre></div> 405 </div> 406 <p>To connect to remotes over <a class="reference external" href="https://yggdrasil-network.github.io/">Yggdrasil</a>, simply 407 specify the target Yggdrasil IPv6 address and port, like so:</p> 408 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">Yggdrasil</span> <span class="n">Remote</span><span class="p">]]</span> 409 <span class="nb">type</span> <span class="o">=</span> <span class="n">BackboneInterface</span> 410 <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span> 411 <span class="n">target_host</span> <span class="o">=</span> <span class="mi">201</span><span class="p">:</span><span class="mi">5</span><span class="n">d78</span><span class="p">:</span><span class="n">af73</span><span class="p">:</span><span class="mi">5</span><span class="n">caf</span><span class="p">:</span><span class="n">a4de</span><span class="p">:</span><span class="n">a79f</span><span class="p">:</span><span class="mi">3278</span><span class="p">:</span><span class="mf">71e5</span> 412 <span class="n">target_port</span> <span class="o">=</span> <span class="mi">4343</span> 413 </pre></div> 414 </div> 415 </section> 416 </section> 417 <section id="tcp-server-interface"> 418 <span id="interfaces-tcps"></span><h2>TCP Server Interface<a class="headerlink" href="#tcp-server-interface" title="Permalink to this heading">#</a></h2> 419 <p>The TCP Server interface is suitable for allowing other peers to connect over 420 the Internet or private IPv4 and IPv6 networks. When a TCP server interface has been 421 configured, other Reticulum peers can connect to it with a TCP Client interface.</p> 422 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># This example demonstrates a TCP server interface.</span> 423 <span class="c1"># It will listen for incoming connections on all IP</span> 424 <span class="c1"># interfaces on port 4242.</span> 425 <span class="p">[[</span><span class="n">TCP</span> <span class="n">Server</span> <span class="n">Interface</span><span class="p">]]</span> 426 <span class="nb">type</span> <span class="o">=</span> <span class="n">TCPServerInterface</span> 427 <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span> 428 <span class="n">listen_ip</span> <span class="o">=</span> <span class="mf">0.0.0.0</span> 429 <span class="n">listen_port</span> <span class="o">=</span> <span class="mi">4242</span> 430 431 <span class="c1"># Alternatively you can bind to a specific IP</span> 432 <span class="p">[[</span><span class="n">TCP</span> <span class="n">Server</span> <span class="n">Interface</span><span class="p">]]</span> 433 <span class="nb">type</span> <span class="o">=</span> <span class="n">TCPServerInterface</span> 434 <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span> 435 <span class="n">listen_ip</span> <span class="o">=</span> <span class="mf">10.0.0.88</span> 436 <span class="n">listen_port</span> <span class="o">=</span> <span class="mi">4242</span> 437 438 <span class="c1"># Or a specific network device</span> 439 <span class="p">[[</span><span class="n">TCP</span> <span class="n">Server</span> <span class="n">Interface</span><span class="p">]]</span> 440 <span class="nb">type</span> <span class="o">=</span> <span class="n">TCPServerInterface</span> 441 <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span> 442 <span class="n">device</span> <span class="o">=</span> <span class="n">eth0</span> 443 <span class="n">listen_port</span> <span class="o">=</span> <span class="mi">4242</span> 444 </pre></div> 445 </div> 446 <p>If you are using the interface on a device which has both IPv4 and IPv6 addresses available, 447 you can use the <code class="docutils literal notranslate"><span class="pre">prefer_ipv6</span></code> option to bind to the IPv6 address:</p> 448 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># This example demonstrates a TCP server interface.</span> 449 <span class="c1"># It will listen for incoming connections on the</span> 450 <span class="c1"># specified IP address and port number.</span> 451 452 <span class="p">[[</span><span class="n">TCP</span> <span class="n">Server</span> <span class="n">Interface</span><span class="p">]]</span> 453 <span class="nb">type</span> <span class="o">=</span> <span class="n">TCPServerInterface</span> 454 <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span> 455 <span class="n">prefer_ipv6</span> <span class="o">=</span> <span class="kc">True</span> 456 <span class="n">device</span> <span class="o">=</span> <span class="n">eth0</span> 457 <span class="n">port</span> <span class="o">=</span> <span class="mi">4242</span> 458 </pre></div> 459 </div> 460 <p>To use the TCP Server Interface over <a class="reference external" href="https://yggdrasil-network.github.io/">Yggdrasil</a>, you 461 can simply specify the Yggdrasil <code class="docutils literal notranslate"><span class="pre">tun</span></code> device and a listening port, like so:</p> 462 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">Yggdrasil</span> <span class="n">TCP</span> <span class="n">Server</span> <span class="n">Interface</span><span class="p">]]</span> 463 <span class="nb">type</span> <span class="o">=</span> <span class="n">TCPServerInterface</span> 464 <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span> 465 <span class="n">device</span> <span class="o">=</span> <span class="n">tun0</span> 466 <span class="n">listen_port</span> <span class="o">=</span> <span class="mi">4343</span> 467 </pre></div> 468 </div> 469 <div class="admonition note"> 470 <p class="admonition-title">Note</p> 471 <p>The TCP interfaces support tunneling over I2P, but to do so reliably, 472 you must use the i2p_tunneled option:</p> 473 </div> 474 <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> 475 <span class="nb">type</span> <span class="o">=</span> <span class="n">TCPServerInterface</span> 476 <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span> 477 <span class="n">listen_ip</span> <span class="o">=</span> <span class="mf">127.0.0.1</span> 478 <span class="n">listen_port</span> <span class="o">=</span> <span class="mi">5001</span> 479 <span class="n">i2p_tunneled</span> <span class="o">=</span> <span class="n">yes</span> 480 </pre></div> 481 </div> 482 <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 483 control, and using I2P routers running on external systems, this option also exists.</p> 484 </section> 485 <section id="tcp-client-interface"> 486 <span id="interfaces-tcpc"></span><h2>TCP Client Interface<a class="headerlink" href="#tcp-client-interface" title="Permalink to this heading">#</a></h2> 487 <p>To connect to a TCP server interface, you can use the TCP client 488 interface. Many TCP Client interfaces from different peers can connect to the 489 same TCP Server interface at the same time.</p> 490 <p>The TCP interface types can also tolerate intermittency in the IP link layer. 491 This means that Reticulum will gracefully handle IP links that go up and down, 492 and restore connectivity after a failure, once the other end of a TCP interface reappears.</p> 493 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Here's an example of a TCP Client interface. The</span> 494 <span class="c1"># target_host can be a hostname or an IPv4 or IPv6 address.</span> 495 <span class="p">[[</span><span class="n">TCP</span> <span class="n">Client</span> <span class="n">Interface</span><span class="p">]]</span> 496 <span class="nb">type</span> <span class="o">=</span> <span class="n">TCPClientInterface</span> 497 <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span> 498 <span class="n">target_host</span> <span class="o">=</span> <span class="mf">127.0.0.1</span> 499 <span class="n">target_port</span> <span class="o">=</span> <span class="mi">4242</span> 500 </pre></div> 501 </div> 502 <p>To use the TCP Client Interface over <a class="reference external" href="https://yggdrasil-network.github.io/">Yggdrasil</a>, simply 503 specify the target Yggdrasil IPv6 address and port, like so:</p> 504 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">Yggdrasil</span> <span class="n">TCP</span> <span class="n">Client</span> <span class="n">Interface</span><span class="p">]]</span> 505 <span class="nb">type</span> <span class="o">=</span> <span class="n">TCPClientInterface</span> 506 <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span> 507 <span class="n">target_host</span> <span class="o">=</span> <span class="mi">201</span><span class="p">:</span><span class="mi">5</span><span class="n">d78</span><span class="p">:</span><span class="n">af73</span><span class="p">:</span><span class="mi">5</span><span class="n">caf</span><span class="p">:</span><span class="n">a4de</span><span class="p">:</span><span class="n">a79f</span><span class="p">:</span><span class="mi">3278</span><span class="p">:</span><span class="mf">71e5</span> 508 <span class="n">target_port</span> <span class="o">=</span> <span class="mi">4343</span> 509 </pre></div> 510 </div> 511 <p>It is also possible to use this interface type to connect via other programs 512 or hardware devices that expose a KISS interface on a TCP port, for example 513 software-based soundmodems. To do this, use the <code class="docutils literal notranslate"><span class="pre">kiss_framing</span></code> option:</p> 514 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Here's an example of a TCP Client interface that connects</span> 515 <span class="c1"># to a software TNC soundmodem on a KISS over TCP port.</span> 516 517 <span class="p">[[</span><span class="n">TCP</span> <span class="n">KISS</span> <span class="n">Interface</span><span class="p">]]</span> 518 <span class="nb">type</span> <span class="o">=</span> <span class="n">TCPClientInterface</span> 519 <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span> 520 <span class="n">kiss_framing</span> <span class="o">=</span> <span class="kc">True</span> 521 <span class="n">target_host</span> <span class="o">=</span> <span class="mf">127.0.0.1</span> 522 <span class="n">target_port</span> <span class="o">=</span> <span class="mi">8001</span> 523 </pre></div> 524 </div> 525 <p><strong>Caution!</strong> Only use the KISS framing option when connecting to external devices 526 and programs like soundmodems and similar over TCP. When using the 527 <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 528 never enable <code class="docutils literal notranslate"><span class="pre">kiss_framing</span></code>, since this will disable internal reliability and 529 recovery mechanisms that greatly improves performance over unreliable and 530 intermittent TCP links.</p> 531 <div class="admonition note"> 532 <p class="admonition-title">Note</p> 533 <p>The TCP interfaces support tunneling over I2P, but to do so reliably, 534 you must use the i2p_tunneled option:</p> 535 </div> 536 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">TCP</span> <span class="n">Client</span> <span class="n">over</span> <span class="n">I2P</span><span class="p">]]</span> 537 <span class="nb">type</span> <span class="o">=</span> <span class="n">TCPClientInterface</span> 538 <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span> 539 <span class="n">target_host</span> <span class="o">=</span> <span class="mf">127.0.0.1</span> 540 <span class="n">target_port</span> <span class="o">=</span> <span class="mi">5001</span> 541 <span class="n">i2p_tunneled</span> <span class="o">=</span> <span class="n">yes</span> 542 </pre></div> 543 </div> 544 </section> 545 <section id="udp-interface"> 546 <span id="interfaces-udp"></span><h2>UDP Interface<a class="headerlink" href="#udp-interface" title="Permalink to this heading">#</a></h2> 547 <p>A UDP interface can be useful for communicating over IP networks, both 548 private and the internet. It can also allow broadcast communication 549 over IP networks, so it can provide an easy way to enable connectivity 550 with all other peers on a local area network.</p> 551 <div class="admonition warning"> 552 <p class="admonition-title">Warning</p> 553 <p>Using broadcast UDP traffic has performance implications, 554 especially on WiFi. If your goal is simply to enable easy communication 555 with all peers in your local Ethernet broadcast domain, the 556 <a class="reference internal" href="#interfaces-auto"><span class="std std-ref">Auto Interface</span></a> performs better, and is even 557 easier to use.</p> 558 </div> 559 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># This example enables communication with other</span> 560 <span class="c1"># local Reticulum peers over UDP.</span> 561 562 <span class="p">[[</span><span class="n">UDP</span> <span class="n">Interface</span><span class="p">]]</span> 563 <span class="nb">type</span> <span class="o">=</span> <span class="n">UDPInterface</span> 564 <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span> 565 566 <span class="n">listen_ip</span> <span class="o">=</span> <span class="mf">0.0.0.0</span> 567 <span class="n">listen_port</span> <span class="o">=</span> <span class="mi">4242</span> 568 <span class="n">forward_ip</span> <span class="o">=</span> <span class="mf">255.255.255.255</span> 569 <span class="n">forward_port</span> <span class="o">=</span> <span class="mi">4242</span> 570 571 <span class="c1"># The above configuration will allow communication</span> 572 <span class="c1"># within the local broadcast domains of all local</span> 573 <span class="c1"># IP interfaces.</span> 574 575 <span class="c1"># Instead of specifying listen_ip, listen_port,</span> 576 <span class="c1"># forward_ip and forward_port, you can also bind</span> 577 <span class="c1"># to a specific network device like below.</span> 578 579 <span class="c1"># device = eth0</span> 580 <span class="c1"># port = 4242</span> 581 582 <span class="c1"># Assuming the eth0 device has the address</span> 583 <span class="c1"># 10.55.0.72/24, the above configuration would</span> 584 <span class="c1"># be equivalent to the following manual setup.</span> 585 <span class="c1"># Note that we are both listening and forwarding to</span> 586 <span class="c1"># the broadcast address of the network segments.</span> 587 588 <span class="c1"># listen_ip = 10.55.0.255</span> 589 <span class="c1"># listen_port = 4242</span> 590 <span class="c1"># forward_ip = 10.55.0.255</span> 591 <span class="c1"># forward_port = 4242</span> 592 593 <span class="c1"># You can of course also communicate only with</span> 594 <span class="c1"># a single IP address</span> 595 596 <span class="c1"># listen_ip = 10.55.0.15</span> 597 <span class="c1"># listen_port = 4242</span> 598 <span class="c1"># forward_ip = 10.55.0.16</span> 599 <span class="c1"># forward_port = 4242</span> 600 </pre></div> 601 </div> 602 </section> 603 <section id="i2p-interface"> 604 <span id="interfaces-i2p"></span><h2>I2P Interface<a class="headerlink" href="#i2p-interface" title="Permalink to this heading">#</a></h2> 605 <p>The I2P interface lets you connect Reticulum instances over the 606 <a class="reference external" href="https://i2pd.website">Invisible Internet Protocol</a>. This can be 607 especially useful in cases where you want to host a globally reachable 608 Reticulum instance, but do not have access to any public IP addresses, 609 have a frequently changing IP address, or have firewalls blocking 610 inbound traffic.</p> 611 <p>Using the I2P interface, you will get a globally reachable, portable 612 and persistent I2P address that your Reticulum instance can be reached 613 at.</p> 614 <p>To use the I2P interface, you must have an I2P router running 615 on your system. The easiest way to achieve this is to download and 616 install the <a class="reference external" href="https://github.com/PurpleI2P/i2pd/releases/latest">latest release</a> 617 of the <code class="docutils literal notranslate"><span class="pre">i2pd</span></code> package. For more details about I2P, see the 618 <a class="reference external" href="https://geti2p.net/en/about/intro">geti2p.net website</a>.</p> 619 <p>When an I2P router is running on your system, you can simply add 620 an I2P interface to Reticulum:</p> 621 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">I2P</span><span class="p">]]</span> 622 <span class="nb">type</span> <span class="o">=</span> <span class="n">I2PInterface</span> 623 <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span> 624 <span class="n">connectable</span> <span class="o">=</span> <span class="n">yes</span> 625 </pre></div> 626 </div> 627 <p>On the first start, Reticulum will generate a new I2P address for the 628 interface and start listening for inbound traffic on it. This can take 629 a while the first time, especially if your I2P router was also just 630 started, and is not yet well-connected to the I2P network. When ready, 631 you should see I2P base32 address printed to your log file. You can 632 also inspect the status of the interface using the <code class="docutils literal notranslate"><span class="pre">rnstatus</span></code> utility.</p> 633 <p>To connect to other Reticulum instances over I2P, just add a comma-separated 634 list of I2P base32 addresses to the <code class="docutils literal notranslate"><span class="pre">peers</span></code> option of the interface:</p> 635 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">I2P</span><span class="p">]]</span> 636 <span class="nb">type</span> <span class="o">=</span> <span class="n">I2PInterface</span> 637 <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span> 638 <span class="n">connectable</span> <span class="o">=</span> <span class="n">yes</span> 639 <span class="n">peers</span> <span class="o">=</span> <span class="mi">5</span><span class="n">urvjicpzi7q3ybztsef4i5ow2aq4soktfj7zedz53s47r54jnqq</span><span class="o">.</span><span class="n">b32</span><span class="o">.</span><span class="n">i2p</span> 640 </pre></div> 641 </div> 642 <p>It can take anywhere from a few seconds to a few minutes to establish 643 I2P connections to the desired peers, so Reticulum handles the process 644 in the background, and will output relevant events to the log.</p> 645 <div class="admonition note"> 646 <p class="admonition-title">Note</p> 647 <p>While the I2P interface is the simplest way to use 648 Reticulum over I2P, it is also possible to tunnel the TCP server and 649 client interfaces over I2P manually. This can be useful in situations 650 where more control is needed, but requires manual tunnel setup through 651 the I2P daemon configuration.</p> 652 </div> 653 <p>It is important to note that the two methods are <em>interchangably compatible</em>. 654 You can use the I2PInterface to connect to a TCPServerInterface that 655 was manually tunneled over I2P, for example. This offers a high degree 656 of flexibility in network setup, while retaining ease of use in simpler 657 use-cases.</p> 658 </section> 659 <section id="rnode-lora-interface"> 660 <span id="interfaces-rnode"></span><h2>RNode LoRa Interface<a class="headerlink" href="#rnode-lora-interface" title="Permalink to this heading">#</a></h2> 661 <p>To use Reticulum over LoRa, the <a class="reference external" href="https://unsigned.io/rnode/">RNode</a> interface 662 can be used, and offers full control over LoRa parameters.</p> 663 <div class="admonition warning"> 664 <p class="admonition-title">Warning</p> 665 <p>Radio frequency spectrum is a legally controlled resource, and legislation 666 varies widely around the world. It is your responsibility to be aware of any 667 relevant regulation for your location, and to make decisions accordingly.</p> 668 </div> 669 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Here's an example of how to add a LoRa interface</span> 670 <span class="c1"># using the RNode LoRa transceiver.</span> 671 672 <span class="p">[[</span><span class="n">RNode</span> <span class="n">LoRa</span> <span class="n">Interface</span><span class="p">]]</span> 673 <span class="nb">type</span> <span class="o">=</span> <span class="n">RNodeInterface</span> 674 675 <span class="c1"># Enable interface if you want use it!</span> 676 <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span> 677 678 <span class="c1"># Serial port for the device</span> 679 <span class="n">port</span> <span class="o">=</span> <span class="o">/</span><span class="n">dev</span><span class="o">/</span><span class="n">ttyUSB0</span> 680 681 <span class="c1"># It is also possible to use BLE devices</span> 682 <span class="c1"># instead of wired serial ports. The</span> 683 <span class="c1"># target RNode must be paired with the</span> 684 <span class="c1"># host device before connecting. BLE</span> 685 <span class="c1"># devices can be connected by name,</span> 686 <span class="c1"># BLE MAC address or by any available.</span> 687 688 <span class="c1"># Connect to specific device by name</span> 689 <span class="c1"># port = ble://RNode 3B87</span> 690 691 <span class="c1"># Or by BLE MAC address</span> 692 <span class="c1"># port = ble://F4:12:73:29:4E:89</span> 693 694 <span class="c1"># Or connect to the first available,</span> 695 <span class="c1"># paired device</span> 696 <span class="c1"># port = ble://</span> 697 698 <span class="c1"># Set frequency to 867.2 MHz</span> 699 <span class="n">frequency</span> <span class="o">=</span> <span class="mi">867200000</span> 700 701 <span class="c1"># Set LoRa bandwidth to 125 KHz</span> 702 <span class="n">bandwidth</span> <span class="o">=</span> <span class="mi">125000</span> 703 704 <span class="c1"># Set TX power to 7 dBm (5 mW)</span> 705 <span class="n">txpower</span> <span class="o">=</span> <span class="mi">7</span> 706 707 <span class="c1"># Select spreading factor 8. Valid</span> 708 <span class="c1"># range is 7 through 12, with 7</span> 709 <span class="c1"># being the fastest and 12 having</span> 710 <span class="c1"># the longest range.</span> 711 <span class="n">spreadingfactor</span> <span class="o">=</span> <span class="mi">8</span> 712 713 <span class="c1"># Select coding rate 5. Valid range</span> 714 <span class="c1"># is 5 throough 8, with 5 being the</span> 715 <span class="c1"># fastest, and 8 the longest range.</span> 716 <span class="n">codingrate</span> <span class="o">=</span> <span class="mi">5</span> 717 718 <span class="c1"># You can configure the RNode to send</span> 719 <span class="c1"># out identification on the channel with</span> 720 <span class="c1"># a set interval by configuring the</span> 721 <span class="c1"># following two parameters.</span> 722 723 <span class="c1"># id_callsign = MYCALL-0</span> 724 <span class="c1"># id_interval = 600</span> 725 726 <span class="c1"># For certain homebrew RNode interfaces</span> 727 <span class="c1"># with low amounts of RAM, using packet</span> 728 <span class="c1"># flow control can be useful. By default</span> 729 <span class="c1"># it is disabled.</span> 730 731 <span class="c1"># flow_control = False</span> 732 733 <span class="c1"># It is possible to limit the airtime</span> 734 <span class="c1"># utilisation of an RNode by using the</span> 735 <span class="c1"># following two configuration options.</span> 736 <span class="c1"># The short-term limit is applied in a</span> 737 <span class="c1"># window of approximately 15 seconds,</span> 738 <span class="c1"># and the long-term limit is enforced</span> 739 <span class="c1"># over a rolling 60 minute window. Both</span> 740 <span class="c1"># options are specified in percent.</span> 741 742 <span class="c1"># airtime_limit_long = 1.5</span> 743 <span class="c1"># airtime_limit_short = 33</span> 744 </pre></div> 745 </div> 746 </section> 747 <section id="rnode-multi-interface"> 748 <span id="interfaces-rnode-multi"></span><h2>RNode Multi Interface<a class="headerlink" href="#rnode-multi-interface" title="Permalink to this heading">#</a></h2> 749 <p>For RNodes that support multiple LoRa transceivers, the RNode 750 Multi interface can be used to configure sub-interfaces individually.</p> 751 <div class="admonition warning"> 752 <p class="admonition-title">Warning</p> 753 <p>Radio frequency spectrum is a legally controlled resource, and legislation 754 varies widely around the world. It is your responsibility to be aware of any 755 relevant regulation for your location, and to make decisions accordingly.</p> 756 </div> 757 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Here's an example of how to add an RNode Multi interface</span> 758 <span class="c1"># using the RNode LoRa transceiver.</span> 759 760 <span class="p">[[</span><span class="n">RNode</span> <span class="n">Multi</span> <span class="n">Interface</span><span class="p">]]</span> 761 <span class="nb">type</span> <span class="o">=</span> <span class="n">RNodeMultiInterface</span> 762 763 <span class="c1"># Enable interface if you want to use it!</span> 764 <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span> 765 766 <span class="c1"># Serial port for the device</span> 767 <span class="n">port</span> <span class="o">=</span> <span class="o">/</span><span class="n">dev</span><span class="o">/</span><span class="n">ttyACM0</span> 768 769 <span class="c1"># You can configure the RNode to send</span> 770 <span class="c1"># out identification on the channel with</span> 771 <span class="c1"># a set interval by configuring the</span> 772 <span class="c1"># following two parameters.</span> 773 774 <span class="c1"># id_callsign = MYCALL-0</span> 775 <span class="c1"># id_interval = 600</span> 776 777 <span class="c1"># A subinterface</span> 778 <span class="p">[[[</span><span class="n">High</span> <span class="n">Datarate</span><span class="p">]]]</span> 779 <span class="c1"># Subinterfaces can be enabled and disabled in of themselves</span> 780 <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span> 781 782 <span class="c1"># Set frequency to 2.4GHz</span> 783 <span class="n">frequency</span> <span class="o">=</span> <span class="mi">2400000000</span> 784 785 <span class="c1"># Set LoRa bandwidth to 1625 KHz</span> 786 <span class="n">bandwidth</span> <span class="o">=</span> <span class="mi">1625000</span> 787 788 <span class="c1"># Set TX power to 0 dBm (0.12 mW)</span> 789 <span class="n">txpower</span> <span class="o">=</span> <span class="mi">0</span> 790 791 <span class="c1"># The virtual port, only the manufacturer</span> 792 <span class="c1"># or the person who wrote the board config</span> 793 <span class="c1"># can tell you what it will be for which</span> 794 <span class="c1"># physical hardware interface</span> 795 <span class="n">vport</span> <span class="o">=</span> <span class="mi">1</span> 796 797 <span class="c1"># Select spreading factor 5. Valid</span> 798 <span class="c1"># range is 5 through 12, with 5</span> 799 <span class="c1"># being the fastest and 12 having</span> 800 <span class="c1"># the longest range.</span> 801 <span class="n">spreadingfactor</span> <span class="o">=</span> <span class="mi">5</span> 802 803 <span class="c1"># Select coding rate 5. Valid range</span> 804 <span class="c1"># is 5 throough 8, with 5 being the</span> 805 <span class="c1"># fastest, and 8 the longest range.</span> 806 <span class="n">codingrate</span> <span class="o">=</span> <span class="mi">5</span> 807 808 <span class="c1"># It is possible to limit the airtime</span> 809 <span class="c1"># utilisation of an RNode by using the</span> 810 <span class="c1"># following two configuration options.</span> 811 <span class="c1"># The short-term limit is applied in a</span> 812 <span class="c1"># window of approximately 15 seconds,</span> 813 <span class="c1"># and the long-term limit is enforced</span> 814 <span class="c1"># over a rolling 60 minute window. Both</span> 815 <span class="c1"># options are specified in percent.</span> 816 817 <span class="c1"># airtime_limit_long = 100</span> 818 <span class="c1"># airtime_limit_short = 100</span> 819 820 <span class="p">[[[</span><span class="n">Low</span> <span class="n">Datarate</span><span class="p">]]]</span> 821 <span class="c1"># Subinterfaces can be enabled and disabled in of themselves</span> 822 <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span> 823 824 <span class="c1"># Set frequency to 865.6 MHz</span> 825 <span class="n">frequency</span> <span class="o">=</span> <span class="mi">865600000</span> 826 827 <span class="c1"># The virtual port, only the manufacturer</span> 828 <span class="c1"># or the person who wrote the board config</span> 829 <span class="c1"># can tell you what it will be for which</span> 830 <span class="c1"># physical hardware interface</span> 831 <span class="n">vport</span> <span class="o">=</span> <span class="mi">0</span> 832 833 <span class="c1"># Set LoRa bandwidth to 125 KHz</span> 834 <span class="n">bandwidth</span> <span class="o">=</span> <span class="mi">125000</span> 835 836 <span class="c1"># Set TX power to 0 dBm (0.12 mW)</span> 837 <span class="n">txpower</span> <span class="o">=</span> <span class="mi">0</span> 838 839 <span class="c1"># Select spreading factor 7. Valid</span> 840 <span class="c1"># range is 5 through 12, with 5</span> 841 <span class="c1"># being the fastest and 12 having</span> 842 <span class="c1"># the longest range.</span> 843 <span class="n">spreadingfactor</span> <span class="o">=</span> <span class="mi">7</span> 844 845 <span class="c1"># Select coding rate 5. Valid range</span> 846 <span class="c1"># is 5 throough 8, with 5 being the</span> 847 <span class="c1"># fastest, and 8 the longest range.</span> 848 <span class="n">codingrate</span> <span class="o">=</span> <span class="mi">5</span> 849 850 <span class="c1"># It is possible to limit the airtime</span> 851 <span class="c1"># utilisation of an RNode by using the</span> 852 <span class="c1"># following two configuration options.</span> 853 <span class="c1"># The short-term limit is applied in a</span> 854 <span class="c1"># window of approximately 15 seconds,</span> 855 <span class="c1"># and the long-term limit is enforced</span> 856 <span class="c1"># over a rolling 60 minute window. Both</span> 857 <span class="c1"># options are specified in percent.</span> 858 859 <span class="c1"># airtime_limit_long = 100</span> 860 <span class="c1"># airtime_limit_short = 100</span> 861 </pre></div> 862 </div> 863 </section> 864 <section id="serial-interface"> 865 <span id="interfaces-serial"></span><h2>Serial Interface<a class="headerlink" href="#serial-interface" title="Permalink to this heading">#</a></h2> 866 <p>Reticulum can be used over serial ports directly, or over any device with a 867 serial port, that will transparently pass data. Useful for communicating 868 directly over a wire-pair, or for using devices such as data radios and lasers.</p> 869 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">Serial</span> <span class="n">Interface</span><span class="p">]]</span> 870 <span class="nb">type</span> <span class="o">=</span> <span class="n">SerialInterface</span> 871 <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span> 872 873 <span class="c1"># Serial port for the device</span> 874 <span class="n">port</span> <span class="o">=</span> <span class="o">/</span><span class="n">dev</span><span class="o">/</span><span class="n">ttyUSB0</span> 875 876 <span class="c1"># Set the serial baud-rate and other</span> 877 <span class="c1"># configuration parameters.</span> 878 <span class="n">speed</span> <span class="o">=</span> <span class="mi">115200</span> 879 <span class="n">databits</span> <span class="o">=</span> <span class="mi">8</span> 880 <span class="n">parity</span> <span class="o">=</span> <span class="n">none</span> 881 <span class="n">stopbits</span> <span class="o">=</span> <span class="mi">1</span> 882 </pre></div> 883 </div> 884 </section> 885 <section id="pipe-interface"> 886 <span id="interfaces-pipe"></span><h2>Pipe Interface<a class="headerlink" href="#pipe-interface" title="Permalink to this heading">#</a></h2> 887 <p>Using this interface, Reticulum can use any program as an interface via <cite>stdin</cite> and 888 <cite>stdout</cite>. This can be used to easily create virtual interfaces, or to interface with 889 custom hardware or other systems.</p> 890 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">Pipe</span> <span class="n">Interface</span><span class="p">]]</span> 891 <span class="nb">type</span> <span class="o">=</span> <span class="n">PipeInterface</span> 892 <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span> 893 894 <span class="c1"># External command to execute</span> 895 <span class="n">command</span> <span class="o">=</span> <span class="n">netcat</span> <span class="o">-</span><span class="n">l</span> <span class="mi">5757</span> 896 897 <span class="c1"># Optional respawn delay, in seconds</span> 898 <span class="n">respawn_delay</span> <span class="o">=</span> <span class="mi">5</span> 899 </pre></div> 900 </div> 901 <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 902 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, 903 Reticulum will try to respawn the program after waiting for <code class="docutils literal notranslate"><span class="pre">respawn_interval</span></code> seconds.</p> 904 </section> 905 <section id="kiss-interface"> 906 <span id="interfaces-kiss"></span><h2>KISS Interface<a class="headerlink" href="#kiss-interface" title="Permalink to this heading">#</a></h2> 907 <p>With the KISS interface, you can use Reticulum over a variety of packet 908 radio modems and TNCs, including <a class="reference external" href="https://unsigned.io/openmodem/">OpenModem</a>. 909 KISS interfaces can also be configured to periodically send out beacons 910 for station identification purposes.</p> 911 <div class="admonition warning"> 912 <p class="admonition-title">Warning</p> 913 <p>Radio frequency spectrum is a legally controlled resource, and legislation 914 varies widely around the world. It is your responsibility to be aware of any 915 relevant regulation for your location, and to make decisions accordingly.</p> 916 </div> 917 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">Packet</span> <span class="n">Radio</span> <span class="n">KISS</span> <span class="n">Interface</span><span class="p">]]</span> 918 <span class="nb">type</span> <span class="o">=</span> <span class="n">KISSInterface</span> 919 <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span> 920 921 <span class="c1"># Serial port for the device</span> 922 <span class="n">port</span> <span class="o">=</span> <span class="o">/</span><span class="n">dev</span><span class="o">/</span><span class="n">ttyUSB1</span> 923 924 <span class="c1"># Set the serial baud-rate and other</span> 925 <span class="c1"># configuration parameters.</span> 926 <span class="n">speed</span> <span class="o">=</span> <span class="mi">115200</span> 927 <span class="n">databits</span> <span class="o">=</span> <span class="mi">8</span> 928 <span class="n">parity</span> <span class="o">=</span> <span class="n">none</span> 929 <span class="n">stopbits</span> <span class="o">=</span> <span class="mi">1</span> 930 931 <span class="c1"># Set the modem preamble.</span> 932 <span class="n">preamble</span> <span class="o">=</span> <span class="mi">150</span> 933 934 <span class="c1"># Set the modem TX tail.</span> 935 <span class="n">txtail</span> <span class="o">=</span> <span class="mi">10</span> 936 937 <span class="c1"># Configure CDMA parameters. These</span> 938 <span class="c1"># settings are reasonable defaults.</span> 939 <span class="n">persistence</span> <span class="o">=</span> <span class="mi">200</span> 940 <span class="n">slottime</span> <span class="o">=</span> <span class="mi">20</span> 941 942 <span class="c1"># You can configure the interface to send</span> 943 <span class="c1"># out identification on the channel with</span> 944 <span class="c1"># a set interval by configuring the</span> 945 <span class="c1"># following two parameters. The KISS</span> 946 <span class="c1"># interface will only ID if the set</span> 947 <span class="c1"># interval has elapsed since it's last</span> 948 <span class="c1"># actual transmission. The interval is</span> 949 <span class="c1"># configured in seconds.</span> 950 <span class="c1"># This option is commented out and not</span> 951 <span class="c1"># used by default.</span> 952 <span class="c1"># id_callsign = MYCALL-0</span> 953 <span class="c1"># id_interval = 600</span> 954 955 <span class="c1"># Whether to use KISS flow-control.</span> 956 <span class="c1"># This is useful for modems that have</span> 957 <span class="c1"># a small internal packet buffer, but</span> 958 <span class="c1"># support packet flow control instead.</span> 959 <span class="n">flow_control</span> <span class="o">=</span> <span class="n">false</span> 960 </pre></div> 961 </div> 962 </section> 963 <section id="ax-25-kiss-interface"> 964 <span id="interfaces-ax25"></span><h2>AX.25 KISS Interface<a class="headerlink" href="#ax-25-kiss-interface" title="Permalink to this heading">#</a></h2> 965 <p>If you’re using Reticulum on amateur radio spectrum, you might want to 966 use the AX.25 KISS interface. This way, Reticulum will automatically 967 encapsulate it’s traffic in AX.25 and also identify your stations 968 transmissions with your callsign and SSID.</p> 969 <p>Only do this if you really need to! Reticulum doesn’t need the AX.25 970 layer for anything, and it incurs extra overhead on every packet to 971 encapsulate in AX.25.</p> 972 <p>A more efficient way is to use the plain KISS interface with the 973 beaconing functionality described above.</p> 974 <div class="admonition warning"> 975 <p class="admonition-title">Warning</p> 976 <p>Radio frequency spectrum is a legally controlled resource, and legislation 977 varies widely around the world. It is your responsibility to be aware of any 978 relevant regulation for your location, and to make decisions accordingly.</p> 979 </div> 980 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">Packet</span> <span class="n">Radio</span> <span class="n">AX</span><span class="mf">.25</span> <span class="n">KISS</span> <span class="n">Interface</span><span class="p">]]</span> 981 <span class="nb">type</span> <span class="o">=</span> <span class="n">AX25KISSInterface</span> 982 983 <span class="c1"># Set the station callsign and SSID</span> 984 <span class="n">callsign</span> <span class="o">=</span> <span class="n">NO1CLL</span> 985 <span class="n">ssid</span> <span class="o">=</span> <span class="mi">0</span> 986 987 <span class="c1"># Enable interface if you want use it!</span> 988 <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span> 989 990 <span class="c1"># Serial port for the device</span> 991 <span class="n">port</span> <span class="o">=</span> <span class="o">/</span><span class="n">dev</span><span class="o">/</span><span class="n">ttyUSB2</span> 992 993 <span class="c1"># Set the serial baud-rate and other</span> 994 <span class="c1"># configuration parameters.</span> 995 <span class="n">speed</span> <span class="o">=</span> <span class="mi">115200</span> 996 <span class="n">databits</span> <span class="o">=</span> <span class="mi">8</span> 997 <span class="n">parity</span> <span class="o">=</span> <span class="n">none</span> 998 <span class="n">stopbits</span> <span class="o">=</span> <span class="mi">1</span> 999 1000 <span class="c1"># Set the modem preamble. A 150ms</span> 1001 <span class="c1"># preamble should be a reasonable</span> 1002 <span class="c1"># default, but may need to be</span> 1003 <span class="c1"># increased for radios with slow-</span> 1004 <span class="c1"># opening squelch and long TX/RX</span> 1005 <span class="c1"># turnaround</span> 1006 <span class="n">preamble</span> <span class="o">=</span> <span class="mi">150</span> 1007 1008 <span class="c1"># Set the modem TX tail. In most</span> 1009 <span class="c1"># cases this should be kept as low</span> 1010 <span class="c1"># as possible to not waste airtime.</span> 1011 <span class="n">txtail</span> <span class="o">=</span> <span class="mi">10</span> 1012 1013 <span class="c1"># Configure CDMA parameters. These</span> 1014 <span class="c1"># settings are reasonable defaults.</span> 1015 <span class="n">persistence</span> <span class="o">=</span> <span class="mi">200</span> 1016 <span class="n">slottime</span> <span class="o">=</span> <span class="mi">20</span> 1017 1018 <span class="c1"># Whether to use KISS flow-control.</span> 1019 <span class="c1"># This is useful for modems with a</span> 1020 <span class="c1"># small internal packet buffer.</span> 1021 <span class="n">flow_control</span> <span class="o">=</span> <span class="n">false</span> 1022 </pre></div> 1023 </div> 1024 </section> 1025 <section id="common-interface-options"> 1026 <span id="interfaces-options"></span><h2>Common Interface Options<a class="headerlink" href="#common-interface-options" title="Permalink to this heading">#</a></h2> 1027 <p>A number of general configuration options are available on most interfaces. 1028 These can be used to control various aspects of interface behaviour.</p> 1029 <blockquote> 1030 <div><ul> 1031 <li><div class="line-block"> 1032 <div class="line">The <code class="docutils literal notranslate"><span class="pre">enabled</span></code> option tells Reticulum whether or not 1033 to bring up the interface. Defaults to <code class="docutils literal notranslate"><span class="pre">False</span></code>. For any 1034 interface to be brought up, the <code class="docutils literal notranslate"><span class="pre">enabled</span></code> option 1035 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> 1036 </div> 1037 </li> 1038 <li><div class="line-block"> 1039 <div class="line">The <code class="docutils literal notranslate"><span class="pre">mode</span></code> option allows selecting the high-level behaviour 1040 of the interface from a number of options.</div> 1041 </div> 1042 <blockquote> 1043 <div><ul class="simple"> 1044 <li><p>The default value is <code class="docutils literal notranslate"><span class="pre">full</span></code>. In this mode, all discovery, 1045 meshing and transport functionality is available.</p></li> 1046 <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 1047 interface will operate as a network access point. In this 1048 mode, announces will not be automatically broadcasted on 1049 the interface, and paths to destinations on the interface 1050 will have a much shorter expiry time. This mode is useful 1051 for creating interfaces that are mostly quiet, unless when 1052 someone is actually using them. An example of this could 1053 be a radio interface serving a wide area, where users are 1054 expected to connect momentarily, use the network, and then 1055 disappear again.</p></li> 1056 </ul> 1057 </div></blockquote> 1058 </li> 1059 <li><div class="line-block"> 1060 <div class="line">The <code class="docutils literal notranslate"><span class="pre">outgoing</span></code> option sets whether an interface is allowed 1061 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> 1062 the interface will only receive data, and never transmit.</div> 1063 </div> 1064 </li> 1065 <li><div class="line-block"> 1066 <div class="line">The <code class="docutils literal notranslate"><span class="pre">network_name</span></code> option sets the virtual network name for 1067 the interface. This allows multiple separate network segments 1068 to exist on the same physical channel or medium.</div> 1069 </div> 1070 </li> 1071 <li><div class="line-block"> 1072 <div class="line">The <code class="docutils literal notranslate"><span class="pre">passphrase</span></code> option sets an authentication passphrase on 1073 the interface. This option can be used in conjunction with the 1074 <code class="docutils literal notranslate"><span class="pre">network_name</span></code> option, or be used alone.</div> 1075 </div> 1076 </li> 1077 <li><div class="line-block"> 1078 <div class="line">The <code class="docutils literal notranslate"><span class="pre">ifac_size</span></code> option allows customising the length of the 1079 Interface Authentication Codes carried by each packet on named 1080 and/or authenticated network segments. It is set by default to 1081 a size suitable for the interface in question, but can be set 1082 to a custom size between 8 and 512 bits by using this option. 1083 In normal usage, this option should not be changed from the 1084 default.</div> 1085 </div> 1086 </li> 1087 <li><div class="line-block"> 1088 <div class="line">The <code class="docutils literal notranslate"><span class="pre">announce_cap</span></code> option lets you configure the maximum 1089 bandwidth to allocate, at any given time, to propagating 1090 announces and other network upkeep traffic. It is configured at 1091 2% by default, and should normally not need to be changed. Can 1092 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> 1093 </div> 1094 <blockquote> 1095 <div><p><em>If an interface exceeds its announce cap, it will queue announces 1096 for later transmission. Reticulum will always prioritise propagating 1097 announces from nearby nodes first. This ensures that the local 1098 topology is prioritised, and that slow networks are not overwhelmed 1099 by interconnected fast networks.</em></p> 1100 <p><em>Destinations that are rapidly re-announcing will be down-prioritised 1101 further. Trying to get “first-in-line” by announce spamming will have 1102 the exact opposite effect: Getting moved to the back of the queue every 1103 time a new announce from the excessively announcing destination is received.</em></p> 1104 <p><em>This means that it is always beneficial to select a balanced 1105 announce rate, and not announce more often than is actually necesarry 1106 for your application to function.</em></p> 1107 </div></blockquote> 1108 </li> 1109 <li><div class="line-block"> 1110 <div class="line">The <code class="docutils literal notranslate"><span class="pre">bitrate</span></code> option configures the interface bitrate. 1111 Reticulum will use interface speeds reported by hardware, or 1112 try to guess a suitable rate when the hardware doesn’t report 1113 any. In most cases, the automatically found rate should be 1114 sufficient, but it can be configured by using the <code class="docutils literal notranslate"><span class="pre">bitrate</span></code> 1115 option, to set the interface speed in <em>bits per second</em>.</div> 1116 </div> 1117 </li> 1118 </ul> 1119 </div></blockquote> 1120 </section> 1121 <section id="interface-modes"> 1122 <span id="interfaces-modes"></span><h2>Interface Modes<a class="headerlink" href="#interface-modes" title="Permalink to this heading">#</a></h2> 1123 <p>The optional <code class="docutils literal notranslate"><span class="pre">mode</span></code> setting is available on all interfaces, and allows 1124 selecting the high-level behaviour of the interface from a number of modes. 1125 These modes affect how Reticulum selects paths in the network, how announces 1126 are propagated, how long paths are valid and how paths are discovered.</p> 1127 <p>Configuring modes on interfaces is <strong>not</strong> strictly necessary, but can be useful 1128 when building or connecting to more complex networks. If your Reticulum 1129 instance is not running a Transport Node, it is rarely useful to configure 1130 interface modes, and in such cases interfaces should generally be left in 1131 the default mode.</p> 1132 <blockquote> 1133 <div><ul> 1134 <li><div class="line-block"> 1135 <div class="line">The default mode is <code class="docutils literal notranslate"><span class="pre">full</span></code>. In this mode, all discovery, 1136 meshing and transport functionality is activated.</div> 1137 </div> 1138 </li> 1139 <li><div class="line-block"> 1140 <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 1141 discovery, meshing and transport functionality available, 1142 but will additionally try to discover unknown paths on 1143 behalf of other nodes residing on the <code class="docutils literal notranslate"><span class="pre">gateway</span></code> interface. 1144 If Reticulum receives a path request for an unknown 1145 destination, from a node on a <code class="docutils literal notranslate"><span class="pre">gateway</span></code> interface, it 1146 will try to discover this path via all other active interfaces, 1147 and forward the discovered path to the requestor if one is 1148 found.</div> 1149 </div> 1150 <div class="line-block"> 1151 <div class="line">If you want to allow other nodes to widely resolve paths or connect 1152 to a network via an interface, it might be useful to put it in this 1153 mode. By creating a chain of <code class="docutils literal notranslate"><span class="pre">gateway</span></code> interfaces, other 1154 nodes will be able to immediately discover paths to any 1155 destination along the chain.</div> 1156 </div> 1157 <div class="line-block"> 1158 <div class="line"><em>Please note!</em> It is the interface <em>facing the clients</em> that 1159 must be put into <code class="docutils literal notranslate"><span class="pre">gateway</span></code> mode for this to work, not 1160 the interface facing the wider network (for this, the <code class="docutils literal notranslate"><span class="pre">boundary</span></code> 1161 mode can be useful, though).</div> 1162 </div> 1163 </li> 1164 <li><div class="line-block"> 1165 <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 1166 interface will operate as a network access point. In this 1167 mode, announces will not be automatically broadcasted on 1168 the interface, and paths to destinations on the interface 1169 will have a much shorter expiry time. In addition, path 1170 requests from clients on the access point interface will 1171 be handled in the same way as the <code class="docutils literal notranslate"><span class="pre">gateway</span></code> interface.</div> 1172 </div> 1173 <div class="line-block"> 1174 <div class="line">This mode is useful for creating interfaces that remain 1175 quiet, until someone actually starts using them. An example 1176 of this could be a radio interface serving a wide area, 1177 where users are expected to connect momentarily, use the 1178 network, and then disappear again.</div> 1179 </div> 1180 </li> 1181 <li><div class="line-block"> 1182 <div class="line">The <code class="docutils literal notranslate"><span class="pre">roaming</span></code> mode should be used on interfaces that are 1183 roaming (physically mobile), seen from the perspective of 1184 other nodes in the network. As an example, if a vehicle is 1185 equipped with an external LoRa interface, and an internal, 1186 WiFi-based interface, that serves devices that are moving 1187 <em>with</em> the vehicle, the external LoRa interface should be 1188 configured as <code class="docutils literal notranslate"><span class="pre">roaming</span></code>, and the internal interface can 1189 be left in the default mode. With transport enabled, such 1190 a setup will allow all internal devices to reach each other, 1191 and all other devices that are available on the LoRa side 1192 of the network, when they are in range. Devices on the LoRa 1193 side of the network will also be able to reach devices 1194 internal to the vehicle, when it is in range. Paths via 1195 <code class="docutils literal notranslate"><span class="pre">roaming</span></code> interfaces also expire faster.</div> 1196 </div> 1197 </li> 1198 <li><div class="line-block"> 1199 <div class="line">The purpose of the <code class="docutils literal notranslate"><span class="pre">boundary</span></code> mode is to specify interfaces 1200 that establish connectivity with network segments that are 1201 significantly different than the one this node exists on. 1202 As an example, if a Reticulum instance is part of a LoRa-based 1203 network, but also has a high-speed connection to a 1204 public Transport Node available on the Internet, the interface 1205 connecting over the Internet should be set to <code class="docutils literal notranslate"><span class="pre">boundary</span></code> mode.</div> 1206 </div> 1207 </li> 1208 </ul> 1209 </div></blockquote> 1210 <p>For a table describing the impact of all modes on announce propagation, 1211 please see the <a class="reference internal" href="understanding.html#understanding-announcepropagation"><span class="std std-ref">Announce Propagation Rules</span></a> section.</p> 1212 </section> 1213 <section id="announce-rate-control"> 1214 <span id="interfaces-announcerates"></span><h2>Announce Rate Control<a class="headerlink" href="#announce-rate-control" title="Permalink to this heading">#</a></h2> 1215 <p>The built-in announce control mechanisms and the default <code class="docutils literal notranslate"><span class="pre">announce_cap</span></code> 1216 option described above are sufficient most of the time, but in some cases, especially on fast 1217 interfaces, it may be useful to control the target announce rate. Using the 1218 <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> 1219 options, this can be done on a per-interface basis, and moderates the <em>rate at 1220 which received announces are re-broadcasted to other interfaces</em>.</p> 1221 <blockquote> 1222 <div><ul> 1223 <li><div class="line-block"> 1224 <div class="line">The <code class="docutils literal notranslate"><span class="pre">announce_rate_target</span></code> option sets the minimum amount of time, 1225 in seconds, that should pass between received announces, for any one 1226 destination. As an example, setting this value to <code class="docutils literal notranslate"><span class="pre">3600</span></code> means that 1227 announces <em>received</em> on this interface will only be re-transmitted and 1228 propagated to other interfaces once every hour, no matter how often they 1229 are received.</div> 1230 </div> 1231 </li> 1232 <li><div class="line-block"> 1233 <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 1234 can violate the announce rate before the target rate is enforced.</div> 1235 </div> 1236 </li> 1237 <li><div class="line-block"> 1238 <div class="line">The optional <code class="docutils literal notranslate"><span class="pre">announce_rate_penalty</span></code> configures an extra amount of 1239 time that is added to the normal rate target. As an example, if a penalty 1240 of <code class="docutils literal notranslate"><span class="pre">7200</span></code> seconds is defined, once the rate target is enforced, the 1241 destination in question will only have its announces propagated every 1242 3 hours, until it lowers its actual announce rate to within the target.</div> 1243 </div> 1244 </li> 1245 </ul> 1246 </div></blockquote> 1247 <p>These mechanisms, in conjunction with the <code class="docutils literal notranslate"><span class="pre">annouce_cap</span></code> mechanisms mentioned 1248 above means that it is essential to select a balanced announce strategy for 1249 your destinations. The more balanced you can make this decision, the easier 1250 it will be for your destinations to make it into slower networks that many hops 1251 away. Or you can prioritise only reaching high-capacity networks with more frequent 1252 announces.</p> 1253 <p>Current statistics and information about announce rates can be viewed using the 1254 <code class="docutils literal notranslate"><span class="pre">rnpath</span> <span class="pre">-r</span></code> command.</p> 1255 <p>It is important to note that there is no one right or wrong way to set up announce 1256 rates. Slower networks will naturally tend towards using less frequent announces to 1257 conserve bandwidth, while very fast networks can support applications that 1258 need very frequent announces. Reticulum implements these mechanisms to ensure 1259 that a large span of network types can seamlessly <em>co-exist</em> and interconnect.</p> 1260 </section> 1261 <section id="new-destination-rate-limiting"> 1262 <span id="interfaces-ingress-control"></span><h2>New Destination Rate Limiting<a class="headerlink" href="#new-destination-rate-limiting" title="Permalink to this heading">#</a></h2> 1263 <p>On public interfaces, where anyone may connect and announce new destinations, 1264 it can be useful to control the rate at which announces for <em>new</em> destinations are 1265 processed.</p> 1266 <p>If a large influx of announces for newly created or previously unknown destinations 1267 occur within a short amount of time, Reticulum will place these announces on hold, 1268 so that announce traffic for known and previously established destinations can 1269 continue to be processed without interruptions.</p> 1270 <p>After the burst subsides, and an additional waiting period has passed, the held 1271 announces will be released at a slow rate, until the hold queue is cleared. This 1272 also means, that should a node decide to connect to a public interface, announce 1273 a large amount of bogus destinations, and then disconnect, these destination will 1274 never make it into path tables and waste network bandwidth on retransmitted 1275 announces.</p> 1276 <p><strong>It’s important to note</strong> that the ingress control works at the level of <em>individual 1277 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> 1278 cannot disrupt processing of incoming announces for other connected clients on the same 1279 <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 1280 processed without interruption.</p> 1281 <p>By default, Reticulum will handle this automatically, and ingress announce 1282 control will be enabled on interface where it is sensible to do so. It should 1283 generally not be neccessary to modify the ingress control configuration, 1284 but all the parameters are exposed for configuration if needed.</p> 1285 <blockquote> 1286 <div><ul> 1287 <li><div class="line-block"> 1288 <div class="line">The <code class="docutils literal notranslate"><span class="pre">ingress_control</span></code> option tells Reticulum whether or not 1289 to enable announce ingress control on the interface. Defaults to 1290 <code class="docutils literal notranslate"><span class="pre">True</span></code>.</div> 1291 </div> 1292 </li> 1293 <li><div class="line-block"> 1294 <div class="line">The <code class="docutils literal notranslate"><span class="pre">ic_new_time</span></code> option configures how long (in seconds) an 1295 interface is considered newly spawned. Defaults to <code class="docutils literal notranslate"><span class="pre">2*60*60</span></code> seconds. This 1296 option is useful on publicly accessible interfaces that spawn new 1297 sub-interfaces when a new client connects.</div> 1298 </div> 1299 </li> 1300 <li><div class="line-block"> 1301 <div class="line">The <code class="docutils literal notranslate"><span class="pre">ic_burst_freq_new</span></code> option sets the maximum announce ingress 1302 frequency for newly spawned interfaces. Defaults to <code class="docutils literal notranslate"><span class="pre">3.5</span></code> 1303 announces per second.</div> 1304 </div> 1305 </li> 1306 <li><div class="line-block"> 1307 <div class="line">The <code class="docutils literal notranslate"><span class="pre">ic_burst_freq</span></code> option sets the maximum announce ingress 1308 frequency for other interfaces. Defaults to <code class="docutils literal notranslate"><span class="pre">12</span></code> announces 1309 per second.</div> 1310 </div> 1311 <blockquote> 1312 <div><p><em>If an interface exceeds its burst frequency, incoming announces 1313 for unknown destinations will be temporarily held in a queue, and 1314 not processed until later.</em></p> 1315 </div></blockquote> 1316 </li> 1317 <li><div class="line-block"> 1318 <div class="line">The <code class="docutils literal notranslate"><span class="pre">ic_max_held_announces</span></code> option sets the maximum amount of 1319 unique announces that will be held in the queue. Any additional 1320 unique announces will be dropped. Defaults to <code class="docutils literal notranslate"><span class="pre">256</span></code> announces.</div> 1321 </div> 1322 </li> 1323 <li><div class="line-block"> 1324 <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 1325 pass after the burst frequency drops below its threshold, for the 1326 announce burst to be considered cleared. Defaults to <code class="docutils literal notranslate"><span class="pre">60</span></code> 1327 seconds.</div> 1328 </div> 1329 </li> 1330 <li><div class="line-block"> 1331 <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 1332 pass after the burst is considered cleared, before held announces can 1333 start being released from the queue. Defaults to <code class="docutils literal notranslate"><span class="pre">5*60</span></code> 1334 seconds.</div> 1335 </div> 1336 </li> 1337 <li><div class="line-block"> 1338 <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) 1339 must pass between releasing each held announce from the queue. Defaults 1340 to <code class="docutils literal notranslate"><span class="pre">30</span></code> seconds.</div> 1341 </div> 1342 </li> 1343 </ul> 1344 </div></blockquote> 1345 </section> 1346 </section> 1347 1348 </article> 1349 </div> 1350 <footer> 1351 1352 <div class="related-pages"> 1353 <a class="next-page" href="networks.html"> 1354 <div class="page-info"> 1355 <div class="context"> 1356 <span>Next</span> 1357 </div> 1358 <div class="title">Building Networks</div> 1359 </div> 1360 <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg> 1361 </a> 1362 <a class="prev-page" href="hardware.html"> 1363 <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg> 1364 <div class="page-info"> 1365 <div class="context"> 1366 <span>Previous</span> 1367 </div> 1368 1369 <div class="title">Communications Hardware</div> 1370 1371 </div> 1372 </a> 1373 </div> 1374 <div class="bottom-of-page"> 1375 <div class="left-details"> 1376 <div class="copyright"> 1377 Copyright © 2023, Mark Qvist 1378 </div> 1379 Generated with <a href="https://www.sphinx-doc.org/">Sphinx</a> and 1380 <a href="https://github.com/pradyunsg/furo">Furo</a> 1381 1382 </div> 1383 <div class="right-details"> 1384 <div class="icons"> 1385 1386 </div> 1387 </div> 1388 </div> 1389 1390 </footer> 1391 </div> 1392 <aside class="toc-drawer"> 1393 1394 1395 <div class="toc-sticky toc-scroll"> 1396 <div class="toc-title-container"> 1397 <span class="toc-title"> 1398 On this page 1399 </span> 1400 </div> 1401 <div class="toc-tree-container"> 1402 <div class="toc-tree"> 1403 <ul> 1404 <li><a class="reference internal" href="#">Configuring Interfaces</a><ul> 1405 <li><a class="reference internal" href="#custom-interfaces">Custom Interfaces</a></li> 1406 <li><a class="reference internal" href="#auto-interface">Auto Interface</a></li> 1407 <li><a class="reference internal" href="#backbone-interface">Backbone Interface</a><ul> 1408 <li><a class="reference internal" href="#listeners">Listeners</a></li> 1409 <li><a class="reference internal" href="#connecting-remotes">Connecting Remotes</a></li> 1410 </ul> 1411 </li> 1412 <li><a class="reference internal" href="#tcp-server-interface">TCP Server Interface</a></li> 1413 <li><a class="reference internal" href="#tcp-client-interface">TCP Client Interface</a></li> 1414 <li><a class="reference internal" href="#udp-interface">UDP Interface</a></li> 1415 <li><a class="reference internal" href="#i2p-interface">I2P Interface</a></li> 1416 <li><a class="reference internal" href="#rnode-lora-interface">RNode LoRa Interface</a></li> 1417 <li><a class="reference internal" href="#rnode-multi-interface">RNode Multi Interface</a></li> 1418 <li><a class="reference internal" href="#serial-interface">Serial Interface</a></li> 1419 <li><a class="reference internal" href="#pipe-interface">Pipe Interface</a></li> 1420 <li><a class="reference internal" href="#kiss-interface">KISS Interface</a></li> 1421 <li><a class="reference internal" href="#ax-25-kiss-interface">AX.25 KISS Interface</a></li> 1422 <li><a class="reference internal" href="#common-interface-options">Common Interface Options</a></li> 1423 <li><a class="reference internal" href="#interface-modes">Interface Modes</a></li> 1424 <li><a class="reference internal" href="#announce-rate-control">Announce Rate Control</a></li> 1425 <li><a class="reference internal" href="#new-destination-rate-limiting">New Destination Rate Limiting</a></li> 1426 </ul> 1427 </li> 1428 </ul> 1429 1430 </div> 1431 </div> 1432 </div> 1433 1434 1435 </aside> 1436 </div> 1437 </div><script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> 1438 <script src="_static/jquery.js"></script> 1439 <script src="_static/underscore.js"></script> 1440 <script src="_static/_sphinx_javascript_frameworks_compat.js"></script> 1441 <script src="_static/doctools.js"></script> 1442 <script src="_static/sphinx_highlight.js"></script> 1443 <script src="_static/scripts/furo.js"></script> 1444 <script src="_static/clipboard.min.js"></script> 1445 <script src="_static/copybutton.js"></script> 1446 </body> 1447 </html>