interfaces.rst
1 2 .. _interfaces-main: 3 4 ********************** 5 Configuring Interfaces 6 ********************** 7 8 Reticulum supports using many kinds of devices as networking interfaces, and 9 allows you to mix and match them in any way you choose. The number of distinct 10 network topologies you can create with Reticulum is more or less endless, but 11 common to them all is that you will need to define one or more *interfaces* 12 for Reticulum to use. 13 14 The following sections describe the interfaces currently available in Reticulum, 15 and gives example configurations for the respective interface types. 16 17 For a high-level overview of how networks can be formed over different interface 18 types, have a look at the :ref:`Building Networks<networks-main>` chapter of this 19 manual. 20 21 22 .. _interfaces-custom: 23 24 Custom Interfaces 25 ================= 26 27 In addition to the built-in interface types, Reticulum is **fully extensible** with 28 custom, user- or community-supplied interfaces, and creating custom interface 29 modules is straightforward. Please see the :ref:`custom interface<example-custominterface>` 30 example for basic interface code to build upon. 31 32 .. _interfaces-auto: 33 34 Auto Interface 35 ============== 36 37 The ``AutoInterface`` enables communication with other discoverable Reticulum 38 nodes over any kind of local Ethernet or WiFi-based medium. Even though it uses IPv6 for peer 39 discovery, and UDP for packet transport, it **does not** need any functional IP 40 infrastructure like routers or DHCP servers, on your physical network. 41 42 As long as there is at least some sort of switching medium present between peers (a 43 wired switch, a hub, a WiFi access point or similar, or simply two devices connected 44 directly by Ethernet cable), it will work without any configuration, setup or intermediary devices. 45 46 For ``AutoInterface`` peer discovery to work, it's also required that link-local 47 IPv6 support is available on your system, which it should be by default in all 48 current operating systems, both desktop and mobile. 49 50 .. note:: 51 Almost all current Ethernet and WiFi hardware will work without any kind 52 of configuration or setup with ``AutoInterface``, but a small subset of 53 devices turn on options that limit device-to-device communication by default, 54 resulting in ``AutoInterface`` peer discovery being blocked. This issue is 55 most commonly seen on very cheap, ISP-supplied WiFi routers, and can sometimes 56 be turned off in the router configuration. 57 58 .. code:: 59 60 # This example demonstrates a bare-minimum setup 61 # of an Auto Interface. It will allow communica- 62 # tion with all other reachable devices on all 63 # usable physical ethernet-based devices that 64 # are available on the system. 65 [[Default Interface]] 66 type = AutoInterface 67 enabled = yes 68 69 # This example demonstrates an more specifically 70 # configured Auto Interface, that only uses spe- 71 # cific physical interfaces, and has a number of 72 # other configuration options set. 73 [[Default Interface]] 74 type = AutoInterface 75 enabled = yes 76 77 # You can create multiple isolated Reticulum 78 # networks on the same physical LAN by 79 # specifying different Group IDs. 80 group_id = reticulum 81 82 # You can also choose the multicast address type: 83 # temporary (default, Temporary Multicast Address) 84 # or permanent (Permanent Multicast Address) 85 multicast_address_type = permanent 86 87 # You can also select specifically which 88 # kernel networking devices to use. 89 devices = wlan0,eth1 90 91 # Or let AutoInterface use all suitable 92 # devices except for a list of ignored ones. 93 ignored_devices = tun0,eth0 94 95 96 If you are connected to the Internet with IPv6, and your provider will route 97 IPv6 multicast, you can potentially configure the Auto Interface to globally 98 autodiscover other Reticulum nodes within your selected Group ID. You can specify 99 the discovery scope by setting it to one of ``link``, ``admin``, ``site``, 100 ``organisation`` or ``global``. 101 102 .. code:: 103 104 [[Default Interface]] 105 type = AutoInterface 106 enabled = yes 107 108 # Configure global discovery 109 110 group_id = custom_network_name 111 discovery_scope = global 112 113 # Other configuration options 114 115 discovery_port = 48555 116 data_port = 49555 117 118 119 .. _interfaces-backbone: 120 121 Backbone Interface 122 ==================== 123 124 The Backbone interface is a very fast and resource efficient interface type, primarily 125 intended for interconnecting Reticulum instances over many different types of mediums. 126 It uses a kernel-event I/O backend, and can handle thousands of interfaces and/or clients 127 with relatively low system resource utilisation. **This interface type is currently only 128 supported on Linux and Android**. 129 130 .. note:: 131 The Backbone Interface is fully compatible with the ``TCPServerInterface`` and ``TCPClientInterface`` 132 types, and they can be used interchangably, and cross-connect with each other. On systems that support 133 ``BackboneInterface``, it is generally recommended to use it, unless you need specific options or 134 features that the TCP server and client interfaces provide. 135 136 While the goal is to support *all* socket types and I/O devices provided by the underlying 137 operating system, the initial release only provides support for TCP connections over IPv4 138 and IPv6. 139 140 For all types of connections over a ``BackboneInterface``, Reticulum will gracefully 141 handle intermittency, link loss, and connections that come and go. 142 143 Listeners 144 --------- 145 146 The following examples illustrates various ways to set up ``BackboneInterface`` listeners. 147 148 .. code:: 149 150 # This example demonstrates a backbone interface 151 # that listens for incoming connections on the 152 # specified IP address and port number. 153 [[Backbone Listener]] 154 type = BackboneInterface 155 enabled = yes 156 listen_on = 0.0.0.0 157 port = 4242 158 159 # Alternatively you can bind to a specific IP 160 [[Backbone Listener]] 161 type = BackboneInterface 162 enabled = yes 163 listen_on = 10.0.0.88 164 port = 4242 165 166 # Or a specific network device 167 [[Backbone Listener]] 168 type = BackboneInterface 169 enabled = yes 170 device = eth0 171 port = 4242 172 173 If you are using the interface on a device which has both IPv4 and IPv6 addresses available, 174 you can use the ``prefer_ipv6`` option to bind to the IPv6 address: 175 176 .. code:: 177 178 # This example demonstrates a backbone interface 179 # listening on the IPv6 address of a specified 180 # kernel networking device. 181 [[Backbone Listener]] 182 type = BackboneInterface 183 enabled = yes 184 prefer_ipv6 = yes 185 device = eth0 186 port = 4242 187 188 To use the ``BackboneInterface`` over `Yggdrasil <https://yggdrasil-network.github.io/>`_, you 189 can simply specify the Yggdrasil ``tun`` device and a listening port, like so: 190 191 .. code:: 192 193 # This example demonstrates a backbone interface 194 # listening for connections over Yggdrasil. 195 [[Yggdrasil Backbone Interface]] 196 type = BackboneInterface 197 enabled = yes 198 device = tun0 199 port = 4343 200 201 Connecting Remotes 202 ------------------ 203 The following examples illustrates various ways to connect to remote ``BackboneInterface`` listeners. 204 As noted above, ``BackboneInterface`` interfaces can also connect to remote ``TCPServerInterface``, 205 and as such these interface types can be used interchangably. 206 207 .. code:: 208 209 # Here's an example of a backbone interface that 210 # connects to a remote listener. 211 [[Backbone Remote]] 212 type = BackboneInterface 213 enabled = yes 214 remote = amsterdam.connect.reticulum.network 215 target_port = 4251 216 217 To connect to remotes over `Yggdrasil <https://yggdrasil-network.github.io/>`_, simply 218 specify the target Yggdrasil IPv6 address and port, like so: 219 220 .. code:: 221 222 [[Yggdrasil Remote]] 223 type = BackboneInterface 224 enabled = yes 225 target_host = 201:5d78:af73:5caf:a4de:a79f:3278:71e5 226 target_port = 4343 227 228 .. _interfaces-tcps: 229 230 TCP Server Interface 231 ==================== 232 233 The TCP Server interface is suitable for allowing other peers to connect over 234 the Internet or private IPv4 and IPv6 networks. When a TCP server interface has been 235 configured, other Reticulum peers can connect to it with a TCP Client interface. 236 237 .. code:: 238 239 # This example demonstrates a TCP server interface. 240 # It will listen for incoming connections on all IP 241 # interfaces on port 4242. 242 [[TCP Server Interface]] 243 type = TCPServerInterface 244 enabled = yes 245 listen_ip = 0.0.0.0 246 listen_port = 4242 247 248 # Alternatively you can bind to a specific IP 249 [[TCP Server Interface]] 250 type = TCPServerInterface 251 enabled = yes 252 listen_ip = 10.0.0.88 253 listen_port = 4242 254 255 # Or a specific network device 256 [[TCP Server Interface]] 257 type = TCPServerInterface 258 enabled = yes 259 device = eth0 260 listen_port = 4242 261 262 If you are using the interface on a device which has both IPv4 and IPv6 addresses available, 263 you can use the ``prefer_ipv6`` option to bind to the IPv6 address: 264 265 .. code:: 266 267 # This example demonstrates a TCP server interface. 268 # It will listen for incoming connections on the 269 # specified IP address and port number. 270 271 [[TCP Server Interface]] 272 type = TCPServerInterface 273 enabled = yes 274 prefer_ipv6 = True 275 device = eth0 276 port = 4242 277 278 To use the TCP Server Interface over `Yggdrasil <https://yggdrasil-network.github.io/>`_, you 279 can simply specify the Yggdrasil ``tun`` device and a listening port, like so: 280 281 .. code:: 282 283 [[Yggdrasil TCP Server Interface]] 284 type = TCPServerInterface 285 enabled = yes 286 device = tun0 287 listen_port = 4343 288 289 .. note:: 290 The TCP interfaces support tunneling over I2P, but to do so reliably, 291 you must use the i2p_tunneled option: 292 293 .. code:: 294 295 [[TCP Server on I2P]] 296 type = TCPServerInterface 297 enabled = yes 298 listen_ip = 127.0.0.1 299 listen_port = 5001 300 i2p_tunneled = yes 301 302 In almost all cases, it is easier to use the dedicated ``I2PInterface``, but for complete 303 control, and using I2P routers running on external systems, this option also exists. 304 305 .. _interfaces-tcpc: 306 307 TCP Client Interface 308 ==================== 309 310 To connect to a TCP server interface, you can use the TCP client 311 interface. Many TCP Client interfaces from different peers can connect to the 312 same TCP Server interface at the same time. 313 314 The TCP interface types can also tolerate intermittency in the IP link layer. 315 This means that Reticulum will gracefully handle IP links that go up and down, 316 and restore connectivity after a failure, once the other end of a TCP interface reappears. 317 318 .. code:: 319 320 # Here's an example of a TCP Client interface. The 321 # target_host can be a hostname or an IPv4 or IPv6 address. 322 [[TCP Client Interface]] 323 type = TCPClientInterface 324 enabled = yes 325 target_host = 127.0.0.1 326 target_port = 4242 327 328 To use the TCP Client Interface over `Yggdrasil <https://yggdrasil-network.github.io/>`_, simply 329 specify the target Yggdrasil IPv6 address and port, like so: 330 331 .. code:: 332 333 [[Yggdrasil TCP Client Interface]] 334 type = TCPClientInterface 335 enabled = yes 336 target_host = 201:5d78:af73:5caf:a4de:a79f:3278:71e5 337 target_port = 4343 338 339 It is also possible to use this interface type to connect via other programs 340 or hardware devices that expose a KISS interface on a TCP port, for example 341 software-based soundmodems. To do this, use the ``kiss_framing`` option: 342 343 .. code:: 344 345 # Here's an example of a TCP Client interface that connects 346 # to a software TNC soundmodem on a KISS over TCP port. 347 348 [[TCP KISS Interface]] 349 type = TCPClientInterface 350 enabled = yes 351 kiss_framing = True 352 target_host = 127.0.0.1 353 target_port = 8001 354 355 **Caution!** Only use the KISS framing option when connecting to external devices 356 and programs like soundmodems and similar over TCP. When using the 357 ``TCPClientInterface`` in conjunction with the ``TCPServerInterface`` you should 358 never enable ``kiss_framing``, since this will disable internal reliability and 359 recovery mechanisms that greatly improves performance over unreliable and 360 intermittent TCP links. 361 362 .. note:: 363 The TCP interfaces support tunneling over I2P, but to do so reliably, 364 you must use the i2p_tunneled option: 365 366 .. code:: 367 368 [[TCP Client over I2P]] 369 type = TCPClientInterface 370 enabled = yes 371 target_host = 127.0.0.1 372 target_port = 5001 373 i2p_tunneled = yes 374 375 376 .. _interfaces-udp: 377 378 UDP Interface 379 ============= 380 381 A UDP interface can be useful for communicating over IP networks, both 382 private and the internet. It can also allow broadcast communication 383 over IP networks, so it can provide an easy way to enable connectivity 384 with all other peers on a local area network. 385 386 .. warning:: 387 Using broadcast UDP traffic has performance implications, 388 especially on WiFi. If your goal is simply to enable easy communication 389 with all peers in your local Ethernet broadcast domain, the 390 :ref:`Auto Interface<interfaces-auto>` performs better, and is even 391 easier to use. 392 393 .. code:: 394 395 # This example enables communication with other 396 # local Reticulum peers over UDP. 397 398 [[UDP Interface]] 399 type = UDPInterface 400 enabled = yes 401 402 listen_ip = 0.0.0.0 403 listen_port = 4242 404 forward_ip = 255.255.255.255 405 forward_port = 4242 406 407 # The above configuration will allow communication 408 # within the local broadcast domains of all local 409 # IP interfaces. 410 411 # Instead of specifying listen_ip, listen_port, 412 # forward_ip and forward_port, you can also bind 413 # to a specific network device like below. 414 415 # device = eth0 416 # port = 4242 417 418 # Assuming the eth0 device has the address 419 # 10.55.0.72/24, the above configuration would 420 # be equivalent to the following manual setup. 421 # Note that we are both listening and forwarding to 422 # the broadcast address of the network segments. 423 424 # listen_ip = 10.55.0.255 425 # listen_port = 4242 426 # forward_ip = 10.55.0.255 427 # forward_port = 4242 428 429 # You can of course also communicate only with 430 # a single IP address 431 432 # listen_ip = 10.55.0.15 433 # listen_port = 4242 434 # forward_ip = 10.55.0.16 435 # forward_port = 4242 436 437 438 .. _interfaces-i2p: 439 440 I2P Interface 441 ============= 442 443 The I2P interface lets you connect Reticulum instances over the 444 `Invisible Internet Protocol <https://i2pd.website>`_. This can be 445 especially useful in cases where you want to host a globally reachable 446 Reticulum instance, but do not have access to any public IP addresses, 447 have a frequently changing IP address, or have firewalls blocking 448 inbound traffic. 449 450 Using the I2P interface, you will get a globally reachable, portable 451 and persistent I2P address that your Reticulum instance can be reached 452 at. 453 454 To use the I2P interface, you must have an I2P router running 455 on your system. The easiest way to achieve this is to download and 456 install the `latest release <https://github.com/PurpleI2P/i2pd/releases/latest>`_ 457 of the ``i2pd`` package. For more details about I2P, see the 458 `geti2p.net website <https://geti2p.net/en/about/intro>`_. 459 460 When an I2P router is running on your system, you can simply add 461 an I2P interface to Reticulum: 462 463 .. code:: 464 465 [[I2P]] 466 type = I2PInterface 467 enabled = yes 468 connectable = yes 469 470 On the first start, Reticulum will generate a new I2P address for the 471 interface and start listening for inbound traffic on it. This can take 472 a while the first time, especially if your I2P router was also just 473 started, and is not yet well-connected to the I2P network. When ready, 474 you should see I2P base32 address printed to your log file. You can 475 also inspect the status of the interface using the ``rnstatus`` utility. 476 477 To connect to other Reticulum instances over I2P, just add a comma-separated 478 list of I2P base32 addresses to the ``peers`` option of the interface: 479 480 .. code:: 481 482 [[I2P]] 483 type = I2PInterface 484 enabled = yes 485 connectable = yes 486 peers = 5urvjicpzi7q3ybztsef4i5ow2aq4soktfj7zedz53s47r54jnqq.b32.i2p 487 488 It can take anywhere from a few seconds to a few minutes to establish 489 I2P connections to the desired peers, so Reticulum handles the process 490 in the background, and will output relevant events to the log. 491 492 .. note:: 493 While the I2P interface is the simplest way to use 494 Reticulum over I2P, it is also possible to tunnel the TCP server and 495 client interfaces over I2P manually. This can be useful in situations 496 where more control is needed, but requires manual tunnel setup through 497 the I2P daemon configuration. 498 499 It is important to note that the two methods are *interchangably compatible*. 500 You can use the I2PInterface to connect to a TCPServerInterface that 501 was manually tunneled over I2P, for example. This offers a high degree 502 of flexibility in network setup, while retaining ease of use in simpler 503 use-cases. 504 505 506 .. _interfaces-rnode: 507 508 RNode LoRa Interface 509 ==================== 510 511 To use Reticulum over LoRa, the `RNode <https://unsigned.io/rnode/>`_ interface 512 can be used, and offers full control over LoRa parameters. 513 514 .. warning:: 515 Radio frequency spectrum is a legally controlled resource, and legislation 516 varies widely around the world. It is your responsibility to be aware of any 517 relevant regulation for your location, and to make decisions accordingly. 518 519 .. code:: 520 521 # Here's an example of how to add a LoRa interface 522 # using the RNode LoRa transceiver. 523 524 [[RNode LoRa Interface]] 525 type = RNodeInterface 526 527 # Enable interface if you want use it! 528 enabled = yes 529 530 # Serial port for the device 531 port = /dev/ttyUSB0 532 533 # It is also possible to use BLE devices 534 # instead of wired serial ports. The 535 # target RNode must be paired with the 536 # host device before connecting. BLE 537 # devices can be connected by name, 538 # BLE MAC address or by any available. 539 540 # Connect to specific device by name 541 # port = ble://RNode 3B87 542 543 # Or by BLE MAC address 544 # port = ble://F4:12:73:29:4E:89 545 546 # Or connect to the first available, 547 # paired device 548 # port = ble:// 549 550 # Set frequency to 867.2 MHz 551 frequency = 867200000 552 553 # Set LoRa bandwidth to 125 KHz 554 bandwidth = 125000 555 556 # Set TX power to 7 dBm (5 mW) 557 txpower = 7 558 559 # Select spreading factor 8. Valid 560 # range is 7 through 12, with 7 561 # being the fastest and 12 having 562 # the longest range. 563 spreadingfactor = 8 564 565 # Select coding rate 5. Valid range 566 # is 5 throough 8, with 5 being the 567 # fastest, and 8 the longest range. 568 codingrate = 5 569 570 # You can configure the RNode to send 571 # out identification on the channel with 572 # a set interval by configuring the 573 # following two parameters. 574 575 # id_callsign = MYCALL-0 576 # id_interval = 600 577 578 # For certain homebrew RNode interfaces 579 # with low amounts of RAM, using packet 580 # flow control can be useful. By default 581 # it is disabled. 582 583 # flow_control = False 584 585 # It is possible to limit the airtime 586 # utilisation of an RNode by using the 587 # following two configuration options. 588 # The short-term limit is applied in a 589 # window of approximately 15 seconds, 590 # and the long-term limit is enforced 591 # over a rolling 60 minute window. Both 592 # options are specified in percent. 593 594 # airtime_limit_long = 1.5 595 # airtime_limit_short = 33 596 597 598 .. _interfaces-rnode-multi: 599 600 RNode Multi Interface 601 ===================== 602 603 For RNodes that support multiple LoRa transceivers, the RNode 604 Multi interface can be used to configure sub-interfaces individually. 605 606 .. warning:: 607 Radio frequency spectrum is a legally controlled resource, and legislation 608 varies widely around the world. It is your responsibility to be aware of any 609 relevant regulation for your location, and to make decisions accordingly. 610 611 .. code:: 612 613 # Here's an example of how to add an RNode Multi interface 614 # using the RNode LoRa transceiver. 615 616 [[RNode Multi Interface]] 617 type = RNodeMultiInterface 618 619 # Enable interface if you want to use it! 620 enabled = yes 621 622 # Serial port for the device 623 port = /dev/ttyACM0 624 625 # You can configure the RNode to send 626 # out identification on the channel with 627 # a set interval by configuring the 628 # following two parameters. 629 630 # id_callsign = MYCALL-0 631 # id_interval = 600 632 633 # A subinterface 634 [[[High Datarate]]] 635 # Subinterfaces can be enabled and disabled in of themselves 636 enabled = yes 637 638 # Set frequency to 2.4GHz 639 frequency = 2400000000 640 641 # Set LoRa bandwidth to 1625 KHz 642 bandwidth = 1625000 643 644 # Set TX power to 0 dBm (0.12 mW) 645 txpower = 0 646 647 # The virtual port, only the manufacturer 648 # or the person who wrote the board config 649 # can tell you what it will be for which 650 # physical hardware interface 651 vport = 1 652 653 # Select spreading factor 5. Valid 654 # range is 5 through 12, with 5 655 # being the fastest and 12 having 656 # the longest range. 657 spreadingfactor = 5 658 659 # Select coding rate 5. Valid range 660 # is 5 throough 8, with 5 being the 661 # fastest, and 8 the longest range. 662 codingrate = 5 663 664 # It is possible to limit the airtime 665 # utilisation of an RNode by using the 666 # following two configuration options. 667 # The short-term limit is applied in a 668 # window of approximately 15 seconds, 669 # and the long-term limit is enforced 670 # over a rolling 60 minute window. Both 671 # options are specified in percent. 672 673 # airtime_limit_long = 100 674 # airtime_limit_short = 100 675 676 [[[Low Datarate]]] 677 # Subinterfaces can be enabled and disabled in of themselves 678 enabled = yes 679 680 # Set frequency to 865.6 MHz 681 frequency = 865600000 682 683 # The virtual port, only the manufacturer 684 # or the person who wrote the board config 685 # can tell you what it will be for which 686 # physical hardware interface 687 vport = 0 688 689 # Set LoRa bandwidth to 125 KHz 690 bandwidth = 125000 691 692 # Set TX power to 0 dBm (0.12 mW) 693 txpower = 0 694 695 # Select spreading factor 7. Valid 696 # range is 5 through 12, with 5 697 # being the fastest and 12 having 698 # the longest range. 699 spreadingfactor = 7 700 701 # Select coding rate 5. Valid range 702 # is 5 throough 8, with 5 being the 703 # fastest, and 8 the longest range. 704 codingrate = 5 705 706 # It is possible to limit the airtime 707 # utilisation of an RNode by using the 708 # following two configuration options. 709 # The short-term limit is applied in a 710 # window of approximately 15 seconds, 711 # and the long-term limit is enforced 712 # over a rolling 60 minute window. Both 713 # options are specified in percent. 714 715 # airtime_limit_long = 100 716 # airtime_limit_short = 100 717 718 .. _interfaces-serial: 719 720 Serial Interface 721 ================ 722 723 Reticulum can be used over serial ports directly, or over any device with a 724 serial port, that will transparently pass data. Useful for communicating 725 directly over a wire-pair, or for using devices such as data radios and lasers. 726 727 .. code:: 728 729 [[Serial Interface]] 730 type = SerialInterface 731 enabled = yes 732 733 # Serial port for the device 734 port = /dev/ttyUSB0 735 736 # Set the serial baud-rate and other 737 # configuration parameters. 738 speed = 115200 739 databits = 8 740 parity = none 741 stopbits = 1 742 743 .. _interfaces-pipe: 744 745 Pipe Interface 746 ============== 747 748 Using this interface, Reticulum can use any program as an interface via `stdin` and 749 `stdout`. This can be used to easily create virtual interfaces, or to interface with 750 custom hardware or other systems. 751 752 .. code:: 753 754 [[Pipe Interface]] 755 type = PipeInterface 756 enabled = yes 757 758 # External command to execute 759 command = netcat -l 5757 760 761 # Optional respawn delay, in seconds 762 respawn_delay = 5 763 764 Reticulum will write all packets to `stdin` of the ``command`` option, and will 765 continuously read and scan its `stdout` for Reticulum packets. If ``EOF`` is reached, 766 Reticulum will try to respawn the program after waiting for ``respawn_interval`` seconds. 767 768 .. _interfaces-kiss: 769 770 KISS Interface 771 ============== 772 773 With the KISS interface, you can use Reticulum over a variety of packet 774 radio modems and TNCs, including `OpenModem <https://unsigned.io/openmodem/>`_. 775 KISS interfaces can also be configured to periodically send out beacons 776 for station identification purposes. 777 778 .. warning:: 779 Radio frequency spectrum is a legally controlled resource, and legislation 780 varies widely around the world. It is your responsibility to be aware of any 781 relevant regulation for your location, and to make decisions accordingly. 782 783 .. code:: 784 785 [[Packet Radio KISS Interface]] 786 type = KISSInterface 787 enabled = yes 788 789 # Serial port for the device 790 port = /dev/ttyUSB1 791 792 # Set the serial baud-rate and other 793 # configuration parameters. 794 speed = 115200 795 databits = 8 796 parity = none 797 stopbits = 1 798 799 # Set the modem preamble. 800 preamble = 150 801 802 # Set the modem TX tail. 803 txtail = 10 804 805 # Configure CDMA parameters. These 806 # settings are reasonable defaults. 807 persistence = 200 808 slottime = 20 809 810 # You can configure the interface to send 811 # out identification on the channel with 812 # a set interval by configuring the 813 # following two parameters. The KISS 814 # interface will only ID if the set 815 # interval has elapsed since it's last 816 # actual transmission. The interval is 817 # configured in seconds. 818 # This option is commented out and not 819 # used by default. 820 # id_callsign = MYCALL-0 821 # id_interval = 600 822 823 # Whether to use KISS flow-control. 824 # This is useful for modems that have 825 # a small internal packet buffer, but 826 # support packet flow control instead. 827 flow_control = false 828 829 .. _interfaces-ax25: 830 831 AX.25 KISS Interface 832 ==================== 833 834 If you're using Reticulum on amateur radio spectrum, you might want to 835 use the AX.25 KISS interface. This way, Reticulum will automatically 836 encapsulate it's traffic in AX.25 and also identify your stations 837 transmissions with your callsign and SSID. 838 839 Only do this if you really need to! Reticulum doesn't need the AX.25 840 layer for anything, and it incurs extra overhead on every packet to 841 encapsulate in AX.25. 842 843 A more efficient way is to use the plain KISS interface with the 844 beaconing functionality described above. 845 846 .. warning:: 847 Radio frequency spectrum is a legally controlled resource, and legislation 848 varies widely around the world. It is your responsibility to be aware of any 849 relevant regulation for your location, and to make decisions accordingly. 850 851 .. code:: 852 853 [[Packet Radio AX.25 KISS Interface]] 854 type = AX25KISSInterface 855 856 # Set the station callsign and SSID 857 callsign = NO1CLL 858 ssid = 0 859 860 # Enable interface if you want use it! 861 enabled = yes 862 863 # Serial port for the device 864 port = /dev/ttyUSB2 865 866 # Set the serial baud-rate and other 867 # configuration parameters. 868 speed = 115200 869 databits = 8 870 parity = none 871 stopbits = 1 872 873 # Set the modem preamble. A 150ms 874 # preamble should be a reasonable 875 # default, but may need to be 876 # increased for radios with slow- 877 # opening squelch and long TX/RX 878 # turnaround 879 preamble = 150 880 881 # Set the modem TX tail. In most 882 # cases this should be kept as low 883 # as possible to not waste airtime. 884 txtail = 10 885 886 # Configure CDMA parameters. These 887 # settings are reasonable defaults. 888 persistence = 200 889 slottime = 20 890 891 # Whether to use KISS flow-control. 892 # This is useful for modems with a 893 # small internal packet buffer. 894 flow_control = false 895 896 .. _interfaces-options: 897 898 Common Interface Options 899 ======================== 900 901 A number of general configuration options are available on most interfaces. 902 These can be used to control various aspects of interface behaviour. 903 904 905 * | The ``enabled`` option tells Reticulum whether or not 906 to bring up the interface. Defaults to ``False``. For any 907 interface to be brought up, the ``enabled`` option 908 must be set to ``True`` or ``Yes``. 909 910 * | The ``mode`` option allows selecting the high-level behaviour 911 of the interface from a number of options. 912 913 - The default value is ``full``. In this mode, all discovery, 914 meshing and transport functionality is available. 915 916 - In the ``access_point`` (or shorthand ``ap``) mode, the 917 interface will operate as a network access point. In this 918 mode, announces will not be automatically broadcasted on 919 the interface, and paths to destinations on the interface 920 will have a much shorter expiry time. This mode is useful 921 for creating interfaces that are mostly quiet, unless when 922 someone is actually using them. An example of this could 923 be a radio interface serving a wide area, where users are 924 expected to connect momentarily, use the network, and then 925 disappear again. 926 927 * | The ``outgoing`` option sets whether an interface is allowed 928 to transmit. Defaults to ``True``. If set to ``False`` or ``No`` 929 the interface will only receive data, and never transmit. 930 931 * | The ``network_name`` option sets the virtual network name for 932 the interface. This allows multiple separate network segments 933 to exist on the same physical channel or medium. 934 935 * | The ``passphrase`` option sets an authentication passphrase on 936 the interface. This option can be used in conjunction with the 937 ``network_name`` option, or be used alone. 938 939 * | The ``ifac_size`` option allows customising the length of the 940 Interface Authentication Codes carried by each packet on named 941 and/or authenticated network segments. It is set by default to 942 a size suitable for the interface in question, but can be set 943 to a custom size between 8 and 512 bits by using this option. 944 In normal usage, this option should not be changed from the 945 default. 946 947 * | The ``announce_cap`` option lets you configure the maximum 948 bandwidth to allocate, at any given time, to propagating 949 announces and other network upkeep traffic. It is configured at 950 2% by default, and should normally not need to be changed. Can 951 be set to any value between ``1`` and ``100``. 952 953 *If an interface exceeds its announce cap, it will queue announces 954 for later transmission. Reticulum will always prioritise propagating 955 announces from nearby nodes first. This ensures that the local 956 topology is prioritised, and that slow networks are not overwhelmed 957 by interconnected fast networks.* 958 959 *Destinations that are rapidly re-announcing will be down-prioritised 960 further. Trying to get "first-in-line" by announce spamming will have 961 the exact opposite effect: Getting moved to the back of the queue every 962 time a new announce from the excessively announcing destination is received.* 963 964 *This means that it is always beneficial to select a balanced 965 announce rate, and not announce more often than is actually necesarry 966 for your application to function.* 967 968 * | The ``bitrate`` option configures the interface bitrate. 969 Reticulum will use interface speeds reported by hardware, or 970 try to guess a suitable rate when the hardware doesn't report 971 any. In most cases, the automatically found rate should be 972 sufficient, but it can be configured by using the ``bitrate`` 973 option, to set the interface speed in *bits per second*. 974 975 976 .. _interfaces-modes: 977 978 Interface Modes 979 =============== 980 981 The optional ``mode`` setting is available on all interfaces, and allows 982 selecting the high-level behaviour of the interface from a number of modes. 983 These modes affect how Reticulum selects paths in the network, how announces 984 are propagated, how long paths are valid and how paths are discovered. 985 986 Configuring modes on interfaces is **not** strictly necessary, but can be useful 987 when building or connecting to more complex networks. If your Reticulum 988 instance is not running a Transport Node, it is rarely useful to configure 989 interface modes, and in such cases interfaces should generally be left in 990 the default mode. 991 992 * | The default mode is ``full``. In this mode, all discovery, 993 meshing and transport functionality is activated. 994 995 * | The ``gateway`` mode (or shorthand ``gw``) also has all 996 discovery, meshing and transport functionality available, 997 but will additionally try to discover unknown paths on 998 behalf of other nodes residing on the ``gateway`` interface. 999 If Reticulum receives a path request for an unknown 1000 destination, from a node on a ``gateway`` interface, it 1001 will try to discover this path via all other active interfaces, 1002 and forward the discovered path to the requestor if one is 1003 found. 1004 1005 | If you want to allow other nodes to widely resolve paths or connect 1006 to a network via an interface, it might be useful to put it in this 1007 mode. By creating a chain of ``gateway`` interfaces, other 1008 nodes will be able to immediately discover paths to any 1009 destination along the chain. 1010 1011 | *Please note!* It is the interface *facing the clients* that 1012 must be put into ``gateway`` mode for this to work, not 1013 the interface facing the wider network (for this, the ``boundary`` 1014 mode can be useful, though). 1015 1016 * | In the ``access_point`` (or shorthand ``ap``) mode, the 1017 interface will operate as a network access point. In this 1018 mode, announces will not be automatically broadcasted on 1019 the interface, and paths to destinations on the interface 1020 will have a much shorter expiry time. In addition, path 1021 requests from clients on the access point interface will 1022 be handled in the same way as the ``gateway`` interface. 1023 1024 | This mode is useful for creating interfaces that remain 1025 quiet, until someone actually starts using them. An example 1026 of this could be a radio interface serving a wide area, 1027 where users are expected to connect momentarily, use the 1028 network, and then disappear again. 1029 1030 * | The ``roaming`` mode should be used on interfaces that are 1031 roaming (physically mobile), seen from the perspective of 1032 other nodes in the network. As an example, if a vehicle is 1033 equipped with an external LoRa interface, and an internal, 1034 WiFi-based interface, that serves devices that are moving 1035 *with* the vehicle, the external LoRa interface should be 1036 configured as ``roaming``, and the internal interface can 1037 be left in the default mode. With transport enabled, such 1038 a setup will allow all internal devices to reach each other, 1039 and all other devices that are available on the LoRa side 1040 of the network, when they are in range. Devices on the LoRa 1041 side of the network will also be able to reach devices 1042 internal to the vehicle, when it is in range. Paths via 1043 ``roaming`` interfaces also expire faster. 1044 1045 * | The purpose of the ``boundary`` mode is to specify interfaces 1046 that establish connectivity with network segments that are 1047 significantly different than the one this node exists on. 1048 As an example, if a Reticulum instance is part of a LoRa-based 1049 network, but also has a high-speed connection to a 1050 public Transport Node available on the Internet, the interface 1051 connecting over the Internet should be set to ``boundary`` mode. 1052 1053 For a table describing the impact of all modes on announce propagation, 1054 please see the :ref:`Announce Propagation Rules<understanding-announcepropagation>` section. 1055 1056 .. _interfaces-announcerates: 1057 1058 Announce Rate Control 1059 ===================== 1060 1061 The built-in announce control mechanisms and the default ``announce_cap`` 1062 option described above are sufficient most of the time, but in some cases, especially on fast 1063 interfaces, it may be useful to control the target announce rate. Using the 1064 ``announce_rate_target``, ``announce_rate_grace`` and ``announce_rate_penalty`` 1065 options, this can be done on a per-interface basis, and moderates the *rate at 1066 which received announces are re-broadcasted to other interfaces*. 1067 1068 * | The ``announce_rate_target`` option sets the minimum amount of time, 1069 in seconds, that should pass between received announces, for any one 1070 destination. As an example, setting this value to ``3600`` means that 1071 announces *received* on this interface will only be re-transmitted and 1072 propagated to other interfaces once every hour, no matter how often they 1073 are received. 1074 1075 * | The optional ``announce_rate_grace`` defines the number of times a destination 1076 can violate the announce rate before the target rate is enforced. 1077 1078 * | The optional ``announce_rate_penalty`` configures an extra amount of 1079 time that is added to the normal rate target. As an example, if a penalty 1080 of ``7200`` seconds is defined, once the rate target is enforced, the 1081 destination in question will only have its announces propagated every 1082 3 hours, until it lowers its actual announce rate to within the target. 1083 1084 These mechanisms, in conjunction with the ``annouce_cap`` mechanisms mentioned 1085 above means that it is essential to select a balanced announce strategy for 1086 your destinations. The more balanced you can make this decision, the easier 1087 it will be for your destinations to make it into slower networks that many hops 1088 away. Or you can prioritise only reaching high-capacity networks with more frequent 1089 announces. 1090 1091 Current statistics and information about announce rates can be viewed using the 1092 ``rnpath -r`` command. 1093 1094 It is important to note that there is no one right or wrong way to set up announce 1095 rates. Slower networks will naturally tend towards using less frequent announces to 1096 conserve bandwidth, while very fast networks can support applications that 1097 need very frequent announces. Reticulum implements these mechanisms to ensure 1098 that a large span of network types can seamlessly *co-exist* and interconnect. 1099 1100 .. _interfaces-ingress-control: 1101 1102 New Destination Rate Limiting 1103 ============================= 1104 1105 On public interfaces, where anyone may connect and announce new destinations, 1106 it can be useful to control the rate at which announces for *new* destinations are 1107 processed. 1108 1109 If a large influx of announces for newly created or previously unknown destinations 1110 occur within a short amount of time, Reticulum will place these announces on hold, 1111 so that announce traffic for known and previously established destinations can 1112 continue to be processed without interruptions. 1113 1114 After the burst subsides, and an additional waiting period has passed, the held 1115 announces will be released at a slow rate, until the hold queue is cleared. This 1116 also means, that should a node decide to connect to a public interface, announce 1117 a large amount of bogus destinations, and then disconnect, these destination will 1118 never make it into path tables and waste network bandwidth on retransmitted 1119 announces. 1120 1121 **It's important to note** that the ingress control works at the level of *individual 1122 sub-interfaces*. As an example, this means that one client on a :ref:`TCP Server Interface<interfaces-tcps>` 1123 cannot disrupt processing of incoming announces for other connected clients on the same 1124 :ref:`TCP Server Interface<interfaces-tcps>`. All other clients on the same interface will still have new announces 1125 processed without interruption. 1126 1127 By default, Reticulum will handle this automatically, and ingress announce 1128 control will be enabled on interface where it is sensible to do so. It should 1129 generally not be neccessary to modify the ingress control configuration, 1130 but all the parameters are exposed for configuration if needed. 1131 1132 * | The ``ingress_control`` option tells Reticulum whether or not 1133 to enable announce ingress control on the interface. Defaults to 1134 ``True``. 1135 1136 * | The ``ic_new_time`` option configures how long (in seconds) an 1137 interface is considered newly spawned. Defaults to ``2*60*60`` seconds. This 1138 option is useful on publicly accessible interfaces that spawn new 1139 sub-interfaces when a new client connects. 1140 1141 * | The ``ic_burst_freq_new`` option sets the maximum announce ingress 1142 frequency for newly spawned interfaces. Defaults to ``3.5`` 1143 announces per second. 1144 1145 * | The ``ic_burst_freq`` option sets the maximum announce ingress 1146 frequency for other interfaces. Defaults to ``12`` announces 1147 per second. 1148 1149 *If an interface exceeds its burst frequency, incoming announces 1150 for unknown destinations will be temporarily held in a queue, and 1151 not processed until later.* 1152 1153 * | The ``ic_max_held_announces`` option sets the maximum amount of 1154 unique announces that will be held in the queue. Any additional 1155 unique announces will be dropped. Defaults to ``256`` announces. 1156 1157 * | The ``ic_burst_hold`` option sets how much time (in seconds) must 1158 pass after the burst frequency drops below its threshold, for the 1159 announce burst to be considered cleared. Defaults to ``60`` 1160 seconds. 1161 1162 * | The ``ic_burst_penalty`` option sets how much time (in seconds) must 1163 pass after the burst is considered cleared, before held announces can 1164 start being released from the queue. Defaults to ``5*60`` 1165 seconds. 1166 1167 * | The ``ic_held_release_interval`` option sets how much time (in seconds) 1168 must pass between releasing each held announce from the queue. Defaults 1169 to ``30`` seconds. 1170