gettingstartedfast.rst
1 ******************** 2 Getting Started Fast 3 ******************** 4 5 The best way to get started with the Reticulum Network Stack depends on what 6 you want to do. This guide will outline sensible starting paths for different 7 scenarios. 8 9 10 Standalone Reticulum Installation 11 ================================= 12 If you simply want to install Reticulum and related utilities on a system, 13 the easiest way is via the ``pip`` package manager: 14 15 .. code:: shell 16 17 pip install rns 18 19 If you do not already have pip installed, you can install it using the package manager 20 of your system with a command like ``sudo apt install python3-pip``, 21 ``sudo pamac install python-pip`` or similar. 22 23 You can also dowload the Reticulum release wheels from GitHub, or other release channels, 24 and install them offline using ``pip``: 25 26 .. code:: shell 27 28 pip install ./rns-1.1.2-py3-none-any.whl 29 30 On platforms that limit user package installation via ``pip``, you may need to manually 31 allow this using the ``--break-system-packages`` command line flag when installing. This 32 will not actually break any packages, unless you have installed Reticulum directly via 33 your operating system's package manager. 34 35 .. code:: shell 36 37 pip install rns --break-system-packages 38 39 For more detailed installation instructions, please see the 40 :ref:`Platform-Specific Install Notes<install-guides>` section. 41 42 After installation is complete, it might be helpful to refer to the 43 :ref:`Using Reticulum on Your System<using-main>` chapter. 44 45 Resolving Dependency & Installation Issues 46 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 47 On some platforms, there may not be binary packages available for all dependencies, and 48 ``pip`` installation may fail with an error message. In these cases, the issue can usually 49 be resolved by installing the development essentials packages for your platform: 50 51 .. code:: shell 52 53 # Debian / Ubuntu / Derivatives 54 sudo apt install build-essential 55 56 # Arch / Manjaro / Derivatives 57 sudo pamac install base-devel 58 59 # Fedora 60 sudo dnf groupinstall "Development Tools" "Development Libraries" 61 62 With the base development packages installed, ``pip`` should be able to compile any missing 63 dependencies from source, and complete installation even on platforms that don't have pre- 64 compiled packages available. 65 66 Try Using a Reticulum-based Program 67 ============================================= 68 69 If you simply want to try using a program built with Reticulum, a :ref:`range of different 70 programs <software-main>` exist that allow basic communication and a various other useful functions, 71 even over extremely low-bandwidth Reticulum networks. 72 73 74 Using the Included Utilities 75 ============================================= 76 Reticulum comes with a range of included utilities that make it easier to 77 manage your network, check connectivity and make Reticulum available to other 78 programs on your system. 79 80 You can use ``rnsd`` to run Reticulum as a background or foreground service, 81 and the ``rnstatus``, ``rnpath`` and ``rnprobe`` utilities to view and query 82 network status and connectivity. 83 84 To learn more about these utility programs, have a look at the 85 :ref:`Using Reticulum on Your System<using-main>` chapter of this manual. 86 87 88 Creating a Network With Reticulum 89 ============================================= 90 To create a network, you will need to specify one or more *interfaces* for 91 Reticulum to use. This is done in the Reticulum configuration file, which by 92 default is located at ``~/.reticulum/config``. You can get an example 93 configuration file with all options via ``rnsd --exampleconfig``. 94 95 When Reticulum is started for the first time, it will create a default 96 configuration file, with one active interface. This default interface uses 97 your existing Ethernet and WiFi networks (if any), and only allows you to 98 communicate with other Reticulum peers within your local broadcast domains. 99 100 To communicate further, you will have to add one or more interfaces. The default 101 configuration includes a number of examples, ranging from using TCP over the 102 internet, to LoRa and Packet Radio interfaces. 103 104 With Reticulum, you only need to configure what interfaces you want to communicate 105 over. There is no need to configure address spaces, subnets, routing tables, 106 or other things you might be used to from other network types. 107 108 Once Reticulum knows which interfaces it should use, it will automatically 109 discover topography and configure transport of data to any destinations it 110 knows about. 111 112 In situations where you already have an established WiFi or Ethernet network, and 113 many devices that want to utilise the same external Reticulum network paths (for example over 114 LoRa), it will often be sufficient to let one system act as a Reticulum gateway, by 115 adding any external interfaces to the configuration of this system, and then enabling transport on it. Any 116 other device on your local WiFi will then be able to connect to this wider Reticulum 117 network just using the default (:ref:`AutoInterface<interfaces-auto>`) configuration. 118 119 Possibly, the examples in the config file are enough to get you started. If 120 you want more information, you can read the :ref:`Building Networks<networks-main>` 121 and :ref:`Interfaces<interfaces-main>` chapters of this manual, but most importantly, 122 start with reading the next section, :ref:`Bootstrapping Connectivity<bootstrapping-connectivity>`, 123 as this provides the most essential understanding of how to ensure reliable 124 connectivity with a minimum of maintenance. 125 126 127 .. _bootstrapping-connectivity: 128 129 Bootstrapping Connectivity 130 ========================== 131 132 Reticulum is not a service you subscribe to, nor is it a single global network you "join". It is a *networking stack*; a toolkit for building communications systems that align with your specific values, requirements, and operational environment. The way you choose to connect to other Reticulum peers is entirely your own choice. 133 134 One of the most powerful aspects of Reticulum is that it provides a multitude of tools to establish, maintain, and optimize connectivity. You can use these tools in isolation or combine them in complex configurations to achieve a vast array of goals. 135 136 Whether your aim is to create a completely private, air-gapped network for your family; to build a resilient community mesh that survives infrastructure collapse; to connect far and wide to as many nodes as possible; or simply to maintain a reliable, encrypted link to a specific organization you care about, Reticulum provides the mechanisms to make it happen. 137 138 There is no "right" or "wrong" way to build a Reticulum network, and you don't need to be a network engineer just to get started. If the information flows in the way you intend, and your privacy and security requirements are met, your configuration is a success. Reticulum is designed to make the most challenging and difficult scenarios attainable, even when other networking technologies fail. 139 140 141 Finding Your Way 142 ^^^^^^^^^^^^^^^^ 143 144 When you first start using Reticulum, you need a way to obtain connectivity with the peers you want to communicate with - the process of *bootstrapping connectivity*. 145 146 .. important:: 147 148 A common mistake in modern networking is the reliance on a few centralized, hard-coded entrypoints. If every user simply connects to the same list of public IP addresses found on a website, the network becomes brittle, centralized, and ultimately fails to deliver on the promise of decentralization and resilience. You have a responsibility here. 149 150 Reticulum encourages the approach of *organic growth*. Instead of relying on permanent static connections to distant servers, you can use temporary bootstrap connections to continously *discover* more relevant or local infrastructure. Once discovered, your system can automatically form stronger, more direct links to these peers, and discard the temporary bootstrap links. This results in a web of connections that are geographically relevant, resilient and efficient. 151 152 It *is* possible to simply add a few public entrypoints to the ``[interfaces]`` section of your Reticulum configuration and be connected, but a better option is to enable :ref:`interface discovery<using-interface_discovery>` and either manually select relevant, local interfaces, or enable discovered interface auto-connection. 153 154 A relevant option in this context is the :ref:`bootstrap only<interfaces-options>` interface option. This is an automated tool for better distributing connectivity. By enabling interface discovery and auto-connection, and marking an interface as ``bootstrap_only``, you tell Reticulum to use that interface primarliy to find connectivity options, and then disconnect it once sufficient entrypoints have been discovered. This helps create a network topology that favors locality and resilience over the simple centralization caused by using only a few static entrypoints. 155 156 Good places to find interface definitions for bootstrapping connectivity are websites like 157 `directory.rns.recipes <https://directory.rns.recipes/>`_ and `rmap.world <https://rmap.world/>`_. 158 159 160 Build Personal Infrastructure 161 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 162 163 You do not need a datacenter to be a meaningful part of the Reticulum ecosystem. In fact, the most important nodes in the network are often the smallest ones. 164 165 We strongly encourage everyone, even home users, to think in terms of building **personal infrastructure**. Don't connect every phone, tablet, and computer in your house directly to a public internet gateway. Instead, repurpose an old computer, a Raspberry Pi, or a supported router to act as your own, personal **Transport Node**: 166 167 * Your local Transport Node sits in your home, connected to your WiFi and perhaps a radio interface (like an RNode). 168 * You configure this node with a ``bootstrap_only`` interface (perhaps a TCP tunnel to a wider network) and enable interface discovery. 169 * While you sleep, work, or cook, your node listens to the network. It discovers other local community members, validates their Network Identities, and automatically establishes direct links. 170 * Your personal devices now connect to your *local* node, which is integrated into a living, breathing local mesh. Your traffic flows through local paths provided by other real people in the community rather than bouncing off a distant server. 171 172 **Don't wait for others to build the networks you want to see**. Every network is important, perhaps even most so those that support individual families and persons. Once enough of this personal, local infrastructure exist, connecting them directly to each other, without traversing the public Internet, becomes inevitable. 173 174 175 Mixing Strategies 176 ^^^^^^^^^^^^^^^^^ 177 178 There is no requirement to commit to a single strategy. The most robust setups often mix static, dynamic, and discovered interfaces. 179 180 * **Static Interfaces:** You maintain a permanent interface to a trusted friend or organization using a static configuration. 181 * **Bootstrap Links:** You connect a ``bootstrap_only`` interface to a public gateway on the Internet to scan for new connectable peers or to regain connectivity if your other interfaces fail. 182 * **Local Wide-Area Connectivity:** You run a ``RNodeInterface`` on a shared frequency, giving you completely self-sovereign and private wide-area access to both your own network and other Reticulum peers globally, without any "service providers" being able to control or monitor how you interact with people. 183 184 By combining these methods, you create a system that is secure against single points of failure, adaptable to changing network conditions, and better integrated into your physical and social reality. 185 186 187 Network Health & Responsibility 188 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 189 190 As you participate in the wider networks you discover and build, you will inevitably encounter peers that are misconfigured, malicious, or simply broken. To protect your resources and those of your local peers, you can utilize the :ref:`Blackhole Management<using-blackhole_management>` system. 191 192 Whether you manually block a spamming identity or subscribe to a blackhole list maintained by a trusted Network Identity, these tools help ensure that *your* transport capacity is used for what *you* consider legitimate communication. This keeps your local segment efficient and contributes to the health of the wider network. 193 194 195 Contributing to the Global Ret 196 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 197 198 If you have the means to host a stable node with a public IP address, consider becoming a :ref:`Public Entrypoint<hosting-entrypoints>`. By :ref:`publishing your interface as discoverable<interfaces-discoverable>`, you provide a potential connection point for others, helping the network grow and reach new areas. 199 200 For guidelines on how to properly configure a public entrypoint, refer to the :ref:`Hosting Public Entrypoints<hosting-entrypoints>` section. 201 202 Connect to the Distributed Backbone 203 =================================== 204 205 A global, distributed backbone of Reticulum Transport Nodes is being run by volunteers from around the world. This network constitutes a heterogenous collection of both public and private nodes that form an uncoordinated, voluntary inter-networking backbone that currently provides global transport and internetworking capabilities for Reticulum. 206 207 As a good starting point, you can find interface definitions for connecting your own networks to this backbone on websites such as `directory.rns.recipes <https://directory.rns.recipes/>`_ and `rmap.world <https://rmap.world/>`_. 208 209 .. tip:: 210 Don't rely on just a single connection to the distributed backbone for everyday use. It is much better to have several redundant connections configured, and enable the interface discovery options, so your nodes can continously discover peering opportunities as the network evolves. Refer to the :ref:`Bootstrapping Connectivity<bootstrapping-connectivity>` section to understand the options. 211 212 213 214 .. _hosting-entrypoints: 215 216 Hosting Public Entrypoints 217 ========================== 218 219 If you want to help build a strong global interconnection backbone, you can host a public (or private) entry-point to a Reticulum network over the 220 Internet. This section offers some helpful pointers. Once you have set up your public entrypoint, it is a great idea to :ref:`make it discoverable over Reticulum<interfaces-discoverable>`. 221 222 You will need a machine, physical or virtual with a public IP address, that can be reached by other devices on the Internet. 223 224 The most efficient and performant way to host a connectable entry-point supporting many 225 users is to use the ``BackboneInterface``. This interface type is fully compatible with 226 the ``TCPClientInterface`` and ``TCPServerInterface`` types, but much faster and uses 227 less system resources, allowing your device to handle thousands of connections even on 228 small systems. 229 230 It is also important to set your connectable interface to ``gateway`` mode, since this 231 will greatly improve network convergence time and path resolution for anyone connecting 232 to your entry-point. 233 234 .. code:: ini 235 236 # This example demonstrates a backbone interface 237 # configured for acting as a gateway for users to 238 # connect to either a public or private network 239 240 [[Public Gateway]] 241 type = BackboneInterface 242 enabled = yes 243 mode = gateway 244 listen_on = 0.0.0.0 245 port = 4242 246 247 # On publicly available interfaces, it can be 248 # a good idea to configure sensible announce 249 # rate targets. 250 announce_rate_target = 3600 251 announce_rate_penalty = 3600 252 announce_rate_grace = 12 253 254 If instead you want to make a private entry-point from the Internet, you can use the 255 :ref:`IFAC name and passphrase options<interfaces-options>` to secure your interface with a network name and passphrase. 256 257 .. code:: ini 258 259 # A private entry-point requiring a pre-shared 260 # network name and passphrase to connect to. 261 262 [[Private Gateway]] 263 type = BackboneInterface 264 enabled = yes 265 mode = gateway 266 listen_on = 0.0.0.0 267 port = 4242 268 network_name = private_ret 269 passphrase = 2owjajquafIanPecAc 270 271 If you are hosting an entry-point on an operating system that does not support 272 ``BackboneInterface``, you can use ``TCPServerInterface`` instead, although it will 273 not be as performant. 274 275 276 Connecting Reticulum Instances Over the Internet 277 ================================================ 278 Reticulum currently offers three interfaces suitable for connecting instances over the Internet: :ref:`Backbone<interfaces-backbone>`, :ref:`TCP<interfaces-tcps>` 279 and :ref:`I2P<interfaces-i2p>`. Each interface offers a different set of features, and Reticulum 280 users should carefully choose the interface which best suites their needs. 281 282 The ``TCPServerInterface`` allows users to host an instance accessible over TCP/IP. This 283 method is generally faster, lower latency, and more energy efficient than using ``I2PInterface``, 284 however it also leaks more data about the server host. 285 286 The ``BackboneInterface`` is a very fast and efficient interface type available on POSIX operating 287 systems, designed to handle thousands of connections simultaneously with low memory, processing 288 and I/O overhead. It is fully compatible with the TCP-based interface types. 289 290 TCP connections reveal the IP address of both your instance and the server to anyone who can 291 inspect the connection. Someone could use this information to determine your location or identity. Adversaries 292 inspecting your packets may be able to record packet metadata like time of transmission and packet size. 293 Even though Reticulum encrypts traffic, TCP does not, so an adversary may be able to use 294 packet inspection to learn that a system is running Reticulum, and what other IP addresses connect to it. 295 Hosting a publicly reachable instance over TCP also requires a publicly reachable IP address, 296 which most Internet connections don't offer anymore. 297 298 The ``I2PInterface`` routes messages through the `Invisible Internet Protocol 299 (I2P) <https://geti2p.net/en/>`_. To use this interface, users must also run an I2P daemon in 300 parallel to ``rnsd``. For always-on I2P nodes it is recommended to use `i2pd <https://i2pd.website/>`_. 301 302 By default, I2P will encrypt and mix all traffic sent over the Internet, and 303 hide both the sender and receiver Reticulum instance IP addresses. Running an I2P node 304 will also relay other I2P user's encrypted packets, which will use extra 305 bandwidth and compute power, but also makes timing attacks and other forms of 306 deep-packet-inspection much more difficult. 307 308 I2P also allows users to host globally available Reticulum instances from non-public IP's and behind firewalls and NAT. 309 310 In general it is recommended to use an I2P node if you want to host a publicly accessible 311 instance, while preserving anonymity. If you care more about performance, and a slightly 312 easier setup, use TCP. 313 314 Adding Radio Interfaces 315 ======================= 316 Once you have Reticulum installed and working, you can add radio interfaces with 317 any compatible hardware you have available. Reticulum supports a wide range of radio 318 hardware, and if you already have any available, it is very likely that it will 319 work with Reticulum. For information on how to configure this, see the 320 :ref:`Interfaces<interfaces-main>` section of this manual. 321 322 If you do not already have transceiver hardware available, you can easily and 323 cheaply build an :ref:`RNode<rnode-main>`, which is a general-purpose long-range 324 digital radio transceiver, that integrates easily with Reticulum. 325 326 To build one yourself requires installing a custom firmware on a supported LoRa 327 development board with an auto-install script or web-based flasher. 328 Please see the :ref:`Communications Hardware<hardware-main>` chapter for a guide. 329 If you prefer purchasing a ready-made unit, you can refer to the 330 :ref:`list of suppliers<rnode-suppliers>`. 331 332 Other radio-based hardware interfaces are being developed and made available by 333 the broader Reticulum community. You can find more information on such topics 334 over Reticulum-based information sharing systems. 335 336 If you have communications hardware that is not already supported by any of the 337 :ref:`existing interface types<interfaces-main>`, it is easy to write (and potentially 338 publish) a :ref:`custom interface module<interfaces-custom>` that makes it compatible with Reticulum. 339 340 341 Creating and Using Custom Interfaces 342 ==================================== 343 344 While Reticulum includes a flexible and broad range of built-in interfaces, these 345 will not cover every conceivable type of communications hardware that Reticulum 346 can potentially use to communicate. 347 348 It is therefore possible to easily write your own interface modules, that can be 349 loaded at run-time and used on-par with any of the built-in interface types. 350 351 For more information on this subject, and code examples to build on, please see 352 the :ref:`Configuring Interfaces<interfaces-main>` chapter. 353 354 355 Develop a Program with Reticulum 356 =========================================== 357 If you want to develop programs that use Reticulum, the easiest way to get 358 started is to install the latest release of Reticulum via pip: 359 360 .. code:: 361 362 pip install rns 363 364 The above command will install Reticulum and dependencies, and you will be 365 ready to import and use RNS in your own programs. The next step will most 366 likely be to look at some :ref:`Example Programs<examples-main>`. 367 368 The entire Reticulum API is documented in the :ref:`API Reference<api-main>` 369 chapter of this manual. Before diving in, it's probably a good idea to read 370 this manual in full, but at least start with the :ref:`Understanding Reticulum<understanding-main>` chapter. 371 372 373 .. _install-guides: 374 375 Platform-Specific Install Notes 376 ============================================== 377 378 Some platforms require a slightly different installation procedure, or have 379 various quirks that are worth being aware of. These are listed here. 380 381 Android 382 ^^^^^^^^^^^^^^^^^^^^^^^^ 383 Reticulum can be used on Android in different ways. The easiest way to get 384 started is using an app like `Sideband <https://unsigned.io/sideband>`_. 385 386 For more control and features, you can use Reticulum and related programs via 387 the `Termux app <https://termux.com/>`_, at the time of writing available on 388 `F-droid <https://f-droid.org>`_. 389 390 Termux is a terminal emulator and Linux environment for Android based devices, 391 which includes the ability to use many different programs and libraries, 392 including Reticulum. 393 394 To use Reticulum within the Termux environment, you will need to install 395 ``python`` and the ``python-cryptography`` library using ``pkg``, the package-manager 396 build into Termux. After that, you can use ``pip`` to install Reticulum. 397 398 From within Termux, execute the following: 399 400 .. code:: shell 401 402 # First, make sure indexes and packages are up to date. 403 pkg update 404 pkg upgrade 405 406 # Then install python and the cryptography library. 407 pkg install python python-cryptography 408 409 # Make sure pip is up to date, and install the wheel module. 410 pip install wheel pip --upgrade 411 412 # Install Reticulum 413 pip install rns 414 415 If for some reason the ``python-cryptography`` package is not available for 416 your platform via the Termux package manager, you can attempt to build it 417 locally on your device using the following command: 418 419 .. code:: shell 420 421 # First, make sure indexes and packages are up to date. 422 pkg update 423 pkg upgrade 424 425 # Then install dependencies for the cryptography library. 426 pkg install python build-essential openssl libffi rust 427 428 # Make sure pip is up to date, and install the wheel module. 429 pip install wheel pip --upgrade 430 431 # To allow the installer to build the cryptography module, 432 # we need to let it know what platform we are compiling for: 433 export CARGO_BUILD_TARGET="aarch64-linux-android" 434 435 # Start the install process for the cryptography module. 436 # Depending on your device, this can take several minutes, 437 # since the module must be compiled locally on your device. 438 pip install cryptography 439 440 # If the above installation succeeds, you can now install 441 # Reticulum and any related software 442 pip install rns 443 444 It is also possible to include Reticulum in apps compiled and distributed as 445 Android APKs. A detailed tutorial and example source code will be included 446 here at a later point. Until then you can use the `Sideband source code <https://github.com/markqvist/sideband>`_ as an example and starting point. 447 448 449 ARM64 450 ^^^^^^^^^^^^^^^^^^^^^^^^ 451 On some architectures, including ARM64, not all dependencies have precompiled 452 binaries. On such systems, you may need to install ``python3-dev`` (or similar) before 453 installing Reticulum or programs that depend on Reticulum. 454 455 .. code:: shell 456 457 # Install Python and development packages 458 sudo apt update 459 sudo apt install python3 python3-pip python3-dev 460 461 # Install Reticulum 462 python3 -m pip install rns 463 464 With these packages installed, ``pip`` will be able to build any missing dependencies 465 on your system locally. 466 467 468 Debian Bookworm 469 ^^^^^^^^^^^^^^^^^^^^^^^^ 470 On versions of Debian released after April 2023, it is no longer possible by default 471 to use ``pip`` to install packages onto your system. Unfortunately, you will need to 472 use the replacement ``pipx`` command instead, which places installed packages in an 473 isolated environment. This should not negatively affect Reticulum, but will not work 474 for including and using Reticulum in your own scripts and programs. 475 476 .. code:: shell 477 478 # Install pipx 479 sudo apt install pipx 480 481 # Make installed programs available on the command line 482 pipx ensurepath 483 484 # Install Reticulum 485 pipx install rns 486 487 Alternatively, you can restore normal behaviour to ``pip`` by creating or editing 488 the configuration file located at ``~/.config/pip/pip.conf``, and adding the 489 following section: 490 491 .. code:: ini 492 493 [global] 494 break-system-packages = true 495 496 For a one-shot installation of Reticulum, without globally enabling the ``break-system-packages`` 497 option, you can use the following command: 498 499 .. code:: shell 500 501 pip install rns --break-system-packages 502 503 .. note:: 504 The ``--break-system-packages`` directive is a somewhat misleading choice 505 of words. Setting it will of course not break any system packages, but will simply 506 allow installing ``pip`` packages user- and system-wide. While this *could* in rare 507 cases lead to version conflicts, it does not generally pose any problems, especially 508 not in the case of installing Reticulum. 509 510 511 MacOS 512 ^^^^^^^^^^^^^^^^^^^^^^^^^ 513 To install Reticulum on macOS, you will need to have Python and the ``pip`` package 514 manager installed. 515 516 Systems running macOS can vary quite widely in whether or not Python is pre-installed, 517 and if it is, which version is installed, and whether the ``pip`` package manager is 518 also installed and set up. If in doubt, you can `download and install <https://www.python.org/downloads/>`_ 519 Python manually. 520 521 When Python and ``pip`` is available on your system, simply open a terminal window 522 and use one of the following commands: 523 524 .. code:: shell 525 526 # Install Reticulum and utilities with pip: 527 pip3 install rns 528 529 # On some versions, you may need to use the 530 # flag --break-system-packages to install: 531 pip3 install rns --break-system-packages 532 533 .. note:: 534 The ``--break-system-packages`` directive is a somewhat misleading choice 535 of words. Setting it will of course not break any system packages, but will simply 536 allow installing ``pip`` packages user- and system-wide. While this *could* in rare 537 cases lead to version conflicts, it does not generally pose any problems, especially 538 not in the case of installing Reticulum. 539 540 Additionally, some version combinations of macOS and Python require you to 541 manually add your installed ``pip`` packages directory to your `PATH` environment 542 variable, before you can use installed commands in your terminal. Usually, adding 543 the following line to your shell init script (for example ``~/.zshrc``) will be enough: 544 545 .. code:: shell 546 547 export PATH=$PATH:~/Library/Python/3.9/bin 548 549 Adjust Python version and shell init script location according to your system. 550 551 552 OpenWRT 553 ^^^^^^^^^^^^^^^^^^^^^^^^^ 554 On OpenWRT systems with sufficient storage and memory, you can install 555 Reticulum and related utilities using the `opkg` package manager and `pip`. 556 557 .. note:: 558 559 At the time of releasing this manual, work is underway to create pre-built 560 Reticulum packages for OpenWRT, with full configuration, service 561 and ``uci`` integration. Please see the `feed-reticulum <https://github.com/gretel/feed-reticulum>`_ 562 and `reticulum-openwrt <https://github.com/gretel/reticulum-openwrt>`_ 563 repositories for more information. 564 565 To install Reticulum on OpenWRT, first log into a command line session, and 566 then use the following instructions: 567 568 .. code:: shell 569 570 # Install dependencies 571 opkg install python3 python3-pip python3-cryptography python3-pyserial 572 573 # Install Reticulum 574 pip install rns 575 576 # Start rnsd with debug logging enabled 577 rnsd -vvv 578 579 .. note:: 580 581 The above instructions have been verified and tested on OpenWRT 21.02 only. 582 It is likely that other versions may require slightly altered installation 583 commands or package names. You will also need enough free space in your 584 overlay FS, and enough free RAM to actually run Reticulum and any related 585 programs and utilities. 586 587 Depending on your device configuration, you may need to adjust firewall rules 588 for Reticulum connectivity to and from your device to work. Until proper 589 packaging is ready, you will also need to manually create a service or startup 590 script to automatically laucnh Reticulum at boot time. 591 592 Please also note that the `AutoInterface` requires link-local IPv6 addresses 593 to be enabled for any Ethernet and WiFi devices you intend to use. If ``ip a`` 594 shows an address starting with ``fe80::`` for the device in question, 595 ``AutoInterface`` should work for that device. 596 597 Raspberry Pi 598 ^^^^^^^^^^^^^^^^^^^^^^^^^ 599 It is currently recommended to use a 64-bit version of the Raspberry Pi OS 600 if you want to run Reticulum on Raspberry Pi computers, since 32-bit versions 601 don't always have packages available for some dependencies. If Python and the 602 `pip` package manager is not already installed, do that first, and then 603 install Reticulum using `pip`. 604 605 .. code:: shell 606 607 # Install dependencies 608 sudo apt install python3 python3-pip python3-cryptography python3-pyserial 609 610 # Install Reticulum 611 pip install rns --break-system-packages 612 613 .. note:: 614 The ``--break-system-packages`` directive is a somewhat misleading choice 615 of words. Setting it will of course not break any system packages, but will simply 616 allow installing ``pip`` packages user- and system-wide. While this *could* in rare 617 cases lead to version conflicts, it does not generally pose any problems, especially 618 not in the case of installing Reticulum. 619 620 While it is possible to install and run Reticulum on 32-bit Rasperry Pi OSes, 621 it will require manually configuring and installing required build dependencies, 622 and is not detailed in this manual. 623 624 625 RISC-V 626 ^^^^^^^^^^^^^^^^^^^^^^^^ 627 On some architectures, including RISC-V, not all dependencies have precompiled 628 binaries. On such systems, you may need to install ``python3-dev`` (or similar) before 629 installing Reticulum or programs that depend on Reticulum. 630 631 .. code:: shell 632 633 # Install Python and development packages 634 sudo apt update 635 sudo apt install python3 python3-pip python3-dev 636 637 # Install Reticulum 638 python3 -m pip install rns 639 640 With these packages installed, ``pip`` will be able to build any missing dependencies 641 on your system locally. 642 643 644 Ubuntu Lunar 645 ^^^^^^^^^^^^^^^^^^^^^^^^ 646 On versions of Ubuntu released after April 2023, it is no longer possible by default 647 to use ``pip`` to install packages onto your system. Unfortunately, you will need to 648 use the replacement ``pipx`` command instead, which places installed packages in an 649 isolated environment. This should not negatively affect Reticulum, but will not work 650 for including and using Reticulum in your own scripts and programs. 651 652 .. code:: shell 653 654 # Install pipx 655 sudo apt install pipx 656 657 # Make installed programs available on the command line 658 pipx ensurepath 659 660 # Install Reticulum 661 pipx install rns 662 663 Alternatively, you can restore normal behaviour to ``pip`` by creating or editing 664 the configuration file located at ``~/.config/pip/pip.conf``, and adding the 665 following section: 666 667 .. code:: text 668 669 [global] 670 break-system-packages = true 671 672 For a one-shot installation of Reticulum, without globally enabling the ``break-system-packages`` 673 option, you can use the following command: 674 675 .. code:: text 676 677 pip install rns --break-system-packages 678 679 .. note:: 680 The ``--break-system-packages`` directive is a somewhat misleading choice 681 of words. Setting it will of course not break any system packages, but will simply 682 allow installing ``pip`` packages user- and system-wide. While this *could* in rare 683 cases lead to version conflicts, it does not generally pose any problems, especially 684 not in the case of installing Reticulum. 685 686 Windows 687 ^^^^^^^^^^^^^^^^^^^^^^^^^ 688 On Windows operating systems, the easiest way to install Reticulum is by using the 689 ``pip`` package manager from the command line (either the command prompt or Windows 690 Powershell). 691 692 If you don't already have Python installed, `download and install Python <https://www.python.org/downloads/>`_. 693 At the time of publication of this manual, the recommended version is `Python 3.12.7 <https://www.python.org/downloads/release/python-3127>`_. 694 695 **Important!** When asked by the installer, make sure to add the Python program to 696 your PATH environment variables. If you don't do this, you will not be able to 697 use the ``pip`` installer, or run the included Reticulum utility programs (such as 698 ``rnsd`` and ``rnstatus``) from the command line. 699 700 After installing Python, open the command prompt or Windows Powershell, and type: 701 702 .. code:: shell 703 704 pip install rns 705 706 You can now use Reticulum and all included utility programs directly from your 707 preferred command line interface. 708 709 Pure-Python Reticulum 710 ============================================== 711 712 .. warning:: 713 If you use the ``rnspure`` package to run Reticulum on systems that 714 do not support `PyCA/cryptography <https://github.com/pyca/cryptography>`_, it is 715 important that you read and understand the :ref:`Cryptographic Primitives <understanding-primitives>` 716 section of this manual. 717 718 In some rare cases, and on more obscure system types, it is not possible to 719 install one or more dependencies. In such situations, 720 you can use the ``rnspure`` package instead of the ``rns`` package, or use ``pip`` 721 with the ``--no-dependencies`` command-line option. The ``rnspure`` 722 package requires no external dependencies for installation. Please note that the 723 actual contents of the ``rns`` and ``rnspure`` packages are *completely identical*. 724 The only difference is that the ``rnspure`` package lists no dependencies required 725 for installation. 726 727 No matter how Reticulum is installed and started, it will load external dependencies 728 only if they are *needed* and *available*. If for example you want to use Reticulum 729 on a system that cannot support ``pyserial``, it is perfectly possible to do so using 730 the `rnspure` package, but Reticulum will not be able to use serial-based interfaces. 731 All other available modules will still be loaded when needed.