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:: 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:: 27 28 pip install ./rns-0.5.1-py3-none-any.whl 29 30 For more detailed installation instructions, please see the 31 :ref:`Platform-Specific Install Notes<install-guides>` section. 32 33 After installation is complete, it might be helpful to refer to the 34 :ref:`Using Reticulum on Your System<using-main>` chapter. 35 36 Resolving Dependency & Installation Issues 37 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 38 On some platforms, there may not be binary packages available for all dependencies, and 39 ``pip`` installation may fail with an error message. In these cases, the issue can usually 40 be resolved by installing the development essentials packages for your platform: 41 42 .. code:: 43 44 # Debian / Ubuntu / Derivatives 45 sudo apt install build-essential 46 47 # Arch / Manjaro / Derivatives 48 sudo pamac install base-devel 49 50 # Fedora 51 sudo dnf groupinstall "Development Tools" "Development Libraries" 52 53 With the base development packages installed, ``pip`` should be able to compile any missing 54 dependencies from source, and complete installation even on platforms that don't have pre- 55 compiled packages available. 56 57 Try Using a Reticulum-based Program 58 ============================================= 59 60 If you simply want to try using a program built with Reticulum, a few different 61 programs exist that allow basic communication and a range of other useful functions, 62 even over extremely low-bandwidth Reticulum networks. 63 64 These programs will let you get a feel for how Reticulum works. They have been designed 65 to run well over networks based on LoRa or packet radio, but can also be used over fast 66 links, such as local WiFi, wired Ethernet, the Internet, or any combination. 67 68 As such, it is easy to get started experimenting, without having to set up any radio 69 transceivers or infrastructure just to try it out. Launching the programs on separate 70 devices connected to the same WiFi network is enough to get started, and physical 71 radio interfaces can then be added later. 72 73 Remote Shell 74 ^^^^^^^^^^^^ 75 76 The `rnsh <https://github.com/acehoss/rnsh>`_ program lets you establish fully interactive 77 remote shell sessions over Reticulum. It also allows you to pipe any program to or from a 78 remote system, and is similar to how ``ssh`` works. The ``rnsh`` is very efficient, and 79 can facilitate fully interactive shell sessions, even over extremely low-bandwidth links, 80 such as LoRa or packet radio. 81 82 Nomad Network 83 ^^^^^^^^^^^^^ 84 85 The terminal-based program `Nomad Network <https://github.com/markqvist/nomadnet>`_ 86 provides a complete encrypted communications suite built with Reticulum. It features 87 encrypted messaging (both direct and delayed-delivery for offline users), file sharing, 88 and has a built-in text-browser and page server with support for dynamically rendered pages, 89 user authentication and more. 90 91 .. image:: screenshots/nomadnet_3.png 92 :target: _images/nomadnet_3.png 93 94 `Nomad Network <https://github.com/markqvist/nomadnet>`_ is a user-facing client 95 for the messaging and information-sharing protocol 96 `LXMF <https://github.com/markqvist/lxmf>`_, another project built with Reticulum. 97 98 You can install Nomad Network via pip: 99 100 .. code:: 101 102 # Install ... 103 pip install nomadnet 104 105 # ... and run 106 nomadnet 107 108 .. note:: 109 If this is the very first time you use ``pip`` to install a program 110 on your system, you might need to reboot your system for your program to become 111 available. If you get a "command not found" error or similar when running the 112 program, reboot your system and try again. In some cases, you may even need to 113 manually add the ``pip`` install path to your ``PATH`` environment variable. 114 115 Sideband 116 ^^^^^^^^ 117 118 If you would rather use a program with a graphical user interface, you can take 119 a look at `Sideband <https://unsigned.io/sideband>`_, which is available for Android, 120 Linux, macOS and Windows. 121 122 .. only:: html 123 124 .. image:: screenshots/sideband_devices.webp 125 :align: center 126 :target: _images/sideband_devices.webp 127 128 .. only:: latex 129 130 .. image:: screenshots/sideband_devices.png 131 :align: center 132 :target: _images/sideband_devices.png 133 134 Sideband allows you to communicate with other people or LXMF-compatible 135 systems over Reticulum networks using LoRa, Packet Radio, WiFi, I2P, Encrypted QR 136 Paper Messages, or anything else Reticulum supports. It also interoperates with 137 the Nomad Network program. 138 139 MeshChat 140 ^^^^^^^^ 141 142 The `Reticulum MeshChat <https://github.com/liamcottle/reticulum-meshchat>`_ application 143 is a user-friendly LXMF client for macOS and Windows, that also includes voice call 144 functionality, and a range of other interesting functions. 145 146 .. only:: html 147 148 .. image:: screenshots/meshchat_1.webp 149 :align: center 150 :target: _images/meshchat_1.webp 151 152 .. only:: latex 153 154 .. image:: screenshots/meshchat_1.png 155 :align: center 156 :target: _images/meshchat_1.png 157 158 Reticulum MeshChat is of course also compatible with Sideband and Nomad Network, or 159 any other LXMF client. 160 161 Using the Included Utilities 162 ============================================= 163 Reticulum comes with a range of included utilities that make it easier to 164 manage your network, check connectivity and make Reticulum available to other 165 programs on your system. 166 167 You can use ``rnsd`` to run Reticulum as a background or foreground service, 168 and the ``rnstatus``, ``rnpath`` and ``rnprobe`` utilities to view and query 169 network status and connectivity. 170 171 To learn more about these utility programs, have a look at the 172 :ref:`Using Reticulum on Your System<using-main>` chapter of this manual. 173 174 175 Creating a Network With Reticulum 176 ============================================= 177 To create a network, you will need to specify one or more *interfaces* for 178 Reticulum to use. This is done in the Reticulum configuration file, which by 179 default is located at ``~/.reticulum/config``. You can get an example 180 configuration file with all options via ``rnsd --exampleconfig``. 181 182 When Reticulum is started for the first time, it will create a default 183 configuration file, with one active interface. This default interface uses 184 your existing Ethernet and WiFi networks (if any), and only allows you to 185 communicate with other Reticulum peers within your local broadcast domains. 186 187 To communicate further, you will have to add one or more interfaces. The default 188 configuration includes a number of examples, ranging from using TCP over the 189 internet, to LoRa and Packet Radio interfaces. 190 191 With Reticulum, you only need to configure what interfaces you want to communicate 192 over. There is no need to configure address spaces, subnets, routing tables, 193 or other things you might be used to from other network types. 194 195 Once Reticulum knows which interfaces it should use, it will automatically 196 discover topography and configure transport of data to any destinations it 197 knows about. 198 199 In situations where you already have an established WiFi or Ethernet network, and 200 many devices that want to utilise the same external Reticulum network paths (for example over 201 LoRa), it will often be sufficient to let one system act as a Reticulum gateway, by 202 adding any external interfaces to the configuration of this system, and then enabling transport on it. Any 203 other device on your local WiFi will then be able to connect to this wider Reticulum 204 network just using the default (:ref:`AutoInterface<interfaces-auto>`) configuration. 205 206 Possibly, the examples in the config file are enough to get you started. If 207 you want more information, you can read the :ref:`Building Networks<networks-main>` 208 and :ref:`Interfaces<interfaces-main>` chapters of this manual. 209 210 Connecting Reticulum Instances Over the Internet 211 ================================================ 212 Reticulum currently offers two interfaces suitable for connecting instances over the Internet: :ref:`TCP<interfaces-tcps>` 213 and :ref:`I2P<interfaces-i2p>`. Each interface offers a different set of features, and Reticulum 214 users should carefully choose the interface which best suites their needs. 215 216 The ``TCPServerInterface`` allows users to host an instance accessible over TCP/IP. This 217 method is generally faster, lower latency, and more energy efficient than using ``I2PInterface``, 218 however it also leaks more data about the server host. 219 220 TCP connections reveal the IP address of both your instance and the server to anyone who can 221 inspect the connection. Someone could use this information to determine your location or identity. Adversaries 222 inspecting your packets may be able to record packet metadata like time of transmission and packet size. 223 Even though Reticulum encrypts traffic, TCP does not, so an adversary may be able to use 224 packet inspection to learn that a system is running Reticulum, and what other IP addresses connect to it. 225 Hosting a publicly reachable instance over TCP also requires a publicly reachable IP address, 226 which most Internet connections don't offer anymore. 227 228 The ``I2PInterface`` routes messages through the `Invisible Internet Protocol 229 (I2P) <https://geti2p.net/en/>`_. To use this interface, users must also run an I2P daemon in 230 parallel to ``rnsd``. For always-on I2P nodes it is recommended to use `i2pd <https://i2pd.website/>`_. 231 232 By default, I2P will encrypt and mix all traffic sent over the Internet, and 233 hide both the sender and receiver Reticulum instance IP addresses. Running an I2P node 234 will also relay other I2P user's encrypted packets, which will use extra 235 bandwidth and compute power, but also makes timing attacks and other forms of 236 deep-packet-inspection much more difficult. 237 238 I2P also allows users to host globally available Reticulum instances from non-public IP's and behind firewalls and NAT. 239 240 In general it is recommended to use an I2P node if you want to host a publicly accessible 241 instance, while preserving anonymity. If you care more about performance, and a slightly 242 easier setup, use TCP. 243 244 245 Connect to the Public Testnet 246 =========================================== 247 248 An experimental public testnet has been made accessible over both I2P and TCP. You can join it 249 by adding one of the following interfaces to your ``.reticulum/config`` file: 250 251 .. code:: 252 253 # TCP/IP interface to the RNS Amsterdam Hub 254 [[RNS Testnet Amsterdam]] 255 type = TCPClientInterface 256 enabled = yes 257 target_host = amsterdam.connect.reticulum.network 258 target_port = 4965 259 260 # TCP/IP interface to the BetweenTheBorders Hub (community-provided) 261 [[RNS Testnet BetweenTheBorders]] 262 type = TCPClientInterface 263 enabled = yes 264 target_host = reticulum.betweentheborders.com 265 target_port = 4242 266 267 # Interface to Testnet I2P Hub 268 [[RNS Testnet I2P Hub]] 269 type = I2PInterface 270 enabled = yes 271 peers = g3br23bvx3lq5uddcsjii74xgmn6y5q325ovrkq2zw2wbzbqgbuq.b32.i2p 272 273 Many other Reticulum instances are connecting to this testnet, and you can also join it 274 via other entry points if you know them. There is absolutely no control over the network 275 topography, usage or what types of instances connect. It will also occasionally be used 276 to test various failure scenarios, and there are no availability or service guarantees. 277 Expect weird things to happen on this network, as people experiment and try out things. 278 279 It probably goes without saying, but *don't use the testnet entry-points as 280 hardcoded or default interfaces in any applications you ship to users*. When 281 shipping applications, the best practice is to provide your own default 282 connectivity solutions, if needed and applicable, or in most cases, simply 283 leave it up to the user which networks to connect to, and how. 284 285 286 Adding Radio Interfaces 287 ============================================== 288 Once you have Reticulum installed and working, you can add radio interfaces with 289 any compatible hardware you have available. Reticulum supports a wide range of radio 290 hardware, and if you already have any available, it is very likely that it will 291 work with Reticulum. For information on how to configure this, see the 292 :ref:`Interfaces<interfaces-main>` section of this manual. 293 294 If you do not already have transceiver hardware available, you can easily and 295 cheaply build an :ref:`RNode<rnode-main>`, which is a general-purpose long-range 296 digital radio transceiver, that integrates easily with Reticulum. 297 298 To build one yourself requires installing a custom firmware on a supported LoRa 299 development board with an auto-install script. Please see the :ref:`Communications Hardware<hardware-main>` 300 chapter for a guide. If you prefer purchasing a ready-made unit, you can refer to the 301 :ref:`list of suppliers<rnode-suppliers>`. For more information on RNode, you can also 302 refer to these additional external resources: 303 304 * `How To Make Your Own RNodes <https://unsigned.io/how-to-make-your-own-rnodes/>`_ 305 * `Installing RNode Firmware on Compatible LoRa Devices <https://unsigned.io/installing-rnode-firmware-on-supported-devices/>`_ 306 * `Private, Secure and Uncensorable Messaging Over a LoRa Mesh <https://unsigned.io/private-messaging-over-lora/>`_ 307 * `RNode Firmware <https://github.com/markqvist/RNode_Firmware/>`_ 308 309 If you have communications hardware that is not already supported by any of the 310 :ref:`existing interface types<interfaces-main>`, but you think would be suitable for use with Reticulum, 311 you are welcome to head over to the `GitHub discussion pages <https://github.com/markqvist/Reticulum/discussions>`_ 312 and propose adding an interface for the hardware. 313 314 315 Creating and Using Custom Interfaces 316 =========================================== 317 318 While Reticulum includes a flexible and broad range of built-in interfaces, these 319 will not cover every conceivable type of communications hardware that Reticulum 320 can potentially use to communicate. 321 322 It is therefore possible to easily write your own interface modules, that can be 323 loaded at run-time and used on-par with any of the built-in interface types. 324 325 For more information on this subject, and code examples to build on, please see 326 the :ref:`Configuring Interfaces<interfaces-main>` chapter. 327 328 329 Develop a Program with Reticulum 330 =========================================== 331 If you want to develop programs that use Reticulum, the easiest way to get 332 started is to install the latest release of Reticulum via pip: 333 334 .. code:: 335 336 pip install rns 337 338 The above command will install Reticulum and dependencies, and you will be 339 ready to import and use RNS in your own programs. The next step will most 340 likely be to look at some :ref:`Example Programs<examples-main>`. 341 342 The entire Reticulum API is documented in the :ref:`API Reference<api-main>` 343 chapter of this manual. 344 345 346 Participate in Reticulum Development 347 ============================================== 348 If you want to participate in the development of Reticulum and associated 349 utilities, you'll want to get the latest source from GitHub. In that case, 350 don't use pip, but try this recipe: 351 352 .. code:: 353 354 # Install dependencies 355 pip install cryptography pyserial 356 357 # Clone repository 358 git clone https://github.com/markqvist/Reticulum.git 359 360 # Move into Reticulum folder and symlink library to examples folder 361 cd Reticulum 362 ln -s ../RNS ./Examples/ 363 364 # Run an example 365 python Examples/Echo.py -s 366 367 # Unless you've manually created a config file, Reticulum will do so now, 368 # and immediately exit. Make any necessary changes to the file: 369 nano ~/.reticulum/config 370 371 # ... and launch the example again. 372 python Examples/Echo.py -s 373 374 # You can now repeat the process on another computer, 375 # and run the same example with -h to get command line options. 376 python Examples/Echo.py -h 377 378 # Run the example in client mode to "ping" the server. 379 # Replace the hash below with the actual destination hash of your server. 380 python Examples/Echo.py 174a64852a75682259ad8b921b8bf416 381 382 # Have a look at another example 383 python Examples/Filetransfer.py -h 384 385 When you have experimented with the basic examples, it's time to go read the 386 :ref:`Understanding Reticulum<understanding-main>` chapter. Before submitting 387 your first pull request, it is probably a good idea to introduce yourself on 388 the `disucssion forum on GitHub <https://github.com/markqvist/Reticulum/discussions>`_, 389 or ask one of the developers or maintainers for a good place to start. 390 391 .. _install-guides: 392 393 Platform-Specific Install Notes 394 ============================================== 395 396 Some platforms require a slightly different installation procedure, or have 397 various quirks that are worth being aware of. These are listed here. 398 399 Android 400 ^^^^^^^^^^^^^^^^^^^^^^^^ 401 Reticulum can be used on Android in different ways. The easiest way to get 402 started is using an app like `Sideband <https://unsigned.io/sideband>`_. 403 404 For more control and features, you can use Reticulum and related programs via 405 the `Termux app <https://termux.com/>`_, at the time of writing available on 406 `F-droid <https://f-droid.org>`_. 407 408 Termux is a terminal emulator and Linux environment for Android based devices, 409 which includes the ability to use many different programs and libraries, 410 including Reticulum. 411 412 To use Reticulum within the Termux environment, you will need to install 413 ``python`` and the ``python-cryptography`` library using ``pkg``, the package-manager 414 build into Termux. After that, you can use ``pip`` to install Reticulum. 415 416 From within Termux, execute the following: 417 418 .. code:: 419 420 # First, make sure indexes and packages are up to date. 421 pkg update 422 pkg upgrade 423 424 # Then install python and the cryptography library. 425 pkg install python python-cryptography 426 427 # Make sure pip is up to date, and install the wheel module. 428 pip install wheel pip --upgrade 429 430 # Install Reticulum 431 pip install rns 432 433 If for some reason the ``python-cryptography`` package is not available for 434 your platform via the Termux package manager, you can attempt to build it 435 locally on your device using the following command: 436 437 .. code:: 438 439 # First, make sure indexes and packages are up to date. 440 pkg update 441 pkg upgrade 442 443 # Then install dependencies for the cryptography library. 444 pkg install python build-essential openssl libffi rust 445 446 # Make sure pip is up to date, and install the wheel module. 447 pip install wheel pip --upgrade 448 449 # To allow the installer to build the cryptography module, 450 # we need to let it know what platform we are compiling for: 451 export CARGO_BUILD_TARGET="aarch64-linux-android" 452 453 # Start the install process for the cryptography module. 454 # Depending on your device, this can take several minutes, 455 # since the module must be compiled locally on your device. 456 pip install cryptography 457 458 # If the above installation succeeds, you can now install 459 # Reticulum and any related software 460 pip install rns 461 462 It is also possible to include Reticulum in apps compiled and distributed as 463 Android APKs. A detailed tutorial and example source code will be included 464 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. 465 466 467 ARM64 468 ^^^^^^^^^^^^^^^^^^^^^^^^ 469 On some architectures, including ARM64, not all dependencies have precompiled 470 binaries. On such systems, you may need to install ``python3-dev`` (or similar) before 471 installing Reticulum or programs that depend on Reticulum. 472 473 .. code:: 474 475 # Install Python and development packages 476 sudo apt update 477 sudo apt install python3 python3-pip python3-dev 478 479 # Install Reticulum 480 python3 -m pip install rns 481 482 With these packages installed, ``pip`` will be able to build any missing dependencies 483 on your system locally. 484 485 486 Debian Bookworm 487 ^^^^^^^^^^^^^^^^^^^^^^^^ 488 On versions of Debian released after April 2023, it is no longer possible by default 489 to use ``pip`` to install packages onto your system. Unfortunately, you will need to 490 use the replacement ``pipx`` command instead, which places installed packages in an 491 isolated environment. This should not negatively affect Reticulum, but will not work 492 for including and using Reticulum in your own scripts and programs. 493 494 .. code:: 495 496 # Install pipx 497 sudo apt install pipx 498 499 # Make installed programs available on the command line 500 pipx ensurepath 501 502 # Install Reticulum 503 pipx install rns 504 505 Alternatively, you can restore normal behaviour to ``pip`` by creating or editing 506 the configuration file located at ``~/.config/pip/pip.conf``, and adding the 507 following section: 508 509 .. code:: text 510 511 [global] 512 break-system-packages = true 513 514 For a one-shot installation of Reticulum, without globally enabling the ``break-system-packages`` 515 option, you can use the following command: 516 517 .. code:: text 518 519 pip install rns --break-system-packages 520 521 .. note:: 522 The ``--break-system-packages`` directive is a somewhat misleading choice 523 of words. Setting it will of course not break any system packages, but will simply 524 allow installing ``pip`` packages user- and system-wide. While this *could* in rare 525 cases lead to version conflicts, it does not generally pose any problems, especially 526 not in the case of installing Reticulum. 527 528 529 MacOS 530 ^^^^^^^^^^^^^^^^^^^^^^^^^ 531 To install Reticulum on macOS, you will need to have Python and the ``pip`` package 532 manager installed. 533 534 Systems running macOS can vary quite widely in whether or not Python is pre-installed, 535 and if it is, which version is installed, and whether the ``pip`` package manager is 536 also installed and set up. If in doubt, you can `download and install <https://www.python.org/downloads/>`_ 537 Python manually. 538 539 When Python and ``pip`` is available on your system, simply open a terminal window 540 and use one of the following commands: 541 542 .. code:: 543 544 # Install Reticulum and utilities with pip: 545 pip3 install rns 546 547 # On some versions, you may need to use the 548 # flag --break-system-packages to install: 549 pip3 install rns --break-system-packages 550 551 .. note:: 552 The ``--break-system-packages`` directive is a somewhat misleading choice 553 of words. Setting it will of course not break any system packages, but will simply 554 allow installing ``pip`` packages user- and system-wide. While this *could* in rare 555 cases lead to version conflicts, it does not generally pose any problems, especially 556 not in the case of installing Reticulum. 557 558 Additionally, some version combinations of macOS and Python require you to 559 manually add your installed ``pip`` packages directory to your `PATH` environment 560 variable, before you can use installed commands in your terminal. Usually, adding 561 the following line to your shell init script (for example ``~/.zshrc``) will be enough: 562 563 .. code:: 564 565 export PATH=$PATH:~/Library/Python/3.9/bin 566 567 Adjust Python version and shell init script location according to your system. 568 569 570 OpenWRT 571 ^^^^^^^^^^^^^^^^^^^^^^^^^ 572 On OpenWRT systems with sufficient storage and memory, you can install 573 Reticulum and related utilities using the `opkg` package manager and `pip`. 574 575 .. note:: 576 577 At the time of releasing this manual, work is underway to create pre-built 578 Reticulum packages for OpenWRT, with full configuration, service 579 and ``uci`` integration. Please see the `feed-reticulum <https://github.com/gretel/feed-reticulum>`_ 580 and `reticulum-openwrt <https://github.com/gretel/reticulum-openwrt>`_ 581 repositories for more information. 582 583 To install Reticulum on OpenWRT, first log into a command line session, and 584 then use the following instructions: 585 586 .. code:: 587 588 # Install dependencies 589 opkg install python3 python3-pip python3-cryptography python3-pyserial 590 591 # Install Reticulum 592 pip install rns 593 594 # Start rnsd with debug logging enabled 595 rnsd -vvv 596 597 .. note:: 598 599 The above instructions have been verified and tested on OpenWRT 21.02 only. 600 It is likely that other versions may require slightly altered installation 601 commands or package names. You will also need enough free space in your 602 overlay FS, and enough free RAM to actually run Reticulum and any related 603 programs and utilities. 604 605 Depending on your device configuration, you may need to adjust firewall rules 606 for Reticulum connectivity to and from your device to work. Until proper 607 packaging is ready, you will also need to manually create a service or startup 608 script to automatically laucnh Reticulum at boot time. 609 610 Please also note that the `AutoInterface` requires link-local IPv6 addresses 611 to be enabled for any Ethernet and WiFi devices you intend to use. If ``ip a`` 612 shows an address starting with ``fe80::`` for the device in question, 613 ``AutoInterface`` should work for that device. 614 615 Raspberry Pi 616 ^^^^^^^^^^^^^^^^^^^^^^^^^ 617 It is currently recommended to use a 64-bit version of the Raspberry Pi OS 618 if you want to run Reticulum on Raspberry Pi computers, since 32-bit versions 619 don't always have packages available for some dependencies. If Python and the 620 `pip` package manager is not already installed, do that first, and then 621 install Reticulum using `pip`. 622 623 .. code:: 624 625 # Install dependencies 626 sudo apt install python3 python3-pip python3-cryptography python3-pyserial 627 628 # Install Reticulum 629 pip install rns --break-system-packages 630 631 .. note:: 632 The ``--break-system-packages`` directive is a somewhat misleading choice 633 of words. Setting it will of course not break any system packages, but will simply 634 allow installing ``pip`` packages user- and system-wide. While this *could* in rare 635 cases lead to version conflicts, it does not generally pose any problems, especially 636 not in the case of installing Reticulum. 637 638 While it is possible to install and run Reticulum on 32-bit Rasperry Pi OSes, 639 it will require manually configuring and installing required build dependencies, 640 and is not detailed in this manual. 641 642 643 RISC-V 644 ^^^^^^^^^^^^^^^^^^^^^^^^ 645 On some architectures, including RISC-V, not all dependencies have precompiled 646 binaries. On such systems, you may need to install ``python3-dev`` (or similar) before 647 installing Reticulum or programs that depend on Reticulum. 648 649 .. code:: 650 651 # Install Python and development packages 652 sudo apt update 653 sudo apt install python3 python3-pip python3-dev 654 655 # Install Reticulum 656 python3 -m pip install rns 657 658 With these packages installed, ``pip`` will be able to build any missing dependencies 659 on your system locally. 660 661 662 Ubuntu Lunar 663 ^^^^^^^^^^^^^^^^^^^^^^^^ 664 On versions of Ubuntu released after April 2023, it is no longer possible by default 665 to use ``pip`` to install packages onto your system. Unfortunately, you will need to 666 use the replacement ``pipx`` command instead, which places installed packages in an 667 isolated environment. This should not negatively affect Reticulum, but will not work 668 for including and using Reticulum in your own scripts and programs. 669 670 .. code:: 671 672 # Install pipx 673 sudo apt install pipx 674 675 # Make installed programs available on the command line 676 pipx ensurepath 677 678 # Install Reticulum 679 pipx install rns 680 681 Alternatively, you can restore normal behaviour to ``pip`` by creating or editing 682 the configuration file located at ``~/.config/pip/pip.conf``, and adding the 683 following section: 684 685 .. code:: text 686 687 [global] 688 break-system-packages = true 689 690 For a one-shot installation of Reticulum, without globally enabling the ``break-system-packages`` 691 option, you can use the following command: 692 693 .. code:: text 694 695 pip install rns --break-system-packages 696 697 .. note:: 698 The ``--break-system-packages`` directive is a somewhat misleading choice 699 of words. Setting it will of course not break any system packages, but will simply 700 allow installing ``pip`` packages user- and system-wide. While this *could* in rare 701 cases lead to version conflicts, it does not generally pose any problems, especially 702 not in the case of installing Reticulum. 703 704 Windows 705 ^^^^^^^^^^^^^^^^^^^^^^^^^ 706 On Windows operating systems, the easiest way to install Reticulum is by using the 707 ``pip`` package manager from the command line (either the command prompt or Windows 708 Powershell). 709 710 If you don't already have Python installed, `download and install Python <https://www.python.org/downloads/>`_. 711 At the time of publication of this manual, the recommended version is `Python 3.12.7 <https://www.python.org/downloads/release/python-3127>`_. 712 713 **Important!** When asked by the installer, make sure to add the Python program to 714 your PATH environment variables. If you don't do this, you will not be able to 715 use the ``pip`` installer, or run the included Reticulum utility programs (such as 716 ``rnsd`` and ``rnstatus``) from the command line. 717 718 After installing Python, open the command prompt or Windows Powershell, and type: 719 720 .. code:: 721 722 pip install rns 723 724 You can now use Reticulum and all included utility programs directly from your 725 preferred command line interface. 726 727 Pure-Python Reticulum 728 ============================================== 729 730 .. warning:: 731 If you use the ``rnspure`` package to run Reticulum on systems that 732 do not support `PyCA/cryptography <https://github.com/pyca/cryptography>`_, it is 733 important that you read and understand the :ref:`Cryptographic Primitives <understanding-primitives>` 734 section of this manual. 735 736 In some rare cases, and on more obscure system types, it is not possible to 737 install one or more dependencies. In such situations, 738 you can use the ``rnspure`` package instead of the ``rns`` package, or use ``pip`` 739 with the ``--no-dependencies`` command-line option. The ``rnspure`` 740 package requires no external dependencies for installation. Please note that the 741 actual contents of the ``rns`` and ``rnspure`` packages are *completely identical*. 742 The only difference is that the ``rnspure`` package lists no dependencies required 743 for installation. 744 745 No matter how Reticulum is installed and started, it will load external dependencies 746 only if they are *needed* and *available*. If for example you want to use Reticulum 747 on a system that cannot support ``pyserial``, it is perfectly possible to do so using 748 the `rnspure` package, but Reticulum will not be able to use serial-based interfaces. 749 All other available modules will still be loaded when needed.