mirror of
https://github.com/markqvist/Reticulum.git
synced 2026-06-08 14:11:53 -07:00
Improved markdown formatting of gettingstartedfast chapter
This commit is contained in:
Mark Qvist
@@ -4,18 +4,14 @@
|
||||
Code Examples
|
||||
*************
|
||||
|
||||
A number of examples are included in the source distribution of Reticulum.
|
||||
You can use these examples to learn how to write your own programs.
|
||||
A number of examples are included in the source distribution of Reticulum. You can use these examples to learn how to write your own programs.
|
||||
|
||||
.. _example-minimal:
|
||||
|
||||
Minimal
|
||||
=======
|
||||
|
||||
The *Minimal* example demonstrates the bare-minimum setup required to connect to
|
||||
a Reticulum network from your program. In about five lines of code, you will
|
||||
have the Reticulum Network Stack initialised, and ready to pass traffic in your
|
||||
program.
|
||||
The *Minimal* example demonstrates the bare-minimum setup required to connect to a Reticulum network from your program. In about five lines of code, you will have the Reticulum Network Stack initialised, and ready to pass traffic in your program.
|
||||
|
||||
.. literalinclude:: ../../Examples/Minimal.py
|
||||
|
||||
@@ -26,9 +22,7 @@ This example can also be found at `<https://github.com/markqvist/Reticulum/blob/
|
||||
Announce
|
||||
========
|
||||
|
||||
The *Announce* example builds upon the previous example by exploring how to
|
||||
announce a destination on the network, and how to let your program receive
|
||||
notifications about announces from relevant destinations.
|
||||
The *Announce* example builds upon the previous example by exploring how to announce a destination on the network, and how to let your program receive notifications about announces from relevant destinations.
|
||||
|
||||
.. literalinclude:: ../../Examples/Announce.py
|
||||
|
||||
@@ -38,8 +32,7 @@ This example can also be found at `<https://github.com/markqvist/Reticulum/blob/
|
||||
|
||||
Broadcast
|
||||
=========
|
||||
The *Broadcast* example explores how to transmit plaintext broadcast messages
|
||||
over the network.
|
||||
The *Broadcast* example explores how to transmit plaintext broadcast messages over the network.
|
||||
|
||||
.. literalinclude:: ../../Examples/Broadcast.py
|
||||
|
||||
@@ -50,8 +43,7 @@ This example can also be found at `<https://github.com/markqvist/Reticulum/blob/
|
||||
Echo
|
||||
====
|
||||
|
||||
The *Echo* example demonstrates communication between two destinations using
|
||||
the Packet interface.
|
||||
The *Echo* example demonstrates communication between two destinations using the Packet interface.
|
||||
|
||||
.. literalinclude:: ../../Examples/Echo.py
|
||||
|
||||
@@ -62,8 +54,7 @@ This example can also be found at `<https://github.com/markqvist/Reticulum/blob/
|
||||
Link
|
||||
====
|
||||
|
||||
The *Link* example explores establishing an encrypted link to a remote
|
||||
destination, and passing traffic back and forth over the link.
|
||||
The *Link* example explores establishing an encrypted link to a remote destination, and passing traffic back and forth over the link.
|
||||
|
||||
.. literalinclude:: ../../Examples/Link.py
|
||||
|
||||
@@ -74,8 +65,7 @@ This example can also be found at `<https://github.com/markqvist/Reticulum/blob/
|
||||
Identification
|
||||
==============
|
||||
|
||||
The *Identify* example explores identifying an intiator of a link, once
|
||||
the link has been established.
|
||||
The *Identify* example explores identifying an intiator of a link, once the link has been established.
|
||||
|
||||
.. literalinclude:: ../../Examples/Identify.py
|
||||
|
||||
@@ -97,8 +87,7 @@ This example can also be found at `<https://github.com/markqvist/Reticulum/blob/
|
||||
Channel
|
||||
=======
|
||||
|
||||
The *Channel* example explores using a ``Channel`` to send structured
|
||||
data between peers of a ``Link``.
|
||||
The *Channel* example explores using a ``Channel`` to send structured data between peers of a ``Link``.
|
||||
|
||||
.. literalinclude:: ../../Examples/Channel.py
|
||||
|
||||
@@ -107,8 +96,7 @@ This example can also be found at `<https://github.com/markqvist/Reticulum/blob/
|
||||
Buffer
|
||||
======
|
||||
|
||||
The *Buffer* example explores using buffered readers and writers to send
|
||||
binary data between peers of a ``Link``.
|
||||
The *Buffer* example explores using buffered readers and writers to send binary data between peers of a ``Link``.
|
||||
|
||||
.. literalinclude:: ../../Examples/Buffer.py
|
||||
|
||||
@@ -119,9 +107,7 @@ This example can also be found at `<https://github.com/markqvist/Reticulum/blob/
|
||||
Filetransfer
|
||||
============
|
||||
|
||||
The *Filetransfer* example implements a basic file-server program that
|
||||
allow clients to connect and download files. The program uses the Resource
|
||||
interface to efficiently pass files of any size over a Reticulum :ref:`Link<api-link>`.
|
||||
The *Filetransfer* example implements a basic file-server program that allow clients to connect and download files. The program uses the Resource interface to efficiently pass files of any size over a Reticulum :ref:`Link<api-link>`.
|
||||
|
||||
.. literalinclude:: ../../Examples/Filetransfer.py
|
||||
|
||||
@@ -132,10 +118,7 @@ This example can also be found at `<https://github.com/markqvist/Reticulum/blob/
|
||||
Custom Interfaces
|
||||
=================
|
||||
|
||||
The *ExampleInterface* demonstrates creating custom interfaces for Reticulum.
|
||||
Any number of custom interfaces can be loaded and utilised by Reticulum, and
|
||||
will be fully on-par with natively included interfaces, including all supported
|
||||
:ref:`interface modes<interfaces-modes>` and :ref:`common configuration options<interfaces-options>`.
|
||||
The *ExampleInterface* demonstrates creating custom interfaces for Reticulum. Any number of custom interfaces can be loaded and utilised by Reticulum, and will be fully on-par with natively included interfaces, including all supported :ref:`interface modes<interfaces-modes>` and :ref:`common configuration options<interfaces-options>`.
|
||||
|
||||
.. literalinclude:: ../../Examples/ExampleInterface.py
|
||||
|
||||
|
||||
@@ -2,51 +2,38 @@
|
||||
Getting Started Fast
|
||||
********************
|
||||
|
||||
The best way to get started with the Reticulum Network Stack depends on what
|
||||
you want to do. This guide will outline sensible starting paths for different
|
||||
scenarios.
|
||||
The best way to get started with the Reticulum Network Stack depends on what you want to do. This guide will outline sensible starting paths for different scenarios.
|
||||
|
||||
|
||||
Standalone Reticulum Installation
|
||||
=================================
|
||||
If you simply want to install Reticulum and related utilities on a system,
|
||||
the easiest way is via the ``pip`` package manager:
|
||||
If you simply want to install Reticulum and related utilities on a system, the easiest way is via the ``pip`` package manager:
|
||||
|
||||
.. code:: shell
|
||||
|
||||
pip install rns
|
||||
|
||||
If you do not already have pip installed, you can install it using the package manager
|
||||
of your system with a command like ``sudo apt install python3-pip``,
|
||||
``sudo pamac install python-pip`` or similar.
|
||||
If you do not already have pip installed, you can install it using the package manager of your system with a command like ``sudo apt install python3-pip``, ``sudo pamac install python-pip`` or similar.
|
||||
|
||||
You can also dowload the Reticulum release wheels from GitHub, or other release channels,
|
||||
and install them offline using ``pip``:
|
||||
You can also dowload the Reticulum release wheels from GitHub, or other release channels, and install them offline using ``pip``:
|
||||
|
||||
.. code:: shell
|
||||
|
||||
pip install ./rns-1.1.2-py3-none-any.whl
|
||||
|
||||
On platforms that limit user package installation via ``pip``, you may need to manually
|
||||
allow this using the ``--break-system-packages`` command line flag when installing. This
|
||||
will not actually break any packages, unless you have installed Reticulum directly via
|
||||
your operating system's package manager.
|
||||
On platforms that limit user package installation via ``pip``, you may need to manually allow this using the ``--break-system-packages`` command line flag when installing. This will not actually break any packages, unless you have installed Reticulum directly via your operating system's package manager.
|
||||
|
||||
.. code:: shell
|
||||
|
||||
pip install rns --break-system-packages
|
||||
|
||||
For more detailed installation instructions, please see the
|
||||
:ref:`Platform-Specific Install Notes<install-guides>` section.
|
||||
For more detailed installation instructions, please see the :ref:`Platform-Specific Install Notes<install-guides>` section.
|
||||
|
||||
After installation is complete, it might be helpful to refer to the
|
||||
:ref:`Using Reticulum on Your System<using-main>` chapter.
|
||||
After installation is complete, it might be helpful to refer to the :ref:`Using Reticulum on Your System<using-main>` chapter.
|
||||
|
||||
Resolving Dependency & Installation Issues
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
On some platforms, there may not be binary packages available for all dependencies, and
|
||||
``pip`` installation may fail with an error message. In these cases, the issue can usually
|
||||
be resolved by installing the development essentials packages for your platform:
|
||||
On some platforms, there may not be binary packages available for all dependencies, and ``pip`` installation may fail with an error message. In these cases, the issue can usually be resolved by installing the development essentials packages for your platform:
|
||||
|
||||
.. code:: shell
|
||||
|
||||
@@ -59,69 +46,38 @@ be resolved by installing the development essentials packages for your platform:
|
||||
# Fedora
|
||||
sudo dnf groupinstall "Development Tools" "Development Libraries"
|
||||
|
||||
With the base development packages installed, ``pip`` should be able to compile any missing
|
||||
dependencies from source, and complete installation even on platforms that don't have pre-
|
||||
compiled packages available.
|
||||
With the base development packages installed, ``pip`` should be able to compile any missing dependencies from source, and complete installation even on platforms that don't have pre-compiled packages available.
|
||||
|
||||
Try Using a Reticulum-based Program
|
||||
=============================================
|
||||
===================================
|
||||
|
||||
If you simply want to try using a program built with Reticulum, a :ref:`range of different
|
||||
programs <software-main>` exist that allow basic communication and a various other useful functions,
|
||||
even over extremely low-bandwidth Reticulum networks.
|
||||
If you simply want to try using a program built with Reticulum, a :ref:`range of different programs <software-main>` exist that allow basic communication and a various other useful functions, even over extremely low-bandwidth Reticulum networks.
|
||||
|
||||
|
||||
Using the Included Utilities
|
||||
=============================================
|
||||
Reticulum comes with a range of included utilities that make it easier to
|
||||
manage your network, check connectivity and make Reticulum available to other
|
||||
programs on your system.
|
||||
============================
|
||||
Reticulum comes with a range of included utilities that make it easier to manage your network, check connectivity and make Reticulum available to other programs on your system.
|
||||
|
||||
You can use ``rnsd`` to run Reticulum as a background or foreground service,
|
||||
and the ``rnstatus``, ``rnpath`` and ``rnprobe`` utilities to view and query
|
||||
network status and connectivity.
|
||||
You can use ``rnsd`` to run Reticulum as a background or foreground service, and the ``rnstatus``, ``rnpath`` and ``rnprobe`` utilities to view and query network status and connectivity.
|
||||
|
||||
To learn more about these utility programs, have a look at the
|
||||
:ref:`Using Reticulum on Your System<using-main>` chapter of this manual.
|
||||
To learn more about these utility programs, have a look at the :ref:`Using Reticulum on Your System<using-main>` chapter of this manual.
|
||||
|
||||
|
||||
Creating a Network With Reticulum
|
||||
=============================================
|
||||
To create a network, you will need to specify one or more *interfaces* for
|
||||
Reticulum to use. This is done in the Reticulum configuration file, which by
|
||||
default is located at ``~/.reticulum/config``. You can get an example
|
||||
configuration file with all options via ``rnsd --exampleconfig``.
|
||||
=================================
|
||||
To create a network, you will need to specify one or more *interfaces* for Reticulum to use. This is done in the Reticulum configuration file, which by default is located at ``~/.reticulum/config``. You can get an example configuration file with all options via ``rnsd --exampleconfig``.
|
||||
|
||||
When Reticulum is started for the first time, it will create a default
|
||||
configuration file, with one active interface. This default interface uses
|
||||
your existing Ethernet and WiFi networks (if any), and only allows you to
|
||||
communicate with other Reticulum peers within your local broadcast domains.
|
||||
When Reticulum is started for the first time, it will create a default configuration file, with one active interface. This default interface uses your existing Ethernet and WiFi networks (if any), and only allows you to communicate with other Reticulum peers within your local broadcast domains.
|
||||
|
||||
To communicate further, you will have to add one or more interfaces. The default
|
||||
configuration includes a number of examples, ranging from using TCP over the
|
||||
internet, to LoRa and Packet Radio interfaces.
|
||||
To communicate further, you will have to add one or more interfaces. The default configuration includes a number of examples, ranging from using TCP over the internet, to LoRa and Packet Radio interfaces.
|
||||
|
||||
With Reticulum, you only need to configure what interfaces you want to communicate
|
||||
over. There is no need to configure address spaces, subnets, routing tables,
|
||||
or other things you might be used to from other network types.
|
||||
With Reticulum, you only need to configure what interfaces you want to communicate over. There is no need to configure address spaces, subnets, routing tables, or other things you might be used to from other network types.
|
||||
|
||||
Once Reticulum knows which interfaces it should use, it will automatically
|
||||
discover topography and configure transport of data to any destinations it
|
||||
knows about.
|
||||
Once Reticulum knows which interfaces it should use, it will automatically discover topography and configure transport of data to any destinations it knows about.
|
||||
|
||||
In situations where you already have an established WiFi or Ethernet network, and
|
||||
many devices that want to utilise the same external Reticulum network paths (for example over
|
||||
LoRa), it will often be sufficient to let one system act as a Reticulum gateway, by
|
||||
adding any external interfaces to the configuration of this system, and then enabling transport on it. Any
|
||||
other device on your local WiFi will then be able to connect to this wider Reticulum
|
||||
network just using the default (:ref:`AutoInterface<interfaces-auto>`) configuration.
|
||||
In situations where you already have an established WiFi or Ethernet network, and many devices that want to utilise the same external Reticulum network paths (for example over LoRa), it will often be sufficient to let one system act as a Reticulum gateway, by adding any external interfaces to the configuration of this system, and then enabling transport on it. Any other device on your local WiFi will then be able to connect to this wider Reticulum network just using the default (:ref:`AutoInterface<interfaces-auto>`) configuration.
|
||||
|
||||
Possibly, the examples in the config file are enough to get you started. If
|
||||
you want more information, you can read the :ref:`Building Networks<networks-main>`
|
||||
and :ref:`Interfaces<interfaces-main>` chapters of this manual, but most importantly,
|
||||
start with reading the next section, :ref:`Bootstrapping Connectivity<bootstrapping-connectivity>`,
|
||||
as this provides the most essential understanding of how to ensure reliable
|
||||
connectivity with a minimum of maintenance.
|
||||
Possibly, the examples in the config file are enough to get you started. If you want more information, you can read the :ref:`Building Networks<networks-main>` and :ref:`Interfaces<interfaces-main>` chapters of this manual, but most importantly, start with reading the next section, :ref:`Bootstrapping Connectivity<bootstrapping-connectivity>`, as this provides the most essential understanding of how to ensure reliable connectivity with a minimum of maintenance.
|
||||
|
||||
|
||||
.. _bootstrapping-connectivity:
|
||||
@@ -216,20 +172,13 @@ As a good starting point, you can find interface definitions for connecting your
|
||||
Hosting Public Entrypoints
|
||||
==========================
|
||||
|
||||
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
|
||||
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>`.
|
||||
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 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>`.
|
||||
|
||||
You will need a machine, physical or virtual with a public IP address, that can be reached by other devices on the Internet.
|
||||
|
||||
The most efficient and performant way to host a connectable entry-point supporting many
|
||||
users is to use the ``BackboneInterface``. This interface type is fully compatible with
|
||||
the ``TCPClientInterface`` and ``TCPServerInterface`` types, but much faster and uses
|
||||
less system resources, allowing your device to handle thousands of connections even on
|
||||
small systems.
|
||||
The most efficient and performant way to host a connectable entry-point supporting many users is to use the ``BackboneInterface``. This interface type is fully compatible with the ``TCPClientInterface`` and ``TCPServerInterface`` types, but much faster and uses less system resources, allowing your device to handle thousands of connections even on small systems.
|
||||
|
||||
It is also important to set your connectable interface to ``gateway`` mode, since this
|
||||
will greatly improve network convergence time and path resolution for anyone connecting
|
||||
to your entry-point.
|
||||
It is also important to set your connectable interface to ``gateway`` mode, since this will greatly improve network convergence time and path resolution for anyone connecting to your entry-point.
|
||||
|
||||
.. code:: ini
|
||||
|
||||
@@ -251,8 +200,7 @@ to your entry-point.
|
||||
announce_rate_penalty = 3600
|
||||
announce_rate_grace = 6
|
||||
|
||||
If instead you want to make a private entry-point from the Internet, you can use the
|
||||
:ref:`IFAC name and passphrase options<interfaces-options>` to secure your interface with a network name and passphrase.
|
||||
If instead you want to make a private entry-point from the Internet, you can use the :ref:`IFAC name and passphrase options<interfaces-options>` to secure your interface with a network name and passphrase.
|
||||
|
||||
.. code:: ini
|
||||
|
||||
@@ -268,132 +216,79 @@ If instead you want to make a private entry-point from the Internet, you can use
|
||||
network_name = private_ret
|
||||
passphrase = 2owjajquafIanPecAc
|
||||
|
||||
If you are hosting an entry-point on an operating system that does not support
|
||||
``BackboneInterface``, you can use ``TCPServerInterface`` instead, although it will
|
||||
not be as performant.
|
||||
If you are hosting an entry-point on an operating system that does not support ``BackboneInterface``, you can use ``TCPServerInterface`` instead, although it will not be as performant.
|
||||
|
||||
|
||||
Connecting Reticulum Instances Over the Internet
|
||||
================================================
|
||||
Reticulum currently offers three interfaces suitable for connecting instances over the Internet: :ref:`Backbone<interfaces-backbone>`, :ref:`TCP<interfaces-tcps>`
|
||||
and :ref:`I2P<interfaces-i2p>`. Each interface offers a different set of features, and Reticulum
|
||||
users should carefully choose the interface which best suites their needs.
|
||||
Reticulum currently offers three interfaces suitable for connecting instances over the Internet: :ref:`Backbone<interfaces-backbone>`, :ref:`TCP<interfaces-tcps>` and :ref:`I2P<interfaces-i2p>`. Each interface offers a different set of features, and Reticulum users should carefully choose the interface which best suites their needs.
|
||||
|
||||
The ``TCPServerInterface`` allows users to host an instance accessible over TCP/IP. This
|
||||
method is generally faster, lower latency, and more energy efficient than using ``I2PInterface``,
|
||||
however it also leaks more data about the server host.
|
||||
The ``TCPServerInterface`` allows users to host an instance accessible over TCP/IP. This method is generally faster, lower latency, and more energy efficient than using ``I2PInterface``, however it also leaks more data about the server host.
|
||||
|
||||
The ``BackboneInterface`` is a very fast and efficient interface type available on POSIX operating
|
||||
systems, designed to handle thousands of connections simultaneously with low memory, processing
|
||||
and I/O overhead. It is fully compatible with the TCP-based interface types.
|
||||
The ``BackboneInterface`` is a very fast and efficient interface type available on POSIX operating systems, designed to handle thousands of connections simultaneously with low memory, processing and I/O overhead. It is fully compatible with the TCP-based interface types.
|
||||
|
||||
TCP connections reveal the IP address of both your instance and the server to anyone who can
|
||||
inspect the connection. Someone could use this information to determine your location or identity. Adversaries
|
||||
inspecting your packets may be able to record packet metadata like time of transmission and packet size.
|
||||
Even though Reticulum encrypts traffic, TCP does not, so an adversary may be able to use
|
||||
packet inspection to learn that a system is running Reticulum, and what other IP addresses connect to it.
|
||||
Hosting a publicly reachable instance over TCP also requires a publicly reachable IP address,
|
||||
which most Internet connections don't offer anymore.
|
||||
TCP connections reveal the IP address of both your instance and the server to anyone who can inspect the connection. Someone could use this information to determine your location or identity. Adversaries inspecting your packets may be able to record packet metadata like time of transmission and packet size. Even though Reticulum encrypts traffic, TCP does not, so an adversary may be able to use packet inspection to learn that a system is running Reticulum, and what other IP addresses connect to it. Hosting a publicly reachable instance over TCP also requires a publicly reachable IP address, which most Internet connections don't offer anymore.
|
||||
|
||||
The ``I2PInterface`` routes messages through the `Invisible Internet Protocol
|
||||
(I2P) <https://geti2p.net/en/>`_. To use this interface, users must also run an I2P daemon in
|
||||
parallel to ``rnsd``. For always-on I2P nodes it is recommended to use `i2pd <https://i2pd.website/>`_.
|
||||
The ``I2PInterface`` routes messages through the `Invisible Internet Protocol (I2P) <https://geti2p.net/en/>`_. To use this interface, users must also run an I2P daemon in parallel to ``rnsd``. For always-on I2P nodes it is recommended to use `i2pd <https://i2pd.website/>`_.
|
||||
|
||||
By default, I2P will encrypt and mix all traffic sent over the Internet, and
|
||||
hide both the sender and receiver Reticulum instance IP addresses. Running an I2P node
|
||||
will also relay other I2P user's encrypted packets, which will use extra
|
||||
bandwidth and compute power, but also makes timing attacks and other forms of
|
||||
deep-packet-inspection much more difficult.
|
||||
By default, I2P will encrypt and mix all traffic sent over the Internet, and hide both the sender and receiver Reticulum instance IP addresses. Running an I2P node will also relay other I2P user's encrypted packets, which will use extra bandwidth and compute power, but also makes timing attacks and other forms of deep-packet-inspection much more difficult.
|
||||
|
||||
I2P also allows users to host globally available Reticulum instances from non-public IP's and behind firewalls and NAT.
|
||||
|
||||
In general it is recommended to use an I2P node if you want to host a publicly accessible
|
||||
instance, while preserving anonymity. If you care more about performance, and a slightly
|
||||
easier setup, use TCP.
|
||||
In general it is recommended to use an I2P node if you want to host a publicly accessible instance, while preserving anonymity. If you care more about performance, and a slightly easier setup, use TCP.
|
||||
|
||||
Adding Radio Interfaces
|
||||
=======================
|
||||
Once you have Reticulum installed and working, you can add radio interfaces with
|
||||
any compatible hardware you have available. Reticulum supports a wide range of radio
|
||||
hardware, and if you already have any available, it is very likely that it will
|
||||
work with Reticulum. For information on how to configure this, see the
|
||||
:ref:`Interfaces<interfaces-main>` section of this manual.
|
||||
Once you have Reticulum installed and working, you can add radio interfaces with any compatible hardware you have available. Reticulum supports a wide range of radio hardware, and if you already have any available, it is very likely that it will work with Reticulum. For information on how to configure this, see the :ref:`Interfaces<interfaces-main>` section of this manual.
|
||||
|
||||
If you do not already have transceiver hardware available, you can easily and
|
||||
cheaply build an :ref:`RNode<rnode-main>`, which is a general-purpose long-range
|
||||
digital radio transceiver, that integrates easily with Reticulum.
|
||||
If you do not already have transceiver hardware available, you can easily and cheaply build an :ref:`RNode<rnode-main>`, which is a general-purpose long-range digital radio transceiver, that integrates easily with Reticulum.
|
||||
|
||||
To build one yourself requires installing a custom firmware on a supported LoRa
|
||||
development board with an auto-install script or web-based flasher.
|
||||
Please see the :ref:`Communications Hardware<hardware-main>` chapter for a guide.
|
||||
If you prefer purchasing a ready-made unit, you can refer to the
|
||||
:ref:`list of suppliers<rnode-suppliers>`.
|
||||
To build one yourself requires installing a custom firmware on a supported LoRa development board with an auto-install script or web-based flasher. Please see the :ref:`Communications Hardware<hardware-main>` chapter for a guide. If you prefer purchasing a ready-made unit, you can refer to the :ref:`list of suppliers<rnode-suppliers>`.
|
||||
|
||||
Other radio-based hardware interfaces are being developed and made available by
|
||||
the broader Reticulum community. You can find more information on such topics
|
||||
over Reticulum-based information sharing systems.
|
||||
Other radio-based hardware interfaces are being developed and made available by the broader Reticulum community. You can find more information on such topics over Reticulum-based information sharing systems.
|
||||
|
||||
If you have communications hardware that is not already supported by any of the
|
||||
:ref:`existing interface types<interfaces-main>`, it is easy to write (and potentially
|
||||
publish) a :ref:`custom interface module<interfaces-custom>` that makes it compatible with Reticulum.
|
||||
If you have communications hardware that is not already supported by any of the :ref:`existing interface types<interfaces-main>`, it is easy to write (and potentially publish) a :ref:`custom interface module<interfaces-custom>` that makes it compatible with Reticulum.
|
||||
|
||||
|
||||
Creating and Using Custom Interfaces
|
||||
====================================
|
||||
|
||||
While Reticulum includes a flexible and broad range of built-in interfaces, these
|
||||
will not cover every conceivable type of communications hardware that Reticulum
|
||||
can potentially use to communicate.
|
||||
While Reticulum includes a flexible and broad range of built-in interfaces, these will not cover every conceivable type of communications hardware that Reticulum can potentially use to communicate.
|
||||
|
||||
It is therefore possible to easily write your own interface modules, that can be
|
||||
loaded at run-time and used on-par with any of the built-in interface types.
|
||||
It is therefore possible to easily write your own interface modules, that can be loaded at run-time and used on-par with any of the built-in interface types.
|
||||
|
||||
For more information on this subject, and code examples to build on, please see
|
||||
the :ref:`Configuring Interfaces<interfaces-main>` chapter.
|
||||
For more information on this subject, and code examples to build on, please see the :ref:`Configuring Interfaces<interfaces-main>` chapter.
|
||||
|
||||
|
||||
Develop a Program with Reticulum
|
||||
===========================================
|
||||
If you want to develop programs that use Reticulum, the easiest way to get
|
||||
started is to install the latest release of Reticulum via pip:
|
||||
================================
|
||||
If you want to develop programs that use Reticulum, the easiest way to get started is to install the latest release of Reticulum via pip:
|
||||
|
||||
.. code::
|
||||
|
||||
pip install rns
|
||||
|
||||
The above command will install Reticulum and dependencies, and you will be
|
||||
ready to import and use RNS in your own programs. The next step will most
|
||||
likely be to look at some :ref:`Example Programs<examples-main>`.
|
||||
The above command will install Reticulum and dependencies, and you will be ready to import and use RNS in your own programs. The next step will most likely be to look at some :ref:`Example Programs<examples-main>`.
|
||||
|
||||
The entire Reticulum API is documented in the :ref:`API Reference<api-main>`
|
||||
chapter of this manual. Before diving in, it's probably a good idea to read
|
||||
this manual in full, but at least start with the :ref:`Understanding Reticulum<understanding-main>` chapter.
|
||||
The entire Reticulum API is documented in the :ref:`API Reference<api-main>` chapter of this manual. Before diving in, it's probably a good idea to read this manual in full, but at least start with the :ref:`Understanding Reticulum<understanding-main>` chapter.
|
||||
|
||||
|
||||
.. _install-guides:
|
||||
|
||||
Platform-Specific Install Notes
|
||||
==============================================
|
||||
===============================
|
||||
|
||||
Some platforms require a slightly different installation procedure, or have
|
||||
various quirks that are worth being aware of. These are listed here.
|
||||
Some platforms require a slightly different installation procedure, or have various quirks that are worth being aware of. These are listed here.
|
||||
|
||||
Android
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
Reticulum can be used on Android in different ways. The easiest way to get
|
||||
started is using an app like `Sideband <https://unsigned.io/sideband>`_.
|
||||
^^^^^^^
|
||||
Reticulum can be used on Android in different ways. The easiest way to get started is using an app like `Sideband <https://unsigned.io/sideband>`_.
|
||||
|
||||
For more control and features, you can use Reticulum and related programs via
|
||||
the `Termux app <https://termux.com/>`_, at the time of writing available on
|
||||
`F-droid <https://f-droid.org>`_.
|
||||
For more control and features, you can use Reticulum and related programs via the `Termux app <https://termux.com/>`_, at the time of writing available on `F-droid <https://f-droid.org>`_.
|
||||
|
||||
Termux is a terminal emulator and Linux environment for Android based devices,
|
||||
which includes the ability to use many different programs and libraries,
|
||||
including Reticulum.
|
||||
Termux is a terminal emulator and Linux environment for Android based devices, which includes the ability to use many different programs and libraries, including Reticulum.
|
||||
|
||||
To use Reticulum within the Termux environment, you will need to install
|
||||
``python`` and the ``python-cryptography`` library using ``pkg``, the package-manager
|
||||
build into Termux. After that, you can use ``pip`` to install Reticulum.
|
||||
To use Reticulum within the Termux environment, you will need to install ``python`` and the ``python-cryptography`` library using ``pkg``, the package-manager build into Termux. After that, you can use ``pip`` to install Reticulum.
|
||||
|
||||
From within Termux, execute the following:
|
||||
|
||||
@@ -412,9 +307,7 @@ From within Termux, execute the following:
|
||||
# Install Reticulum
|
||||
pip install rns
|
||||
|
||||
If for some reason the ``python-cryptography`` package is not available for
|
||||
your platform via the Termux package manager, you can attempt to build it
|
||||
locally on your device using the following command:
|
||||
If for some reason the ``python-cryptography`` package is not available for your platform via the Termux package manager, you can attempt to build it locally on your device using the following command:
|
||||
|
||||
.. code:: shell
|
||||
|
||||
@@ -441,16 +334,12 @@ locally on your device using the following command:
|
||||
# Reticulum and any related software
|
||||
pip install rns
|
||||
|
||||
It is also possible to include Reticulum in apps compiled and distributed as
|
||||
Android APKs. A detailed tutorial and example source code will be included
|
||||
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.
|
||||
It is also possible to include Reticulum in apps compiled and distributed as Android APKs. A detailed tutorial and example source code will be included 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.
|
||||
|
||||
|
||||
ARM64
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
On some architectures, including ARM64, not all dependencies have precompiled
|
||||
binaries. On such systems, you may need to install ``python3-dev`` (or similar) before
|
||||
installing Reticulum or programs that depend on Reticulum.
|
||||
^^^^^
|
||||
On some architectures, including ARM64, not all dependencies have precompiled binaries. On such systems, you may need to install ``python3-dev`` (or similar) before installing Reticulum or programs that depend on Reticulum.
|
||||
|
||||
.. code:: shell
|
||||
|
||||
@@ -466,12 +355,8 @@ on your system locally.
|
||||
|
||||
|
||||
Debian Bookworm
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
On versions of Debian released after April 2023, it is no longer possible by default
|
||||
to use ``pip`` to install packages onto your system. Unfortunately, you will need to
|
||||
use the replacement ``pipx`` command instead, which places installed packages in an
|
||||
isolated environment. This should not negatively affect Reticulum, but will not work
|
||||
for including and using Reticulum in your own scripts and programs.
|
||||
^^^^^^^^^^^^^^^
|
||||
On versions of Debian released after April 2023, it is no longer possible by default to use ``pip`` to install packages onto your system. Unfortunately, you will need to use the replacement ``pipx`` command instead, which places installed packages in an isolated environment. This should not negatively affect Reticulum, but will not work for including and using Reticulum in your own scripts and programs.
|
||||
|
||||
.. code:: shell
|
||||
|
||||
@@ -484,17 +369,14 @@ for including and using Reticulum in your own scripts and programs.
|
||||
# Install Reticulum
|
||||
pipx install rns
|
||||
|
||||
Alternatively, you can restore normal behaviour to ``pip`` by creating or editing
|
||||
the configuration file located at ``~/.config/pip/pip.conf``, and adding the
|
||||
following section:
|
||||
Alternatively, you can restore normal behaviour to ``pip`` by creating or editing the configuration file located at ``~/.config/pip/pip.conf``, and adding the following section:
|
||||
|
||||
.. code:: ini
|
||||
|
||||
[global]
|
||||
break-system-packages = true
|
||||
|
||||
For a one-shot installation of Reticulum, without globally enabling the ``break-system-packages``
|
||||
option, you can use the following command:
|
||||
For a one-shot installation of Reticulum, without globally enabling the ``break-system-packages`` option, you can use the following command:
|
||||
|
||||
.. code:: shell
|
||||
|
||||
@@ -509,17 +391,12 @@ option, you can use the following command:
|
||||
|
||||
|
||||
MacOS
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
To install Reticulum on macOS, you will need to have Python and the ``pip`` package
|
||||
manager installed.
|
||||
^^^^^
|
||||
To install Reticulum on macOS, you will need to have Python and the ``pip`` package manager installed.
|
||||
|
||||
Systems running macOS can vary quite widely in whether or not Python is pre-installed,
|
||||
and if it is, which version is installed, and whether the ``pip`` package manager is
|
||||
also installed and set up. If in doubt, you can `download and install <https://www.python.org/downloads/>`_
|
||||
Python manually.
|
||||
Systems running macOS can vary quite widely in whether or not Python is pre-installed, and if it is, which version is installed, and whether the ``pip`` package manager is also installed and set up. If in doubt, you can `download and install <https://www.python.org/downloads/>`_ Python manually.
|
||||
|
||||
When Python and ``pip`` is available on your system, simply open a terminal window
|
||||
and use one of the following commands:
|
||||
When Python and ``pip`` is available on your system, simply open a terminal window and use one of the following commands:
|
||||
|
||||
.. code:: shell
|
||||
|
||||
@@ -531,16 +408,9 @@ and use one of the following commands:
|
||||
pip3 install rns --break-system-packages
|
||||
|
||||
.. note::
|
||||
The ``--break-system-packages`` directive is a somewhat misleading choice
|
||||
of words. Setting it will of course not break any system packages, but will simply
|
||||
allow installing ``pip`` packages user- and system-wide. While this *could* in rare
|
||||
cases lead to version conflicts, it does not generally pose any problems, especially
|
||||
not in the case of installing Reticulum.
|
||||
The ``--break-system-packages`` directive is a somewhat misleading choice of words. Setting it will of course not break any system packages, but will simply allow installing ``pip`` packages user- and system-wide. While this *could* in rare cases lead to version conflicts, it does not generally pose any problems, especially not in the case of installing Reticulum.
|
||||
|
||||
Additionally, some version combinations of macOS and Python require you to
|
||||
manually add your installed ``pip`` packages directory to your `PATH` environment
|
||||
variable, before you can use installed commands in your terminal. Usually, adding
|
||||
the following line to your shell init script (for example ``~/.zshrc``) will be enough:
|
||||
Additionally, some version combinations of macOS and Python require you to manually add your installed ``pip`` packages directory to your `PATH` environment variable, before you can use installed commands in your terminal. Usually, adding the following line to your shell init script (for example ``~/.zshrc``) will be enough:
|
||||
|
||||
.. code:: shell
|
||||
|
||||
@@ -550,9 +420,8 @@ Adjust Python version and shell init script location according to your system.
|
||||
|
||||
|
||||
OpenWRT
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
On OpenWRT systems with sufficient storage and memory, you can install
|
||||
Reticulum and related utilities using the `opkg` package manager and `pip`.
|
||||
^^^^^^^
|
||||
On OpenWRT systems with sufficient storage and memory, you can install Reticulum and related utilities using the `opkg` package manager and `pip`.
|
||||
|
||||
.. note::
|
||||
|
||||
@@ -562,8 +431,7 @@ Reticulum and related utilities using the `opkg` package manager and `pip`.
|
||||
and `reticulum-openwrt <https://github.com/gretel/reticulum-openwrt>`_
|
||||
repositories for more information.
|
||||
|
||||
To install Reticulum on OpenWRT, first log into a command line session, and
|
||||
then use the following instructions:
|
||||
To install Reticulum on OpenWRT, first log into a command line session, and then use the following instructions:
|
||||
|
||||
.. code:: shell
|
||||
|
||||
@@ -578,29 +446,15 @@ then use the following instructions:
|
||||
|
||||
.. note::
|
||||
|
||||
The above instructions have been verified and tested on OpenWRT 21.02 only.
|
||||
It is likely that other versions may require slightly altered installation
|
||||
commands or package names. You will also need enough free space in your
|
||||
overlay FS, and enough free RAM to actually run Reticulum and any related
|
||||
programs and utilities.
|
||||
The above instructions have been verified and tested on OpenWRT 21.02 only. It is likely that other versions may require slightly altered installation commands or package names. You will also need enough free space in your overlay FS, and enough free RAM to actually run Reticulum and any related programs and utilities.
|
||||
|
||||
Depending on your device configuration, you may need to adjust firewall rules
|
||||
for Reticulum connectivity to and from your device to work. Until proper
|
||||
packaging is ready, you will also need to manually create a service or startup
|
||||
script to automatically laucnh Reticulum at boot time.
|
||||
Depending on your device configuration, you may need to adjust firewall rules for Reticulum connectivity to and from your device to work. Until proper packaging is ready, you will also need to manually create a service or startup script to automatically laucnh Reticulum at boot time.
|
||||
|
||||
Please also note that the `AutoInterface` requires link-local IPv6 addresses
|
||||
to be enabled for any Ethernet and WiFi devices you intend to use. If ``ip a``
|
||||
shows an address starting with ``fe80::`` for the device in question,
|
||||
``AutoInterface`` should work for that device.
|
||||
Please also note that the `AutoInterface` requires link-local IPv6 addresses to be enabled for any Ethernet and WiFi devices you intend to use. If ``ip a`` shows an address starting with ``fe80::`` for the device in question, ``AutoInterface`` should work for that device.
|
||||
|
||||
Raspberry Pi
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
It is currently recommended to use a 64-bit version of the Raspberry Pi OS
|
||||
if you want to run Reticulum on Raspberry Pi computers, since 32-bit versions
|
||||
don't always have packages available for some dependencies. If Python and the
|
||||
`pip` package manager is not already installed, do that first, and then
|
||||
install Reticulum using `pip`.
|
||||
^^^^^^^^^^^^
|
||||
It is currently recommended to use a 64-bit version of the Raspberry Pi OS if you want to run Reticulum on Raspberry Pi computers, since 32-bit versions don't always have packages available for some dependencies. If Python and the `pip` package manager is not already installed, do that first, and then install Reticulum using `pip`.
|
||||
|
||||
.. code:: shell
|
||||
|
||||
@@ -611,22 +465,14 @@ install Reticulum using `pip`.
|
||||
pip install rns --break-system-packages
|
||||
|
||||
.. note::
|
||||
The ``--break-system-packages`` directive is a somewhat misleading choice
|
||||
of words. Setting it will of course not break any system packages, but will simply
|
||||
allow installing ``pip`` packages user- and system-wide. While this *could* in rare
|
||||
cases lead to version conflicts, it does not generally pose any problems, especially
|
||||
not in the case of installing Reticulum.
|
||||
The ``--break-system-packages`` directive is a somewhat misleading choice of words. Setting it will of course not break any system packages, but will simply allow installing ``pip`` packages user- and system-wide. While this *could* in rare cases lead to version conflicts, it does not generally pose any problems, especially not in the case of installing Reticulum.
|
||||
|
||||
While it is possible to install and run Reticulum on 32-bit Rasperry Pi OSes,
|
||||
it will require manually configuring and installing required build dependencies,
|
||||
and is not detailed in this manual.
|
||||
While it is possible to install and run Reticulum on 32-bit Rasperry Pi OSes, it will require manually configuring and installing required build dependencies, and is not detailed in this manual.
|
||||
|
||||
|
||||
RISC-V
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
On some architectures, including RISC-V, not all dependencies have precompiled
|
||||
binaries. On such systems, you may need to install ``python3-dev`` (or similar) before
|
||||
installing Reticulum or programs that depend on Reticulum.
|
||||
^^^^^^
|
||||
On some architectures, including RISC-V, not all dependencies have precompiled binaries. On such systems, you may need to install ``python3-dev`` (or similar) before installing Reticulum or programs that depend on Reticulum.
|
||||
|
||||
.. code:: shell
|
||||
|
||||
@@ -637,17 +483,12 @@ installing Reticulum or programs that depend on Reticulum.
|
||||
# Install Reticulum
|
||||
python3 -m pip install rns
|
||||
|
||||
With these packages installed, ``pip`` will be able to build any missing dependencies
|
||||
on your system locally.
|
||||
With these packages installed, ``pip`` will be able to build any missing dependencies on your system locally.
|
||||
|
||||
|
||||
Ubuntu Lunar
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
On versions of Ubuntu released after April 2023, it is no longer possible by default
|
||||
to use ``pip`` to install packages onto your system. Unfortunately, you will need to
|
||||
use the replacement ``pipx`` command instead, which places installed packages in an
|
||||
isolated environment. This should not negatively affect Reticulum, but will not work
|
||||
for including and using Reticulum in your own scripts and programs.
|
||||
^^^^^^^^^^^^
|
||||
On versions of Ubuntu released after April 2023, it is no longer possible by default to use ``pip`` to install packages onto your system. Unfortunately, you will need to use the replacement ``pipx`` command instead, which places installed packages in an isolated environment. This should not negatively affect Reticulum, but will not work for including and using Reticulum in your own scripts and programs.
|
||||
|
||||
.. code:: shell
|
||||
|
||||
@@ -660,42 +501,29 @@ for including and using Reticulum in your own scripts and programs.
|
||||
# Install Reticulum
|
||||
pipx install rns
|
||||
|
||||
Alternatively, you can restore normal behaviour to ``pip`` by creating or editing
|
||||
the configuration file located at ``~/.config/pip/pip.conf``, and adding the
|
||||
following section:
|
||||
Alternatively, you can restore normal behaviour to ``pip`` by creating or editing the configuration file located at ``~/.config/pip/pip.conf``, and adding the following section:
|
||||
|
||||
.. code:: text
|
||||
|
||||
[global]
|
||||
break-system-packages = true
|
||||
|
||||
For a one-shot installation of Reticulum, without globally enabling the ``break-system-packages``
|
||||
option, you can use the following command:
|
||||
For a one-shot installation of Reticulum, without globally enabling the ``break-system-packages`` option, you can use the following command:
|
||||
|
||||
.. code:: text
|
||||
|
||||
pip install rns --break-system-packages
|
||||
|
||||
.. note::
|
||||
The ``--break-system-packages`` directive is a somewhat misleading choice
|
||||
of words. Setting it will of course not break any system packages, but will simply
|
||||
allow installing ``pip`` packages user- and system-wide. While this *could* in rare
|
||||
cases lead to version conflicts, it does not generally pose any problems, especially
|
||||
not in the case of installing Reticulum.
|
||||
The ``--break-system-packages`` directive is a somewhat misleading choice of words. Setting it will of course not break any system packages, but will simply allow installing ``pip`` packages user- and system-wide. While this *could* in rare cases lead to version conflicts, it does not generally pose any problems, especially not in the case of installing Reticulum.
|
||||
|
||||
Windows
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
On Windows operating systems, the easiest way to install Reticulum is by using the
|
||||
``pip`` package manager from the command line (either the command prompt or Windows
|
||||
Powershell).
|
||||
^^^^^^^
|
||||
On Windows operating systems, the easiest way to install Reticulum is by using the ``pip`` package manager from the command line (either the command prompt or Windows Powershell).
|
||||
|
||||
If you don't already have Python installed, `download and install Python <https://www.python.org/downloads/>`_.
|
||||
At the time of publication of this manual, the recommended version is `Python 3.12.7 <https://www.python.org/downloads/release/python-3127>`_.
|
||||
If you don't already have Python installed, `download and install Python <https://www.python.org/downloads/>`_. At the time of publication of this manual, the recommended version is `Python 3.12.7 <https://www.python.org/downloads/release/python-3127>`_.
|
||||
|
||||
**Important!** When asked by the installer, make sure to add the Python program to
|
||||
your PATH environment variables. If you don't do this, you will not be able to
|
||||
use the ``pip`` installer, or run the included Reticulum utility programs (such as
|
||||
``rnsd`` and ``rnstatus``) from the command line.
|
||||
**Important!** When asked by the installer, make sure to add the Python program to your PATH environment variables. If you don't do this, you will not be able to use the ``pip`` installer, or run the included Reticulum utility programs (such as ``rnsd`` and ``rnstatus``) from the command line.
|
||||
|
||||
After installing Python, open the command prompt or Windows Powershell, and type:
|
||||
|
||||
@@ -703,11 +531,10 @@ After installing Python, open the command prompt or Windows Powershell, and type
|
||||
|
||||
pip install rns
|
||||
|
||||
You can now use Reticulum and all included utility programs directly from your
|
||||
preferred command line interface.
|
||||
You can now use Reticulum and all included utility programs directly from your preferred command line interface.
|
||||
|
||||
Pure-Python Reticulum
|
||||
==============================================
|
||||
=====================
|
||||
|
||||
.. warning::
|
||||
If you use the ``rnspure`` package to run Reticulum on systems that
|
||||
@@ -715,17 +542,6 @@ Pure-Python Reticulum
|
||||
important that you read and understand the :ref:`Cryptographic Primitives <understanding-primitives>`
|
||||
section of this manual.
|
||||
|
||||
In some rare cases, and on more obscure system types, it is not possible to
|
||||
install one or more dependencies. In such situations,
|
||||
you can use the ``rnspure`` package instead of the ``rns`` package, or use ``pip``
|
||||
with the ``--no-dependencies`` command-line option. The ``rnspure``
|
||||
package requires no external dependencies for installation. Please note that the
|
||||
actual contents of the ``rns`` and ``rnspure`` packages are *completely identical*.
|
||||
The only difference is that the ``rnspure`` package lists no dependencies required
|
||||
for installation.
|
||||
In some rare cases, and on more obscure system types, it is not possible to install one or more dependencies. In such situations, you can use the ``rnspure`` package instead of the ``rns`` package, or use ``pip`` with the ``--no-dependencies`` command-line option. The ``rnspure`` package requires no external dependencies for installation. Please note that the actual contents of the ``rns`` and ``rnspure`` packages are *completely identical*. The only difference is that the ``rnspure`` package lists no dependencies required for installation.
|
||||
|
||||
No matter how Reticulum is installed and started, it will load external dependencies
|
||||
only if they are *needed* and *available*. If for example you want to use Reticulum
|
||||
on a system that cannot support ``pyserial``, it is perfectly possible to do so using
|
||||
the `rnspure` package, but Reticulum will not be able to use serial-based interfaces.
|
||||
All other available modules will still be loaded when needed.
|
||||
No matter how Reticulum is installed and started, it will load external dependencies only if they are *needed* and *available*. If for example you want to use Reticulum on a system that cannot support ``pyserial``, it is perfectly possible to do so using the `rnspure` package, but Reticulum will not be able to use serial-based interfaces. All other available modules will still be loaded when needed.
|
||||
|
||||
+11
-28
@@ -264,14 +264,10 @@
|
||||
<article role="main" id="furo-main-content">
|
||||
<section id="code-examples">
|
||||
<span id="examples-main"></span><h1>Code Examples<a class="headerlink" href="#code-examples" title="Link to this heading">¶</a></h1>
|
||||
<p>A number of examples are included in the source distribution of Reticulum.
|
||||
You can use these examples to learn how to write your own programs.</p>
|
||||
<p>A number of examples are included in the source distribution of Reticulum. You can use these examples to learn how to write your own programs.</p>
|
||||
<section id="minimal">
|
||||
<span id="example-minimal"></span><h2>Minimal<a class="headerlink" href="#minimal" title="Link to this heading">¶</a></h2>
|
||||
<p>The <em>Minimal</em> example demonstrates the bare-minimum setup required to connect to
|
||||
a Reticulum network from your program. In about five lines of code, you will
|
||||
have the Reticulum Network Stack initialised, and ready to pass traffic in your
|
||||
program.</p>
|
||||
<p>The <em>Minimal</em> example demonstrates the bare-minimum setup required to connect to a Reticulum network from your program. In about five lines of code, you will have the Reticulum Network Stack initialised, and ready to pass traffic in your program.</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1">##########################################################</span>
|
||||
<span class="c1"># This RNS example demonstrates a minimal setup, that #</span>
|
||||
<span class="c1"># will start up the Reticulum Network Stack, generate a #</span>
|
||||
@@ -380,9 +376,7 @@ program.</p>
|
||||
</section>
|
||||
<section id="announce">
|
||||
<span id="example-announce"></span><h2>Announce<a class="headerlink" href="#announce" title="Link to this heading">¶</a></h2>
|
||||
<p>The <em>Announce</em> example builds upon the previous example by exploring how to
|
||||
announce a destination on the network, and how to let your program receive
|
||||
notifications about announces from relevant destinations.</p>
|
||||
<p>The <em>Announce</em> example builds upon the previous example by exploring how to announce a destination on the network, and how to let your program receive notifications about announces from relevant destinations.</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1">##########################################################</span>
|
||||
<span class="c1"># This RNS example demonstrates setting up announce #</span>
|
||||
<span class="c1"># callbacks, which will let an application receive a #</span>
|
||||
@@ -561,8 +555,7 @@ notifications about announces from relevant destinations.</p>
|
||||
</section>
|
||||
<section id="broadcast">
|
||||
<span id="example-broadcast"></span><h2>Broadcast<a class="headerlink" href="#broadcast" title="Link to this heading">¶</a></h2>
|
||||
<p>The <em>Broadcast</em> example explores how to transmit plaintext broadcast messages
|
||||
over the network.</p>
|
||||
<p>The <em>Broadcast</em> example explores how to transmit plaintext broadcast messages over the network.</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1">##########################################################</span>
|
||||
<span class="c1"># This RNS example demonstrates broadcasting unencrypted #</span>
|
||||
<span class="c1"># information to any listening destinations. #</span>
|
||||
@@ -690,8 +683,7 @@ over the network.</p>
|
||||
</section>
|
||||
<section id="echo">
|
||||
<span id="example-echo"></span><h2>Echo<a class="headerlink" href="#echo" title="Link to this heading">¶</a></h2>
|
||||
<p>The <em>Echo</em> example demonstrates communication between two destinations using
|
||||
the Packet interface.</p>
|
||||
<p>The <em>Echo</em> example demonstrates communication between two destinations using the Packet interface.</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1">##########################################################</span>
|
||||
<span class="c1"># This RNS example demonstrates a simple client/server #</span>
|
||||
<span class="c1"># echo utility. A client can send an echo request to the #</span>
|
||||
@@ -1030,8 +1022,7 @@ the Packet interface.</p>
|
||||
</section>
|
||||
<section id="link">
|
||||
<span id="example-link"></span><h2>Link<a class="headerlink" href="#link" title="Link to this heading">¶</a></h2>
|
||||
<p>The <em>Link</em> example explores establishing an encrypted link to a remote
|
||||
destination, and passing traffic back and forth over the link.</p>
|
||||
<p>The <em>Link</em> example explores establishing an encrypted link to a remote destination, and passing traffic back and forth over the link.</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1">##########################################################</span>
|
||||
<span class="c1"># This RNS example demonstrates how to set up a link to #</span>
|
||||
<span class="c1"># a destination, and pass data back and forth over it. #</span>
|
||||
@@ -1328,8 +1319,7 @@ destination, and passing traffic back and forth over the link.</p>
|
||||
</section>
|
||||
<section id="example-identify">
|
||||
<span id="identification"></span><h2>Identification<a class="headerlink" href="#example-identify" title="Link to this heading">¶</a></h2>
|
||||
<p>The <em>Identify</em> example explores identifying an intiator of a link, once
|
||||
the link has been established.</p>
|
||||
<p>The <em>Identify</em> example explores identifying an intiator of a link, once the link has been established.</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1">##########################################################</span>
|
||||
<span class="c1"># This RNS example demonstrates how to set up a link to #</span>
|
||||
<span class="c1"># a destination, and identify the initiator to it's peer #</span>
|
||||
@@ -1942,8 +1932,7 @@ the link has been established.</p>
|
||||
</section>
|
||||
<section id="channel">
|
||||
<span id="example-channel"></span><h2>Channel<a class="headerlink" href="#channel" title="Link to this heading">¶</a></h2>
|
||||
<p>The <em>Channel</em> example explores using a <code class="docutils literal notranslate"><span class="pre">Channel</span></code> to send structured
|
||||
data between peers of a <code class="docutils literal notranslate"><span class="pre">Link</span></code>.</p>
|
||||
<p>The <em>Channel</em> example explores using a <code class="docutils literal notranslate"><span class="pre">Channel</span></code> to send structured data between peers of a <code class="docutils literal notranslate"><span class="pre">Link</span></code>.</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1">##########################################################</span>
|
||||
<span class="c1"># This RNS example demonstrates how to set up a link to #</span>
|
||||
<span class="c1"># a destination, and pass structured messages over it #</span>
|
||||
@@ -2339,8 +2328,7 @@ data between peers of a <code class="docutils literal notranslate"><span class="
|
||||
</section>
|
||||
<section id="buffer">
|
||||
<h2>Buffer<a class="headerlink" href="#buffer" title="Link to this heading">¶</a></h2>
|
||||
<p>The <em>Buffer</em> example explores using buffered readers and writers to send
|
||||
binary data between peers of a <code class="docutils literal notranslate"><span class="pre">Link</span></code>.</p>
|
||||
<p>The <em>Buffer</em> example explores using buffered readers and writers to send binary data between peers of a <code class="docutils literal notranslate"><span class="pre">Link</span></code>.</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1">##########################################################</span>
|
||||
<span class="c1"># This RNS example demonstrates how to set up a link to #</span>
|
||||
<span class="c1"># a destination, and pass binary data over it using a #</span>
|
||||
@@ -2669,9 +2657,7 @@ binary data between peers of a <code class="docutils literal notranslate"><span
|
||||
</section>
|
||||
<section id="filetransfer">
|
||||
<span id="example-filetransfer"></span><h2>Filetransfer<a class="headerlink" href="#filetransfer" title="Link to this heading">¶</a></h2>
|
||||
<p>The <em>Filetransfer</em> example implements a basic file-server program that
|
||||
allow clients to connect and download files. The program uses the Resource
|
||||
interface to efficiently pass files of any size over a Reticulum <a class="reference internal" href="reference.html#api-link"><span class="std std-ref">Link</span></a>.</p>
|
||||
<p>The <em>Filetransfer</em> example implements a basic file-server program that allow clients to connect and download files. The program uses the Resource interface to efficiently pass files of any size over a Reticulum <a class="reference internal" href="reference.html#api-link"><span class="std std-ref">Link</span></a>.</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1">##########################################################</span>
|
||||
<span class="c1"># This RNS example demonstrates a simple filetransfer #</span>
|
||||
<span class="c1"># server and client program. The server will serve a #</span>
|
||||
@@ -3281,10 +3267,7 @@ interface to efficiently pass files of any size over a Reticulum <a class="refer
|
||||
</section>
|
||||
<section id="custom-interfaces">
|
||||
<span id="example-custominterface"></span><h2>Custom Interfaces<a class="headerlink" href="#custom-interfaces" title="Link to this heading">¶</a></h2>
|
||||
<p>The <em>ExampleInterface</em> demonstrates creating custom interfaces for Reticulum.
|
||||
Any number of custom interfaces can be loaded and utilised by Reticulum, and
|
||||
will be fully on-par with natively included interfaces, including all supported
|
||||
<a class="reference internal" href="interfaces.html#interfaces-modes"><span class="std std-ref">interface modes</span></a> and <a class="reference internal" href="interfaces.html#interfaces-options"><span class="std std-ref">common configuration options</span></a>.</p>
|
||||
<p>The <em>ExampleInterface</em> demonstrates creating custom interfaces for Reticulum. Any number of custom interfaces can be loaded and utilised by Reticulum, and will be fully on-par with natively included interfaces, including all supported <a class="reference internal" href="interfaces.html#interfaces-modes"><span class="std std-ref">interface modes</span></a> and <a class="reference internal" href="interfaces.html#interfaces-options"><span class="std std-ref">common configuration options</span></a>.</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># This example illustrates creating a custom interface</span>
|
||||
<span class="c1"># definition, that can be loaded and used by Reticulum at</span>
|
||||
<span class="c1"># runtime. Any number of custom interfaces can be created</span>
|
||||
|
||||
@@ -264,40 +264,27 @@
|
||||
<article role="main" id="furo-main-content">
|
||||
<section id="getting-started-fast">
|
||||
<h1>Getting Started Fast<a class="headerlink" href="#getting-started-fast" title="Link to this heading">¶</a></h1>
|
||||
<p>The best way to get started with the Reticulum Network Stack depends on what
|
||||
you want to do. This guide will outline sensible starting paths for different
|
||||
scenarios.</p>
|
||||
<p>The best way to get started with the Reticulum Network Stack depends on what you want to do. This guide will outline sensible starting paths for different scenarios.</p>
|
||||
<section id="standalone-reticulum-installation">
|
||||
<h2>Standalone Reticulum Installation<a class="headerlink" href="#standalone-reticulum-installation" title="Link to this heading">¶</a></h2>
|
||||
<p>If you simply want to install Reticulum and related utilities on a system,
|
||||
the easiest way is via the <code class="docutils literal notranslate"><span class="pre">pip</span></code> package manager:</p>
|
||||
<p>If you simply want to install Reticulum and related utilities on a system, the easiest way is via the <code class="docutils literal notranslate"><span class="pre">pip</span></code> package manager:</p>
|
||||
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>pip<span class="w"> </span>install<span class="w"> </span>rns
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>If you do not already have pip installed, you can install it using the package manager
|
||||
of your system with a command like <code class="docutils literal notranslate"><span class="pre">sudo</span> <span class="pre">apt</span> <span class="pre">install</span> <span class="pre">python3-pip</span></code>,
|
||||
<code class="docutils literal notranslate"><span class="pre">sudo</span> <span class="pre">pamac</span> <span class="pre">install</span> <span class="pre">python-pip</span></code> or similar.</p>
|
||||
<p>You can also dowload the Reticulum release wheels from GitHub, or other release channels,
|
||||
and install them offline using <code class="docutils literal notranslate"><span class="pre">pip</span></code>:</p>
|
||||
<p>If you do not already have pip installed, you can install it using the package manager of your system with a command like <code class="docutils literal notranslate"><span class="pre">sudo</span> <span class="pre">apt</span> <span class="pre">install</span> <span class="pre">python3-pip</span></code>, <code class="docutils literal notranslate"><span class="pre">sudo</span> <span class="pre">pamac</span> <span class="pre">install</span> <span class="pre">python-pip</span></code> or similar.</p>
|
||||
<p>You can also dowload the Reticulum release wheels from GitHub, or other release channels, and install them offline using <code class="docutils literal notranslate"><span class="pre">pip</span></code>:</p>
|
||||
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>pip<span class="w"> </span>install<span class="w"> </span>./rns-1.1.2-py3-none-any.whl
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>On platforms that limit user package installation via <code class="docutils literal notranslate"><span class="pre">pip</span></code>, you may need to manually
|
||||
allow this using the <code class="docutils literal notranslate"><span class="pre">--break-system-packages</span></code> command line flag when installing. This
|
||||
will not actually break any packages, unless you have installed Reticulum directly via
|
||||
your operating system’s package manager.</p>
|
||||
<p>On platforms that limit user package installation via <code class="docutils literal notranslate"><span class="pre">pip</span></code>, you may need to manually allow this using the <code class="docutils literal notranslate"><span class="pre">--break-system-packages</span></code> command line flag when installing. This will not actually break any packages, unless you have installed Reticulum directly via your operating system’s package manager.</p>
|
||||
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>pip<span class="w"> </span>install<span class="w"> </span>rns<span class="w"> </span>--break-system-packages
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>For more detailed installation instructions, please see the
|
||||
<a class="reference internal" href="#install-guides"><span class="std std-ref">Platform-Specific Install Notes</span></a> section.</p>
|
||||
<p>After installation is complete, it might be helpful to refer to the
|
||||
<a class="reference internal" href="using.html#using-main"><span class="std std-ref">Using Reticulum on Your System</span></a> chapter.</p>
|
||||
<p>For more detailed installation instructions, please see the <a class="reference internal" href="#install-guides"><span class="std std-ref">Platform-Specific Install Notes</span></a> section.</p>
|
||||
<p>After installation is complete, it might be helpful to refer to the <a class="reference internal" href="using.html#using-main"><span class="std std-ref">Using Reticulum on Your System</span></a> chapter.</p>
|
||||
<section id="resolving-dependency-installation-issues">
|
||||
<h3>Resolving Dependency & Installation Issues<a class="headerlink" href="#resolving-dependency-installation-issues" title="Link to this heading">¶</a></h3>
|
||||
<p>On some platforms, there may not be binary packages available for all dependencies, and
|
||||
<code class="docutils literal notranslate"><span class="pre">pip</span></code> installation may fail with an error message. In these cases, the issue can usually
|
||||
be resolved by installing the development essentials packages for your platform:</p>
|
||||
<p>On some platforms, there may not be binary packages available for all dependencies, and <code class="docutils literal notranslate"><span class="pre">pip</span></code> installation may fail with an error message. In these cases, the issue can usually be resolved by installing the development essentials packages for your platform:</p>
|
||||
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span><span class="c1"># Debian / Ubuntu / Derivatives</span>
|
||||
sudo<span class="w"> </span>apt<span class="w"> </span>install<span class="w"> </span>build-essential
|
||||
|
||||
@@ -308,59 +295,28 @@ sudo<span class="w"> </span>pamac<span class="w"> </span>install<span class="w">
|
||||
sudo<span class="w"> </span>dnf<span class="w"> </span>groupinstall<span class="w"> </span><span class="s2">"Development Tools"</span><span class="w"> </span><span class="s2">"Development Libraries"</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>With the base development packages installed, <code class="docutils literal notranslate"><span class="pre">pip</span></code> should be able to compile any missing
|
||||
dependencies from source, and complete installation even on platforms that don’t have pre-
|
||||
compiled packages available.</p>
|
||||
<p>With the base development packages installed, <code class="docutils literal notranslate"><span class="pre">pip</span></code> should be able to compile any missing dependencies from source, and complete installation even on platforms that don’t have pre-compiled packages available.</p>
|
||||
</section>
|
||||
</section>
|
||||
<section id="try-using-a-reticulum-based-program">
|
||||
<h2>Try Using a Reticulum-based Program<a class="headerlink" href="#try-using-a-reticulum-based-program" title="Link to this heading">¶</a></h2>
|
||||
<p>If you simply want to try using a program built with Reticulum, a <a class="reference internal" href="software.html#software-main"><span class="std std-ref">range of different
|
||||
programs</span></a> exist that allow basic communication and a various other useful functions,
|
||||
even over extremely low-bandwidth Reticulum networks.</p>
|
||||
<p>If you simply want to try using a program built with Reticulum, a <a class="reference internal" href="software.html#software-main"><span class="std std-ref">range of different programs</span></a> exist that allow basic communication and a various other useful functions, even over extremely low-bandwidth Reticulum networks.</p>
|
||||
</section>
|
||||
<section id="using-the-included-utilities">
|
||||
<h2>Using the Included Utilities<a class="headerlink" href="#using-the-included-utilities" title="Link to this heading">¶</a></h2>
|
||||
<p>Reticulum comes with a range of included utilities that make it easier to
|
||||
manage your network, check connectivity and make Reticulum available to other
|
||||
programs on your system.</p>
|
||||
<p>You can use <code class="docutils literal notranslate"><span class="pre">rnsd</span></code> to run Reticulum as a background or foreground service,
|
||||
and the <code class="docutils literal notranslate"><span class="pre">rnstatus</span></code>, <code class="docutils literal notranslate"><span class="pre">rnpath</span></code> and <code class="docutils literal notranslate"><span class="pre">rnprobe</span></code> utilities to view and query
|
||||
network status and connectivity.</p>
|
||||
<p>To learn more about these utility programs, have a look at the
|
||||
<a class="reference internal" href="using.html#using-main"><span class="std std-ref">Using Reticulum on Your System</span></a> chapter of this manual.</p>
|
||||
<p>Reticulum comes with a range of included utilities that make it easier to manage your network, check connectivity and make Reticulum available to other programs on your system.</p>
|
||||
<p>You can use <code class="docutils literal notranslate"><span class="pre">rnsd</span></code> to run Reticulum as a background or foreground service, and the <code class="docutils literal notranslate"><span class="pre">rnstatus</span></code>, <code class="docutils literal notranslate"><span class="pre">rnpath</span></code> and <code class="docutils literal notranslate"><span class="pre">rnprobe</span></code> utilities to view and query network status and connectivity.</p>
|
||||
<p>To learn more about these utility programs, have a look at the <a class="reference internal" href="using.html#using-main"><span class="std std-ref">Using Reticulum on Your System</span></a> chapter of this manual.</p>
|
||||
</section>
|
||||
<section id="creating-a-network-with-reticulum">
|
||||
<h2>Creating a Network With Reticulum<a class="headerlink" href="#creating-a-network-with-reticulum" title="Link to this heading">¶</a></h2>
|
||||
<p>To create a network, you will need to specify one or more <em>interfaces</em> for
|
||||
Reticulum to use. This is done in the Reticulum configuration file, which by
|
||||
default is located at <code class="docutils literal notranslate"><span class="pre">~/.reticulum/config</span></code>. You can get an example
|
||||
configuration file with all options via <code class="docutils literal notranslate"><span class="pre">rnsd</span> <span class="pre">--exampleconfig</span></code>.</p>
|
||||
<p>When Reticulum is started for the first time, it will create a default
|
||||
configuration file, with one active interface. This default interface uses
|
||||
your existing Ethernet and WiFi networks (if any), and only allows you to
|
||||
communicate with other Reticulum peers within your local broadcast domains.</p>
|
||||
<p>To communicate further, you will have to add one or more interfaces. The default
|
||||
configuration includes a number of examples, ranging from using TCP over the
|
||||
internet, to LoRa and Packet Radio interfaces.</p>
|
||||
<p>With Reticulum, you only need to configure what interfaces you want to communicate
|
||||
over. There is no need to configure address spaces, subnets, routing tables,
|
||||
or other things you might be used to from other network types.</p>
|
||||
<p>Once Reticulum knows which interfaces it should use, it will automatically
|
||||
discover topography and configure transport of data to any destinations it
|
||||
knows about.</p>
|
||||
<p>In situations where you already have an established WiFi or Ethernet network, and
|
||||
many devices that want to utilise the same external Reticulum network paths (for example over
|
||||
LoRa), it will often be sufficient to let one system act as a Reticulum gateway, by
|
||||
adding any external interfaces to the configuration of this system, and then enabling transport on it. Any
|
||||
other device on your local WiFi will then be able to connect to this wider Reticulum
|
||||
network just using the default (<a class="reference internal" href="interfaces.html#interfaces-auto"><span class="std std-ref">AutoInterface</span></a>) configuration.</p>
|
||||
<p>Possibly, the examples in the config file are enough to get you started. If
|
||||
you want more information, you can read the <a class="reference internal" href="networks.html#networks-main"><span class="std std-ref">Building Networks</span></a>
|
||||
and <a class="reference internal" href="interfaces.html#interfaces-main"><span class="std std-ref">Interfaces</span></a> chapters of this manual, but most importantly,
|
||||
start with reading the next section, <a class="reference internal" href="#bootstrapping-connectivity"><span class="std std-ref">Bootstrapping Connectivity</span></a>,
|
||||
as this provides the most essential understanding of how to ensure reliable
|
||||
connectivity with a minimum of maintenance.</p>
|
||||
<p>To create a network, you will need to specify one or more <em>interfaces</em> for Reticulum to use. This is done in the Reticulum configuration file, which by default is located at <code class="docutils literal notranslate"><span class="pre">~/.reticulum/config</span></code>. You can get an example configuration file with all options via <code class="docutils literal notranslate"><span class="pre">rnsd</span> <span class="pre">--exampleconfig</span></code>.</p>
|
||||
<p>When Reticulum is started for the first time, it will create a default configuration file, with one active interface. This default interface uses your existing Ethernet and WiFi networks (if any), and only allows you to communicate with other Reticulum peers within your local broadcast domains.</p>
|
||||
<p>To communicate further, you will have to add one or more interfaces. The default configuration includes a number of examples, ranging from using TCP over the internet, to LoRa and Packet Radio interfaces.</p>
|
||||
<p>With Reticulum, you only need to configure what interfaces you want to communicate over. There is no need to configure address spaces, subnets, routing tables, or other things you might be used to from other network types.</p>
|
||||
<p>Once Reticulum knows which interfaces it should use, it will automatically discover topography and configure transport of data to any destinations it knows about.</p>
|
||||
<p>In situations where you already have an established WiFi or Ethernet network, and many devices that want to utilise the same external Reticulum network paths (for example over LoRa), it will often be sufficient to let one system act as a Reticulum gateway, by adding any external interfaces to the configuration of this system, and then enabling transport on it. Any other device on your local WiFi will then be able to connect to this wider Reticulum network just using the default (<a class="reference internal" href="interfaces.html#interfaces-auto"><span class="std std-ref">AutoInterface</span></a>) configuration.</p>
|
||||
<p>Possibly, the examples in the config file are enough to get you started. If you want more information, you can read the <a class="reference internal" href="networks.html#networks-main"><span class="std std-ref">Building Networks</span></a> and <a class="reference internal" href="interfaces.html#interfaces-main"><span class="std std-ref">Interfaces</span></a> chapters of this manual, but most importantly, start with reading the next section, <a class="reference internal" href="#bootstrapping-connectivity"><span class="std std-ref">Bootstrapping Connectivity</span></a>, as this provides the most essential understanding of how to ensure reliable connectivity with a minimum of maintenance.</p>
|
||||
</section>
|
||||
<section id="bootstrapping-connectivity">
|
||||
<span id="id1"></span><h2>Bootstrapping Connectivity<a class="headerlink" href="#bootstrapping-connectivity" title="Link to this heading">¶</a></h2>
|
||||
@@ -425,17 +381,10 @@ connectivity with a minimum of maintenance.</p>
|
||||
</section>
|
||||
<section id="hosting-public-entrypoints">
|
||||
<span id="hosting-entrypoints"></span><h2>Hosting Public Entrypoints<a class="headerlink" href="#hosting-public-entrypoints" title="Link to this heading">¶</a></h2>
|
||||
<p>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
|
||||
Internet. This section offers some helpful pointers. Once you have set up your public entrypoint, it is a great idea to <a class="reference internal" href="interfaces.html#interfaces-discoverable"><span class="std std-ref">make it discoverable over Reticulum</span></a>.</p>
|
||||
<p>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 Internet. This section offers some helpful pointers. Once you have set up your public entrypoint, it is a great idea to <a class="reference internal" href="interfaces.html#interfaces-discoverable"><span class="std std-ref">make it discoverable over Reticulum</span></a>.</p>
|
||||
<p>You will need a machine, physical or virtual with a public IP address, that can be reached by other devices on the Internet.</p>
|
||||
<p>The most efficient and performant way to host a connectable entry-point supporting many
|
||||
users is to use the <code class="docutils literal notranslate"><span class="pre">BackboneInterface</span></code>. This interface type is fully compatible with
|
||||
the <code class="docutils literal notranslate"><span class="pre">TCPClientInterface</span></code> and <code class="docutils literal notranslate"><span class="pre">TCPServerInterface</span></code> types, but much faster and uses
|
||||
less system resources, allowing your device to handle thousands of connections even on
|
||||
small systems.</p>
|
||||
<p>It is also important to set your connectable interface to <code class="docutils literal notranslate"><span class="pre">gateway</span></code> mode, since this
|
||||
will greatly improve network convergence time and path resolution for anyone connecting
|
||||
to your entry-point.</p>
|
||||
<p>The most efficient and performant way to host a connectable entry-point supporting many users is to use the <code class="docutils literal notranslate"><span class="pre">BackboneInterface</span></code>. This interface type is fully compatible with the <code class="docutils literal notranslate"><span class="pre">TCPClientInterface</span></code> and <code class="docutils literal notranslate"><span class="pre">TCPServerInterface</span></code> types, but much faster and uses less system resources, allowing your device to handle thousands of connections even on small systems.</p>
|
||||
<p>It is also important to set your connectable interface to <code class="docutils literal notranslate"><span class="pre">gateway</span></code> mode, since this will greatly improve network convergence time and path resolution for anyone connecting to your entry-point.</p>
|
||||
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="c1"># This example demonstrates a backbone interface</span>
|
||||
<span class="c1"># configured for acting as a gateway for users to</span>
|
||||
<span class="c1"># connect to either a public or private network</span>
|
||||
@@ -455,8 +404,7 @@ to your entry-point.</p>
|
||||
<span class="w"> </span><span class="na">announce_rate_grace</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">6</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>If instead you want to make a private entry-point from the Internet, you can use the
|
||||
<a class="reference internal" href="interfaces.html#interfaces-options"><span class="std std-ref">IFAC name and passphrase options</span></a> to secure your interface with a network name and passphrase.</p>
|
||||
<p>If instead you want to make a private entry-point from the Internet, you can use the <a class="reference internal" href="interfaces.html#interfaces-options"><span class="std std-ref">IFAC name and passphrase options</span></a> to secure your interface with a network name and passphrase.</p>
|
||||
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="c1"># A private entry-point requiring a pre-shared</span>
|
||||
<span class="c1"># network name and passphrase to connect to.</span>
|
||||
|
||||
@@ -470,104 +418,51 @@ to your entry-point.</p>
|
||||
<span class="w"> </span><span class="na">passphrase</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">2owjajquafIanPecAc</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>If you are hosting an entry-point on an operating system that does not support
|
||||
<code class="docutils literal notranslate"><span class="pre">BackboneInterface</span></code>, you can use <code class="docutils literal notranslate"><span class="pre">TCPServerInterface</span></code> instead, although it will
|
||||
not be as performant.</p>
|
||||
<p>If you are hosting an entry-point on an operating system that does not support <code class="docutils literal notranslate"><span class="pre">BackboneInterface</span></code>, you can use <code class="docutils literal notranslate"><span class="pre">TCPServerInterface</span></code> instead, although it will not be as performant.</p>
|
||||
</section>
|
||||
<section id="connecting-reticulum-instances-over-the-internet">
|
||||
<h2>Connecting Reticulum Instances Over the Internet<a class="headerlink" href="#connecting-reticulum-instances-over-the-internet" title="Link to this heading">¶</a></h2>
|
||||
<p>Reticulum currently offers three interfaces suitable for connecting instances over the Internet: <a class="reference internal" href="interfaces.html#interfaces-backbone"><span class="std std-ref">Backbone</span></a>, <a class="reference internal" href="interfaces.html#interfaces-tcps"><span class="std std-ref">TCP</span></a>
|
||||
and <a class="reference internal" href="interfaces.html#interfaces-i2p"><span class="std std-ref">I2P</span></a>. Each interface offers a different set of features, and Reticulum
|
||||
users should carefully choose the interface which best suites their needs.</p>
|
||||
<p>The <code class="docutils literal notranslate"><span class="pre">TCPServerInterface</span></code> allows users to host an instance accessible over TCP/IP. This
|
||||
method is generally faster, lower latency, and more energy efficient than using <code class="docutils literal notranslate"><span class="pre">I2PInterface</span></code>,
|
||||
however it also leaks more data about the server host.</p>
|
||||
<p>The <code class="docutils literal notranslate"><span class="pre">BackboneInterface</span></code> is a very fast and efficient interface type available on POSIX operating
|
||||
systems, designed to handle thousands of connections simultaneously with low memory, processing
|
||||
and I/O overhead. It is fully compatible with the TCP-based interface types.</p>
|
||||
<p>TCP connections reveal the IP address of both your instance and the server to anyone who can
|
||||
inspect the connection. Someone could use this information to determine your location or identity. Adversaries
|
||||
inspecting your packets may be able to record packet metadata like time of transmission and packet size.
|
||||
Even though Reticulum encrypts traffic, TCP does not, so an adversary may be able to use
|
||||
packet inspection to learn that a system is running Reticulum, and what other IP addresses connect to it.
|
||||
Hosting a publicly reachable instance over TCP also requires a publicly reachable IP address,
|
||||
which most Internet connections don’t offer anymore.</p>
|
||||
<p>The <code class="docutils literal notranslate"><span class="pre">I2PInterface</span></code> routes messages through the <a class="reference external" href="https://geti2p.net/en/">Invisible Internet Protocol
|
||||
(I2P)</a>. To use this interface, users must also run an I2P daemon in
|
||||
parallel to <code class="docutils literal notranslate"><span class="pre">rnsd</span></code>. For always-on I2P nodes it is recommended to use <a class="reference external" href="https://i2pd.website/">i2pd</a>.</p>
|
||||
<p>By default, I2P will encrypt and mix all traffic sent over the Internet, and
|
||||
hide both the sender and receiver Reticulum instance IP addresses. Running an I2P node
|
||||
will also relay other I2P user’s encrypted packets, which will use extra
|
||||
bandwidth and compute power, but also makes timing attacks and other forms of
|
||||
deep-packet-inspection much more difficult.</p>
|
||||
<p>Reticulum currently offers three interfaces suitable for connecting instances over the Internet: <a class="reference internal" href="interfaces.html#interfaces-backbone"><span class="std std-ref">Backbone</span></a>, <a class="reference internal" href="interfaces.html#interfaces-tcps"><span class="std std-ref">TCP</span></a> and <a class="reference internal" href="interfaces.html#interfaces-i2p"><span class="std std-ref">I2P</span></a>. Each interface offers a different set of features, and Reticulum users should carefully choose the interface which best suites their needs.</p>
|
||||
<p>The <code class="docutils literal notranslate"><span class="pre">TCPServerInterface</span></code> allows users to host an instance accessible over TCP/IP. This method is generally faster, lower latency, and more energy efficient than using <code class="docutils literal notranslate"><span class="pre">I2PInterface</span></code>, however it also leaks more data about the server host.</p>
|
||||
<p>The <code class="docutils literal notranslate"><span class="pre">BackboneInterface</span></code> is a very fast and efficient interface type available on POSIX operating systems, designed to handle thousands of connections simultaneously with low memory, processing and I/O overhead. It is fully compatible with the TCP-based interface types.</p>
|
||||
<p>TCP connections reveal the IP address of both your instance and the server to anyone who can inspect the connection. Someone could use this information to determine your location or identity. Adversaries inspecting your packets may be able to record packet metadata like time of transmission and packet size. Even though Reticulum encrypts traffic, TCP does not, so an adversary may be able to use packet inspection to learn that a system is running Reticulum, and what other IP addresses connect to it. Hosting a publicly reachable instance over TCP also requires a publicly reachable IP address, which most Internet connections don’t offer anymore.</p>
|
||||
<p>The <code class="docutils literal notranslate"><span class="pre">I2PInterface</span></code> routes messages through the <a class="reference external" href="https://geti2p.net/en/">Invisible Internet Protocol (I2P)</a>. To use this interface, users must also run an I2P daemon in parallel to <code class="docutils literal notranslate"><span class="pre">rnsd</span></code>. For always-on I2P nodes it is recommended to use <a class="reference external" href="https://i2pd.website/">i2pd</a>.</p>
|
||||
<p>By default, I2P will encrypt and mix all traffic sent over the Internet, and hide both the sender and receiver Reticulum instance IP addresses. Running an I2P node will also relay other I2P user’s encrypted packets, which will use extra bandwidth and compute power, but also makes timing attacks and other forms of deep-packet-inspection much more difficult.</p>
|
||||
<p>I2P also allows users to host globally available Reticulum instances from non-public IP’s and behind firewalls and NAT.</p>
|
||||
<p>In general it is recommended to use an I2P node if you want to host a publicly accessible
|
||||
instance, while preserving anonymity. If you care more about performance, and a slightly
|
||||
easier setup, use TCP.</p>
|
||||
<p>In general it is recommended to use an I2P node if you want to host a publicly accessible instance, while preserving anonymity. If you care more about performance, and a slightly easier setup, use TCP.</p>
|
||||
</section>
|
||||
<section id="adding-radio-interfaces">
|
||||
<h2>Adding Radio Interfaces<a class="headerlink" href="#adding-radio-interfaces" title="Link to this heading">¶</a></h2>
|
||||
<p>Once you have Reticulum installed and working, you can add radio interfaces with
|
||||
any compatible hardware you have available. Reticulum supports a wide range of radio
|
||||
hardware, and if you already have any available, it is very likely that it will
|
||||
work with Reticulum. For information on how to configure this, see the
|
||||
<a class="reference internal" href="interfaces.html#interfaces-main"><span class="std std-ref">Interfaces</span></a> section of this manual.</p>
|
||||
<p>If you do not already have transceiver hardware available, you can easily and
|
||||
cheaply build an <a class="reference internal" href="hardware.html#rnode-main"><span class="std std-ref">RNode</span></a>, which is a general-purpose long-range
|
||||
digital radio transceiver, that integrates easily with Reticulum.</p>
|
||||
<p>To build one yourself requires installing a custom firmware on a supported LoRa
|
||||
development board with an auto-install script or web-based flasher.
|
||||
Please see the <a class="reference internal" href="hardware.html#hardware-main"><span class="std std-ref">Communications Hardware</span></a> chapter for a guide.
|
||||
If you prefer purchasing a ready-made unit, you can refer to the
|
||||
<span class="xref std std-ref">list of suppliers</span>.</p>
|
||||
<p>Other radio-based hardware interfaces are being developed and made available by
|
||||
the broader Reticulum community. You can find more information on such topics
|
||||
over Reticulum-based information sharing systems.</p>
|
||||
<p>If you have communications hardware that is not already supported by any of the
|
||||
<a class="reference internal" href="interfaces.html#interfaces-main"><span class="std std-ref">existing interface types</span></a>, it is easy to write (and potentially
|
||||
publish) a <a class="reference internal" href="interfaces.html#interfaces-custom"><span class="std std-ref">custom interface module</span></a> that makes it compatible with Reticulum.</p>
|
||||
<p>Once you have Reticulum installed and working, you can add radio interfaces with any compatible hardware you have available. Reticulum supports a wide range of radio hardware, and if you already have any available, it is very likely that it will work with Reticulum. For information on how to configure this, see the <a class="reference internal" href="interfaces.html#interfaces-main"><span class="std std-ref">Interfaces</span></a> section of this manual.</p>
|
||||
<p>If you do not already have transceiver hardware available, you can easily and cheaply build an <a class="reference internal" href="hardware.html#rnode-main"><span class="std std-ref">RNode</span></a>, which is a general-purpose long-range digital radio transceiver, that integrates easily with Reticulum.</p>
|
||||
<p>To build one yourself requires installing a custom firmware on a supported LoRa development board with an auto-install script or web-based flasher. Please see the <a class="reference internal" href="hardware.html#hardware-main"><span class="std std-ref">Communications Hardware</span></a> chapter for a guide. If you prefer purchasing a ready-made unit, you can refer to the <span class="xref std std-ref">list of suppliers</span>.</p>
|
||||
<p>Other radio-based hardware interfaces are being developed and made available by the broader Reticulum community. You can find more information on such topics over Reticulum-based information sharing systems.</p>
|
||||
<p>If you have communications hardware that is not already supported by any of the <a class="reference internal" href="interfaces.html#interfaces-main"><span class="std std-ref">existing interface types</span></a>, it is easy to write (and potentially publish) a <a class="reference internal" href="interfaces.html#interfaces-custom"><span class="std std-ref">custom interface module</span></a> that makes it compatible with Reticulum.</p>
|
||||
</section>
|
||||
<section id="creating-and-using-custom-interfaces">
|
||||
<h2>Creating and Using Custom Interfaces<a class="headerlink" href="#creating-and-using-custom-interfaces" title="Link to this heading">¶</a></h2>
|
||||
<p>While Reticulum includes a flexible and broad range of built-in interfaces, these
|
||||
will not cover every conceivable type of communications hardware that Reticulum
|
||||
can potentially use to communicate.</p>
|
||||
<p>It is therefore possible to easily write your own interface modules, that can be
|
||||
loaded at run-time and used on-par with any of the built-in interface types.</p>
|
||||
<p>For more information on this subject, and code examples to build on, please see
|
||||
the <a class="reference internal" href="interfaces.html#interfaces-main"><span class="std std-ref">Configuring Interfaces</span></a> chapter.</p>
|
||||
<p>While Reticulum includes a flexible and broad range of built-in interfaces, these will not cover every conceivable type of communications hardware that Reticulum can potentially use to communicate.</p>
|
||||
<p>It is therefore possible to easily write your own interface modules, that can be loaded at run-time and used on-par with any of the built-in interface types.</p>
|
||||
<p>For more information on this subject, and code examples to build on, please see the <a class="reference internal" href="interfaces.html#interfaces-main"><span class="std std-ref">Configuring Interfaces</span></a> chapter.</p>
|
||||
</section>
|
||||
<section id="develop-a-program-with-reticulum">
|
||||
<h2>Develop a Program with Reticulum<a class="headerlink" href="#develop-a-program-with-reticulum" title="Link to this heading">¶</a></h2>
|
||||
<p>If you want to develop programs that use Reticulum, the easiest way to get
|
||||
started is to install the latest release of Reticulum via pip:</p>
|
||||
<p>If you want to develop programs that use Reticulum, the easiest way to get started is to install the latest release of Reticulum via pip:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="n">rns</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>The above command will install Reticulum and dependencies, and you will be
|
||||
ready to import and use RNS in your own programs. The next step will most
|
||||
likely be to look at some <a class="reference internal" href="examples.html#examples-main"><span class="std std-ref">Example Programs</span></a>.</p>
|
||||
<p>The entire Reticulum API is documented in the <a class="reference internal" href="reference.html#api-main"><span class="std std-ref">API Reference</span></a>
|
||||
chapter of this manual. Before diving in, it’s probably a good idea to read
|
||||
this manual in full, but at least start with the <a class="reference internal" href="understanding.html#understanding-main"><span class="std std-ref">Understanding Reticulum</span></a> chapter.</p>
|
||||
<p>The above command will install Reticulum and dependencies, and you will be ready to import and use RNS in your own programs. The next step will most likely be to look at some <a class="reference internal" href="examples.html#examples-main"><span class="std std-ref">Example Programs</span></a>.</p>
|
||||
<p>The entire Reticulum API is documented in the <a class="reference internal" href="reference.html#api-main"><span class="std std-ref">API Reference</span></a> chapter of this manual. Before diving in, it’s probably a good idea to read this manual in full, but at least start with the <a class="reference internal" href="understanding.html#understanding-main"><span class="std std-ref">Understanding Reticulum</span></a> chapter.</p>
|
||||
</section>
|
||||
<section id="platform-specific-install-notes">
|
||||
<span id="install-guides"></span><h2>Platform-Specific Install Notes<a class="headerlink" href="#platform-specific-install-notes" title="Link to this heading">¶</a></h2>
|
||||
<p>Some platforms require a slightly different installation procedure, or have
|
||||
various quirks that are worth being aware of. These are listed here.</p>
|
||||
<p>Some platforms require a slightly different installation procedure, or have various quirks that are worth being aware of. These are listed here.</p>
|
||||
<section id="android">
|
||||
<h3>Android<a class="headerlink" href="#android" title="Link to this heading">¶</a></h3>
|
||||
<p>Reticulum can be used on Android in different ways. The easiest way to get
|
||||
started is using an app like <a class="reference external" href="https://unsigned.io/sideband">Sideband</a>.</p>
|
||||
<p>For more control and features, you can use Reticulum and related programs via
|
||||
the <a class="reference external" href="https://termux.com/">Termux app</a>, at the time of writing available on
|
||||
<a class="reference external" href="https://f-droid.org">F-droid</a>.</p>
|
||||
<p>Termux is a terminal emulator and Linux environment for Android based devices,
|
||||
which includes the ability to use many different programs and libraries,
|
||||
including Reticulum.</p>
|
||||
<p>To use Reticulum within the Termux environment, you will need to install
|
||||
<code class="docutils literal notranslate"><span class="pre">python</span></code> and the <code class="docutils literal notranslate"><span class="pre">python-cryptography</span></code> library using <code class="docutils literal notranslate"><span class="pre">pkg</span></code>, the package-manager
|
||||
build into Termux. After that, you can use <code class="docutils literal notranslate"><span class="pre">pip</span></code> to install Reticulum.</p>
|
||||
<p>Reticulum can be used on Android in different ways. The easiest way to get started is using an app like <a class="reference external" href="https://unsigned.io/sideband">Sideband</a>.</p>
|
||||
<p>For more control and features, you can use Reticulum and related programs via the <a class="reference external" href="https://termux.com/">Termux app</a>, at the time of writing available on <a class="reference external" href="https://f-droid.org">F-droid</a>.</p>
|
||||
<p>Termux is a terminal emulator and Linux environment for Android based devices, which includes the ability to use many different programs and libraries, including Reticulum.</p>
|
||||
<p>To use Reticulum within the Termux environment, you will need to install <code class="docutils literal notranslate"><span class="pre">python</span></code> and the <code class="docutils literal notranslate"><span class="pre">python-cryptography</span></code> library using <code class="docutils literal notranslate"><span class="pre">pkg</span></code>, the package-manager build into Termux. After that, you can use <code class="docutils literal notranslate"><span class="pre">pip</span></code> to install Reticulum.</p>
|
||||
<p>From within Termux, execute the following:</p>
|
||||
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span><span class="c1"># First, make sure indexes and packages are up to date.</span>
|
||||
pkg<span class="w"> </span>update
|
||||
@@ -583,9 +478,7 @@ pip<span class="w"> </span>install<span class="w"> </span>wheel<span class="w">
|
||||
pip<span class="w"> </span>install<span class="w"> </span>rns
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>If for some reason the <code class="docutils literal notranslate"><span class="pre">python-cryptography</span></code> package is not available for
|
||||
your platform via the Termux package manager, you can attempt to build it
|
||||
locally on your device using the following command:</p>
|
||||
<p>If for some reason the <code class="docutils literal notranslate"><span class="pre">python-cryptography</span></code> package is not available for your platform via the Termux package manager, you can attempt to build it locally on your device using the following command:</p>
|
||||
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span><span class="c1"># First, make sure indexes and packages are up to date.</span>
|
||||
pkg<span class="w"> </span>update
|
||||
pkg<span class="w"> </span>upgrade
|
||||
@@ -610,15 +503,11 @@ pip<span class="w"> </span>install<span class="w"> </span>cryptography
|
||||
pip<span class="w"> </span>install<span class="w"> </span>rns
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>It is also possible to include Reticulum in apps compiled and distributed as
|
||||
Android APKs. A detailed tutorial and example source code will be included
|
||||
here at a later point. Until then you can use the <a class="reference external" href="https://github.com/markqvist/sideband">Sideband source code</a> as an example and starting point.</p>
|
||||
<p>It is also possible to include Reticulum in apps compiled and distributed as Android APKs. A detailed tutorial and example source code will be included here at a later point. Until then you can use the <a class="reference external" href="https://github.com/markqvist/sideband">Sideband source code</a> as an example and starting point.</p>
|
||||
</section>
|
||||
<section id="arm64">
|
||||
<h3>ARM64<a class="headerlink" href="#arm64" title="Link to this heading">¶</a></h3>
|
||||
<p>On some architectures, including ARM64, not all dependencies have precompiled
|
||||
binaries. On such systems, you may need to install <code class="docutils literal notranslate"><span class="pre">python3-dev</span></code> (or similar) before
|
||||
installing Reticulum or programs that depend on Reticulum.</p>
|
||||
<p>On some architectures, including ARM64, not all dependencies have precompiled binaries. On such systems, you may need to install <code class="docutils literal notranslate"><span class="pre">python3-dev</span></code> (or similar) before installing Reticulum or programs that depend on Reticulum.</p>
|
||||
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install Python and development packages</span>
|
||||
sudo<span class="w"> </span>apt<span class="w"> </span>update
|
||||
sudo<span class="w"> </span>apt<span class="w"> </span>install<span class="w"> </span>python3<span class="w"> </span>python3-pip<span class="w"> </span>python3-dev
|
||||
@@ -632,11 +521,7 @@ on your system locally.</p>
|
||||
</section>
|
||||
<section id="debian-bookworm">
|
||||
<h3>Debian Bookworm<a class="headerlink" href="#debian-bookworm" title="Link to this heading">¶</a></h3>
|
||||
<p>On versions of Debian released after April 2023, it is no longer possible by default
|
||||
to use <code class="docutils literal notranslate"><span class="pre">pip</span></code> to install packages onto your system. Unfortunately, you will need to
|
||||
use the replacement <code class="docutils literal notranslate"><span class="pre">pipx</span></code> command instead, which places installed packages in an
|
||||
isolated environment. This should not negatively affect Reticulum, but will not work
|
||||
for including and using Reticulum in your own scripts and programs.</p>
|
||||
<p>On versions of Debian released after April 2023, it is no longer possible by default to use <code class="docutils literal notranslate"><span class="pre">pip</span></code> to install packages onto your system. Unfortunately, you will need to use the replacement <code class="docutils literal notranslate"><span class="pre">pipx</span></code> command instead, which places installed packages in an isolated environment. This should not negatively affect Reticulum, but will not work for including and using Reticulum in your own scripts and programs.</p>
|
||||
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install pipx</span>
|
||||
sudo<span class="w"> </span>apt<span class="w"> </span>install<span class="w"> </span>pipx
|
||||
|
||||
@@ -647,15 +532,12 @@ pipx<span class="w"> </span>ensurepath
|
||||
pipx<span class="w"> </span>install<span class="w"> </span>rns
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Alternatively, you can restore normal behaviour to <code class="docutils literal notranslate"><span class="pre">pip</span></code> by creating or editing
|
||||
the configuration file located at <code class="docutils literal notranslate"><span class="pre">~/.config/pip/pip.conf</span></code>, and adding the
|
||||
following section:</p>
|
||||
<p>Alternatively, you can restore normal behaviour to <code class="docutils literal notranslate"><span class="pre">pip</span></code> by creating or editing the configuration file located at <code class="docutils literal notranslate"><span class="pre">~/.config/pip/pip.conf</span></code>, and adding the following section:</p>
|
||||
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[global]</span>
|
||||
<span class="na">break-system-packages</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">true</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>For a one-shot installation of Reticulum, without globally enabling the <code class="docutils literal notranslate"><span class="pre">break-system-packages</span></code>
|
||||
option, you can use the following command:</p>
|
||||
<p>For a one-shot installation of Reticulum, without globally enabling the <code class="docutils literal notranslate"><span class="pre">break-system-packages</span></code> option, you can use the following command:</p>
|
||||
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>pip<span class="w"> </span>install<span class="w"> </span>rns<span class="w"> </span>--break-system-packages
|
||||
</pre></div>
|
||||
</div>
|
||||
@@ -670,14 +552,9 @@ not in the case of installing Reticulum.</p>
|
||||
</section>
|
||||
<section id="macos">
|
||||
<h3>MacOS<a class="headerlink" href="#macos" title="Link to this heading">¶</a></h3>
|
||||
<p>To install Reticulum on macOS, you will need to have Python and the <code class="docutils literal notranslate"><span class="pre">pip</span></code> package
|
||||
manager installed.</p>
|
||||
<p>Systems running macOS can vary quite widely in whether or not Python is pre-installed,
|
||||
and if it is, which version is installed, and whether the <code class="docutils literal notranslate"><span class="pre">pip</span></code> package manager is
|
||||
also installed and set up. If in doubt, you can <a class="reference external" href="https://www.python.org/downloads/">download and install</a>
|
||||
Python manually.</p>
|
||||
<p>When Python and <code class="docutils literal notranslate"><span class="pre">pip</span></code> is available on your system, simply open a terminal window
|
||||
and use one of the following commands:</p>
|
||||
<p>To install Reticulum on macOS, you will need to have Python and the <code class="docutils literal notranslate"><span class="pre">pip</span></code> package manager installed.</p>
|
||||
<p>Systems running macOS can vary quite widely in whether or not Python is pre-installed, and if it is, which version is installed, and whether the <code class="docutils literal notranslate"><span class="pre">pip</span></code> package manager is also installed and set up. If in doubt, you can <a class="reference external" href="https://www.python.org/downloads/">download and install</a> Python manually.</p>
|
||||
<p>When Python and <code class="docutils literal notranslate"><span class="pre">pip</span></code> is available on your system, simply open a terminal window and use one of the following commands:</p>
|
||||
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install Reticulum and utilities with pip:</span>
|
||||
pip3<span class="w"> </span>install<span class="w"> </span>rns
|
||||
|
||||
@@ -688,16 +565,9 @@ pip3<span class="w"> </span>install<span class="w"> </span>rns<span class="w"> <
|
||||
</div>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>The <code class="docutils literal notranslate"><span class="pre">--break-system-packages</span></code> directive is a somewhat misleading choice
|
||||
of words. Setting it will of course not break any system packages, but will simply
|
||||
allow installing <code class="docutils literal notranslate"><span class="pre">pip</span></code> packages user- and system-wide. While this <em>could</em> in rare
|
||||
cases lead to version conflicts, it does not generally pose any problems, especially
|
||||
not in the case of installing Reticulum.</p>
|
||||
<p>The <code class="docutils literal notranslate"><span class="pre">--break-system-packages</span></code> directive is a somewhat misleading choice of words. Setting it will of course not break any system packages, but will simply allow installing <code class="docutils literal notranslate"><span class="pre">pip</span></code> packages user- and system-wide. While this <em>could</em> in rare cases lead to version conflicts, it does not generally pose any problems, especially not in the case of installing Reticulum.</p>
|
||||
</div>
|
||||
<p>Additionally, some version combinations of macOS and Python require you to
|
||||
manually add your installed <code class="docutils literal notranslate"><span class="pre">pip</span></code> packages directory to your <cite>PATH</cite> environment
|
||||
variable, before you can use installed commands in your terminal. Usually, adding
|
||||
the following line to your shell init script (for example <code class="docutils literal notranslate"><span class="pre">~/.zshrc</span></code>) will be enough:</p>
|
||||
<p>Additionally, some version combinations of macOS and Python require you to manually add your installed <code class="docutils literal notranslate"><span class="pre">pip</span></code> packages directory to your <cite>PATH</cite> environment variable, before you can use installed commands in your terminal. Usually, adding the following line to your shell init script (for example <code class="docutils literal notranslate"><span class="pre">~/.zshrc</span></code>) will be enough:</p>
|
||||
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span><span class="nb">export</span><span class="w"> </span><span class="nv">PATH</span><span class="o">=</span><span class="nv">$PATH</span>:~/Library/Python/3.9/bin
|
||||
</pre></div>
|
||||
</div>
|
||||
@@ -705,8 +575,7 @@ the following line to your shell init script (for example <code class="docutils
|
||||
</section>
|
||||
<section id="openwrt">
|
||||
<h3>OpenWRT<a class="headerlink" href="#openwrt" title="Link to this heading">¶</a></h3>
|
||||
<p>On OpenWRT systems with sufficient storage and memory, you can install
|
||||
Reticulum and related utilities using the <cite>opkg</cite> package manager and <cite>pip</cite>.</p>
|
||||
<p>On OpenWRT systems with sufficient storage and memory, you can install Reticulum and related utilities using the <cite>opkg</cite> package manager and <cite>pip</cite>.</p>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>At the time of releasing this manual, work is underway to create pre-built
|
||||
@@ -715,8 +584,7 @@ and <code class="docutils literal notranslate"><span class="pre">uci</span></cod
|
||||
and <a class="reference external" href="https://github.com/gretel/reticulum-openwrt">reticulum-openwrt</a>
|
||||
repositories for more information.</p>
|
||||
</div>
|
||||
<p>To install Reticulum on OpenWRT, first log into a command line session, and
|
||||
then use the following instructions:</p>
|
||||
<p>To install Reticulum on OpenWRT, first log into a command line session, and then use the following instructions:</p>
|
||||
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install dependencies</span>
|
||||
opkg<span class="w"> </span>install<span class="w"> </span>python3<span class="w"> </span>python3-pip<span class="w"> </span>python3-cryptography<span class="w"> </span>python3-pyserial
|
||||
|
||||
@@ -729,28 +597,14 @@ rnsd<span class="w"> </span>-vvv
|
||||
</div>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>The above instructions have been verified and tested on OpenWRT 21.02 only.
|
||||
It is likely that other versions may require slightly altered installation
|
||||
commands or package names. You will also need enough free space in your
|
||||
overlay FS, and enough free RAM to actually run Reticulum and any related
|
||||
programs and utilities.</p>
|
||||
<p>The above instructions have been verified and tested on OpenWRT 21.02 only. It is likely that other versions may require slightly altered installation commands or package names. You will also need enough free space in your overlay FS, and enough free RAM to actually run Reticulum and any related programs and utilities.</p>
|
||||
</div>
|
||||
<p>Depending on your device configuration, you may need to adjust firewall rules
|
||||
for Reticulum connectivity to and from your device to work. Until proper
|
||||
packaging is ready, you will also need to manually create a service or startup
|
||||
script to automatically laucnh Reticulum at boot time.</p>
|
||||
<p>Please also note that the <cite>AutoInterface</cite> requires link-local IPv6 addresses
|
||||
to be enabled for any Ethernet and WiFi devices you intend to use. If <code class="docutils literal notranslate"><span class="pre">ip</span> <span class="pre">a</span></code>
|
||||
shows an address starting with <code class="docutils literal notranslate"><span class="pre">fe80::</span></code> for the device in question,
|
||||
<code class="docutils literal notranslate"><span class="pre">AutoInterface</span></code> should work for that device.</p>
|
||||
<p>Depending on your device configuration, you may need to adjust firewall rules for Reticulum connectivity to and from your device to work. Until proper packaging is ready, you will also need to manually create a service or startup script to automatically laucnh Reticulum at boot time.</p>
|
||||
<p>Please also note that the <cite>AutoInterface</cite> requires link-local IPv6 addresses to be enabled for any Ethernet and WiFi devices you intend to use. If <code class="docutils literal notranslate"><span class="pre">ip</span> <span class="pre">a</span></code> shows an address starting with <code class="docutils literal notranslate"><span class="pre">fe80::</span></code> for the device in question, <code class="docutils literal notranslate"><span class="pre">AutoInterface</span></code> should work for that device.</p>
|
||||
</section>
|
||||
<section id="raspberry-pi">
|
||||
<h3>Raspberry Pi<a class="headerlink" href="#raspberry-pi" title="Link to this heading">¶</a></h3>
|
||||
<p>It is currently recommended to use a 64-bit version of the Raspberry Pi OS
|
||||
if you want to run Reticulum on Raspberry Pi computers, since 32-bit versions
|
||||
don’t always have packages available for some dependencies. If Python and the
|
||||
<cite>pip</cite> package manager is not already installed, do that first, and then
|
||||
install Reticulum using <cite>pip</cite>.</p>
|
||||
<p>It is currently recommended to use a 64-bit version of the Raspberry Pi OS if you want to run Reticulum on Raspberry Pi computers, since 32-bit versions don’t always have packages available for some dependencies. If Python and the <cite>pip</cite> package manager is not already installed, do that first, and then install Reticulum using <cite>pip</cite>.</p>
|
||||
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install dependencies</span>
|
||||
sudo<span class="w"> </span>apt<span class="w"> </span>install<span class="w"> </span>python3<span class="w"> </span>python3-pip<span class="w"> </span>python3-cryptography<span class="w"> </span>python3-pyserial
|
||||
|
||||
@@ -760,21 +614,13 @@ pip<span class="w"> </span>install<span class="w"> </span>rns<span class="w"> </
|
||||
</div>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>The <code class="docutils literal notranslate"><span class="pre">--break-system-packages</span></code> directive is a somewhat misleading choice
|
||||
of words. Setting it will of course not break any system packages, but will simply
|
||||
allow installing <code class="docutils literal notranslate"><span class="pre">pip</span></code> packages user- and system-wide. While this <em>could</em> in rare
|
||||
cases lead to version conflicts, it does not generally pose any problems, especially
|
||||
not in the case of installing Reticulum.</p>
|
||||
<p>The <code class="docutils literal notranslate"><span class="pre">--break-system-packages</span></code> directive is a somewhat misleading choice of words. Setting it will of course not break any system packages, but will simply allow installing <code class="docutils literal notranslate"><span class="pre">pip</span></code> packages user- and system-wide. While this <em>could</em> in rare cases lead to version conflicts, it does not generally pose any problems, especially not in the case of installing Reticulum.</p>
|
||||
</div>
|
||||
<p>While it is possible to install and run Reticulum on 32-bit Rasperry Pi OSes,
|
||||
it will require manually configuring and installing required build dependencies,
|
||||
and is not detailed in this manual.</p>
|
||||
<p>While it is possible to install and run Reticulum on 32-bit Rasperry Pi OSes, it will require manually configuring and installing required build dependencies, and is not detailed in this manual.</p>
|
||||
</section>
|
||||
<section id="risc-v">
|
||||
<h3>RISC-V<a class="headerlink" href="#risc-v" title="Link to this heading">¶</a></h3>
|
||||
<p>On some architectures, including RISC-V, not all dependencies have precompiled
|
||||
binaries. On such systems, you may need to install <code class="docutils literal notranslate"><span class="pre">python3-dev</span></code> (or similar) before
|
||||
installing Reticulum or programs that depend on Reticulum.</p>
|
||||
<p>On some architectures, including RISC-V, not all dependencies have precompiled binaries. On such systems, you may need to install <code class="docutils literal notranslate"><span class="pre">python3-dev</span></code> (or similar) before installing Reticulum or programs that depend on Reticulum.</p>
|
||||
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install Python and development packages</span>
|
||||
sudo<span class="w"> </span>apt<span class="w"> </span>update
|
||||
sudo<span class="w"> </span>apt<span class="w"> </span>install<span class="w"> </span>python3<span class="w"> </span>python3-pip<span class="w"> </span>python3-dev
|
||||
@@ -783,16 +629,11 @@ sudo<span class="w"> </span>apt<span class="w"> </span>install<span class="w"> <
|
||||
python3<span class="w"> </span>-m<span class="w"> </span>pip<span class="w"> </span>install<span class="w"> </span>rns
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>With these packages installed, <code class="docutils literal notranslate"><span class="pre">pip</span></code> will be able to build any missing dependencies
|
||||
on your system locally.</p>
|
||||
<p>With these packages installed, <code class="docutils literal notranslate"><span class="pre">pip</span></code> will be able to build any missing dependencies on your system locally.</p>
|
||||
</section>
|
||||
<section id="ubuntu-lunar">
|
||||
<h3>Ubuntu Lunar<a class="headerlink" href="#ubuntu-lunar" title="Link to this heading">¶</a></h3>
|
||||
<p>On versions of Ubuntu released after April 2023, it is no longer possible by default
|
||||
to use <code class="docutils literal notranslate"><span class="pre">pip</span></code> to install packages onto your system. Unfortunately, you will need to
|
||||
use the replacement <code class="docutils literal notranslate"><span class="pre">pipx</span></code> command instead, which places installed packages in an
|
||||
isolated environment. This should not negatively affect Reticulum, but will not work
|
||||
for including and using Reticulum in your own scripts and programs.</p>
|
||||
<p>On versions of Ubuntu released after April 2023, it is no longer possible by default to use <code class="docutils literal notranslate"><span class="pre">pip</span></code> to install packages onto your system. Unfortunately, you will need to use the replacement <code class="docutils literal notranslate"><span class="pre">pipx</span></code> command instead, which places installed packages in an isolated environment. This should not negatively affect Reticulum, but will not work for including and using Reticulum in your own scripts and programs.</p>
|
||||
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install pipx</span>
|
||||
sudo<span class="w"> </span>apt<span class="w"> </span>install<span class="w"> </span>pipx
|
||||
|
||||
@@ -803,44 +644,30 @@ pipx<span class="w"> </span>ensurepath
|
||||
pipx<span class="w"> </span>install<span class="w"> </span>rns
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Alternatively, you can restore normal behaviour to <code class="docutils literal notranslate"><span class="pre">pip</span></code> by creating or editing
|
||||
the configuration file located at <code class="docutils literal notranslate"><span class="pre">~/.config/pip/pip.conf</span></code>, and adding the
|
||||
following section:</p>
|
||||
<p>Alternatively, you can restore normal behaviour to <code class="docutils literal notranslate"><span class="pre">pip</span></code> by creating or editing the configuration file located at <code class="docutils literal notranslate"><span class="pre">~/.config/pip/pip.conf</span></code>, and adding the following section:</p>
|
||||
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>[global]
|
||||
break-system-packages = true
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>For a one-shot installation of Reticulum, without globally enabling the <code class="docutils literal notranslate"><span class="pre">break-system-packages</span></code>
|
||||
option, you can use the following command:</p>
|
||||
<p>For a one-shot installation of Reticulum, without globally enabling the <code class="docutils literal notranslate"><span class="pre">break-system-packages</span></code> option, you can use the following command:</p>
|
||||
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>pip install rns --break-system-packages
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>The <code class="docutils literal notranslate"><span class="pre">--break-system-packages</span></code> directive is a somewhat misleading choice
|
||||
of words. Setting it will of course not break any system packages, but will simply
|
||||
allow installing <code class="docutils literal notranslate"><span class="pre">pip</span></code> packages user- and system-wide. While this <em>could</em> in rare
|
||||
cases lead to version conflicts, it does not generally pose any problems, especially
|
||||
not in the case of installing Reticulum.</p>
|
||||
<p>The <code class="docutils literal notranslate"><span class="pre">--break-system-packages</span></code> directive is a somewhat misleading choice of words. Setting it will of course not break any system packages, but will simply allow installing <code class="docutils literal notranslate"><span class="pre">pip</span></code> packages user- and system-wide. While this <em>could</em> in rare cases lead to version conflicts, it does not generally pose any problems, especially not in the case of installing Reticulum.</p>
|
||||
</div>
|
||||
</section>
|
||||
<section id="windows">
|
||||
<h3>Windows<a class="headerlink" href="#windows" title="Link to this heading">¶</a></h3>
|
||||
<p>On Windows operating systems, the easiest way to install Reticulum is by using the
|
||||
<code class="docutils literal notranslate"><span class="pre">pip</span></code> package manager from the command line (either the command prompt or Windows
|
||||
Powershell).</p>
|
||||
<p>If you don’t already have Python installed, <a class="reference external" href="https://www.python.org/downloads/">download and install Python</a>.
|
||||
At the time of publication of this manual, the recommended version is <a class="reference external" href="https://www.python.org/downloads/release/python-3127">Python 3.12.7</a>.</p>
|
||||
<p><strong>Important!</strong> When asked by the installer, make sure to add the Python program to
|
||||
your PATH environment variables. If you don’t do this, you will not be able to
|
||||
use the <code class="docutils literal notranslate"><span class="pre">pip</span></code> installer, or run the included Reticulum utility programs (such as
|
||||
<code class="docutils literal notranslate"><span class="pre">rnsd</span></code> and <code class="docutils literal notranslate"><span class="pre">rnstatus</span></code>) from the command line.</p>
|
||||
<p>On Windows operating systems, the easiest way to install Reticulum is by using the <code class="docutils literal notranslate"><span class="pre">pip</span></code> package manager from the command line (either the command prompt or Windows Powershell).</p>
|
||||
<p>If you don’t already have Python installed, <a class="reference external" href="https://www.python.org/downloads/">download and install Python</a>. At the time of publication of this manual, the recommended version is <a class="reference external" href="https://www.python.org/downloads/release/python-3127">Python 3.12.7</a>.</p>
|
||||
<p><strong>Important!</strong> When asked by the installer, make sure to add the Python program to your PATH environment variables. If you don’t do this, you will not be able to use the <code class="docutils literal notranslate"><span class="pre">pip</span></code> installer, or run the included Reticulum utility programs (such as <code class="docutils literal notranslate"><span class="pre">rnsd</span></code> and <code class="docutils literal notranslate"><span class="pre">rnstatus</span></code>) from the command line.</p>
|
||||
<p>After installing Python, open the command prompt or Windows Powershell, and type:</p>
|
||||
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>pip<span class="w"> </span>install<span class="w"> </span>rns
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>You can now use Reticulum and all included utility programs directly from your
|
||||
preferred command line interface.</p>
|
||||
<p>You can now use Reticulum and all included utility programs directly from your preferred command line interface.</p>
|
||||
</section>
|
||||
</section>
|
||||
<section id="pure-python-reticulum">
|
||||
@@ -852,19 +679,8 @@ do not support <a class="reference external" href="https://github.com/pyca/crypt
|
||||
important that you read and understand the <a class="reference internal" href="understanding.html#understanding-primitives"><span class="std std-ref">Cryptographic Primitives</span></a>
|
||||
section of this manual.</p>
|
||||
</div>
|
||||
<p>In some rare cases, and on more obscure system types, it is not possible to
|
||||
install one or more dependencies. In such situations,
|
||||
you can use the <code class="docutils literal notranslate"><span class="pre">rnspure</span></code> package instead of the <code class="docutils literal notranslate"><span class="pre">rns</span></code> package, or use <code class="docutils literal notranslate"><span class="pre">pip</span></code>
|
||||
with the <code class="docutils literal notranslate"><span class="pre">--no-dependencies</span></code> command-line option. The <code class="docutils literal notranslate"><span class="pre">rnspure</span></code>
|
||||
package requires no external dependencies for installation. Please note that the
|
||||
actual contents of the <code class="docutils literal notranslate"><span class="pre">rns</span></code> and <code class="docutils literal notranslate"><span class="pre">rnspure</span></code> packages are <em>completely identical</em>.
|
||||
The only difference is that the <code class="docutils literal notranslate"><span class="pre">rnspure</span></code> package lists no dependencies required
|
||||
for installation.</p>
|
||||
<p>No matter how Reticulum is installed and started, it will load external dependencies
|
||||
only if they are <em>needed</em> and <em>available</em>. If for example you want to use Reticulum
|
||||
on a system that cannot support <code class="docutils literal notranslate"><span class="pre">pyserial</span></code>, it is perfectly possible to do so using
|
||||
the <cite>rnspure</cite> package, but Reticulum will not be able to use serial-based interfaces.
|
||||
All other available modules will still be loaded when needed.</p>
|
||||
<p>In some rare cases, and on more obscure system types, it is not possible to install one or more dependencies. In such situations, you can use the <code class="docutils literal notranslate"><span class="pre">rnspure</span></code> package instead of the <code class="docutils literal notranslate"><span class="pre">rns</span></code> package, or use <code class="docutils literal notranslate"><span class="pre">pip</span></code> with the <code class="docutils literal notranslate"><span class="pre">--no-dependencies</span></code> command-line option. The <code class="docutils literal notranslate"><span class="pre">rnspure</span></code> package requires no external dependencies for installation. Please note that the actual contents of the <code class="docutils literal notranslate"><span class="pre">rns</span></code> and <code class="docutils literal notranslate"><span class="pre">rnspure</span></code> packages are <em>completely identical</em>. The only difference is that the <code class="docutils literal notranslate"><span class="pre">rnspure</span></code> package lists no dependencies required for installation.</p>
|
||||
<p>No matter how Reticulum is installed and started, it will load external dependencies only if they are <em>needed</em> and <em>available</em>. If for example you want to use Reticulum on a system that cannot support <code class="docutils literal notranslate"><span class="pre">pyserial</span></code>, it is perfectly possible to do so using the <cite>rnspure</cite> package, but Reticulum will not be able to use serial-based interfaces. All other available modules will still be loaded when needed.</p>
|
||||
</section>
|
||||
</section>
|
||||
|
||||
|
||||
+11
-28
@@ -1,14 +1,10 @@
|
||||
# Code Examples
|
||||
|
||||
A number of examples are included in the source distribution of Reticulum.
|
||||
You can use these examples to learn how to write your own programs.
|
||||
A number of examples are included in the source distribution of Reticulum. You can use these examples to learn how to write your own programs.
|
||||
|
||||
## Minimal
|
||||
|
||||
The *Minimal* example demonstrates the bare-minimum setup required to connect to
|
||||
a Reticulum network from your program. In about five lines of code, you will
|
||||
have the Reticulum Network Stack initialised, and ready to pass traffic in your
|
||||
program.
|
||||
The *Minimal* example demonstrates the bare-minimum setup required to connect to a Reticulum network from your program. In about five lines of code, you will have the Reticulum Network Stack initialised, and ready to pass traffic in your program.
|
||||
|
||||
```default
|
||||
##########################################################
|
||||
@@ -117,9 +113,7 @@ This example can also be found at [https://github.com/markqvist/Reticulum/blob/m
|
||||
|
||||
## Announce
|
||||
|
||||
The *Announce* example builds upon the previous example by exploring how to
|
||||
announce a destination on the network, and how to let your program receive
|
||||
notifications about announces from relevant destinations.
|
||||
The *Announce* example builds upon the previous example by exploring how to announce a destination on the network, and how to let your program receive notifications about announces from relevant destinations.
|
||||
|
||||
```default
|
||||
##########################################################
|
||||
@@ -299,8 +293,7 @@ This example can also be found at [https://github.com/markqvist/Reticulum/blob/m
|
||||
|
||||
## Broadcast
|
||||
|
||||
The *Broadcast* example explores how to transmit plaintext broadcast messages
|
||||
over the network.
|
||||
The *Broadcast* example explores how to transmit plaintext broadcast messages over the network.
|
||||
|
||||
```default
|
||||
##########################################################
|
||||
@@ -429,8 +422,7 @@ This example can also be found at [https://github.com/markqvist/Reticulum/blob/m
|
||||
|
||||
## Echo
|
||||
|
||||
The *Echo* example demonstrates communication between two destinations using
|
||||
the Packet interface.
|
||||
The *Echo* example demonstrates communication between two destinations using the Packet interface.
|
||||
|
||||
```default
|
||||
##########################################################
|
||||
@@ -766,8 +758,7 @@ This example can also be found at [https://github.com/markqvist/Reticulum/blob/m
|
||||
|
||||
## Link
|
||||
|
||||
The *Link* example explores establishing an encrypted link to a remote
|
||||
destination, and passing traffic back and forth over the link.
|
||||
The *Link* example explores establishing an encrypted link to a remote destination, and passing traffic back and forth over the link.
|
||||
|
||||
```default
|
||||
##########################################################
|
||||
@@ -1064,8 +1055,7 @@ This example can also be found at [https://github.com/markqvist/Reticulum/blob/m
|
||||
|
||||
## Identification
|
||||
|
||||
The *Identify* example explores identifying an intiator of a link, once
|
||||
the link has been established.
|
||||
The *Identify* example explores identifying an intiator of a link, once the link has been established.
|
||||
|
||||
```default
|
||||
##########################################################
|
||||
@@ -1676,8 +1666,7 @@ This example can also be found at [https://github.com/markqvist/Reticulum/blob/m
|
||||
|
||||
## Channel
|
||||
|
||||
The *Channel* example explores using a `Channel` to send structured
|
||||
data between peers of a `Link`.
|
||||
The *Channel* example explores using a `Channel` to send structured data between peers of a `Link`.
|
||||
|
||||
```default
|
||||
##########################################################
|
||||
@@ -2072,8 +2061,7 @@ This example can also be found at [https://github.com/markqvist/Reticulum/blob/m
|
||||
|
||||
## Buffer
|
||||
|
||||
The *Buffer* example explores using buffered readers and writers to send
|
||||
binary data between peers of a `Link`.
|
||||
The *Buffer* example explores using buffered readers and writers to send binary data between peers of a `Link`.
|
||||
|
||||
```default
|
||||
##########################################################
|
||||
@@ -2399,9 +2387,7 @@ This example can also be found at [https://github.com/markqvist/Reticulum/blob/m
|
||||
|
||||
## Filetransfer
|
||||
|
||||
The *Filetransfer* example implements a basic file-server program that
|
||||
allow clients to connect and download files. The program uses the Resource
|
||||
interface to efficiently pass files of any size over a Reticulum [Link](reference.md#api-link).
|
||||
The *Filetransfer* example implements a basic file-server program that allow clients to connect and download files. The program uses the Resource interface to efficiently pass files of any size over a Reticulum [Link](reference.md#api-link).
|
||||
|
||||
```default
|
||||
##########################################################
|
||||
@@ -3010,10 +2996,7 @@ This example can also be found at [https://github.com/markqvist/Reticulum/blob/m
|
||||
|
||||
## Custom Interfaces
|
||||
|
||||
The *ExampleInterface* demonstrates creating custom interfaces for Reticulum.
|
||||
Any number of custom interfaces can be loaded and utilised by Reticulum, and
|
||||
will be fully on-par with natively included interfaces, including all supported
|
||||
[interface modes](interfaces.md#interfaces-modes) and [common configuration options](interfaces.md#interfaces-options).
|
||||
The *ExampleInterface* demonstrates creating custom interfaces for Reticulum. Any number of custom interfaces can be loaded and utilised by Reticulum, and will be fully on-par with natively included interfaces, including all supported [interface modes](interfaces.md#interfaces-modes) and [common configuration options](interfaces.md#interfaces-options).
|
||||
|
||||
```default
|
||||
# This example illustrates creating a custom interface
|
||||
|
||||
@@ -1,49 +1,36 @@
|
||||
# Getting Started Fast
|
||||
|
||||
The best way to get started with the Reticulum Network Stack depends on what
|
||||
you want to do. This guide will outline sensible starting paths for different
|
||||
scenarios.
|
||||
The best way to get started with the Reticulum Network Stack depends on what you want to do. This guide will outline sensible starting paths for different scenarios.
|
||||
|
||||
## Standalone Reticulum Installation
|
||||
|
||||
If you simply want to install Reticulum and related utilities on a system,
|
||||
the easiest way is via the `pip` package manager:
|
||||
If you simply want to install Reticulum and related utilities on a system, the easiest way is via the `pip` package manager:
|
||||
|
||||
```shell
|
||||
pip install rns
|
||||
```
|
||||
|
||||
If you do not already have pip installed, you can install it using the package manager
|
||||
of your system with a command like `sudo apt install python3-pip`,
|
||||
`sudo pamac install python-pip` or similar.
|
||||
If you do not already have pip installed, you can install it using the package manager of your system with a command like `sudo apt install python3-pip`, `sudo pamac install python-pip` or similar.
|
||||
|
||||
You can also dowload the Reticulum release wheels from GitHub, or other release channels,
|
||||
and install them offline using `pip`:
|
||||
You can also dowload the Reticulum release wheels from GitHub, or other release channels, and install them offline using `pip`:
|
||||
|
||||
```shell
|
||||
pip install ./rns-1.1.2-py3-none-any.whl
|
||||
```
|
||||
|
||||
On platforms that limit user package installation via `pip`, you may need to manually
|
||||
allow this using the `--break-system-packages` command line flag when installing. This
|
||||
will not actually break any packages, unless you have installed Reticulum directly via
|
||||
your operating system’s package manager.
|
||||
On platforms that limit user package installation via `pip`, you may need to manually allow this using the `--break-system-packages` command line flag when installing. This will not actually break any packages, unless you have installed Reticulum directly via your operating system’s package manager.
|
||||
|
||||
```shell
|
||||
pip install rns --break-system-packages
|
||||
```
|
||||
|
||||
For more detailed installation instructions, please see the
|
||||
[Platform-Specific Install Notes](#install-guides) section.
|
||||
For more detailed installation instructions, please see the [Platform-Specific Install Notes](#install-guides) section.
|
||||
|
||||
After installation is complete, it might be helpful to refer to the
|
||||
[Using Reticulum on Your System](using.md#using-main) chapter.
|
||||
After installation is complete, it might be helpful to refer to the [Using Reticulum on Your System](using.md#using-main) chapter.
|
||||
|
||||
### Resolving Dependency & Installation Issues
|
||||
|
||||
On some platforms, there may not be binary packages available for all dependencies, and
|
||||
`pip` installation may fail with an error message. In these cases, the issue can usually
|
||||
be resolved by installing the development essentials packages for your platform:
|
||||
On some platforms, there may not be binary packages available for all dependencies, and `pip` installation may fail with an error message. In these cases, the issue can usually be resolved by installing the development essentials packages for your platform:
|
||||
|
||||
```shell
|
||||
# Debian / Ubuntu / Derivatives
|
||||
@@ -56,66 +43,35 @@ sudo pamac install base-devel
|
||||
sudo dnf groupinstall "Development Tools" "Development Libraries"
|
||||
```
|
||||
|
||||
With the base development packages installed, `pip` should be able to compile any missing
|
||||
dependencies from source, and complete installation even on platforms that don’t have pre-
|
||||
compiled packages available.
|
||||
With the base development packages installed, `pip` should be able to compile any missing dependencies from source, and complete installation even on platforms that don’t have pre-compiled packages available.
|
||||
|
||||
## Try Using a Reticulum-based Program
|
||||
|
||||
If you simply want to try using a program built with Reticulum, a [range of different
|
||||
programs](software.md#software-main) exist that allow basic communication and a various other useful functions,
|
||||
even over extremely low-bandwidth Reticulum networks.
|
||||
If you simply want to try using a program built with Reticulum, a [range of different programs](software.md#software-main) exist that allow basic communication and a various other useful functions, even over extremely low-bandwidth Reticulum networks.
|
||||
|
||||
## Using the Included Utilities
|
||||
|
||||
Reticulum comes with a range of included utilities that make it easier to
|
||||
manage your network, check connectivity and make Reticulum available to other
|
||||
programs on your system.
|
||||
Reticulum comes with a range of included utilities that make it easier to manage your network, check connectivity and make Reticulum available to other programs on your system.
|
||||
|
||||
You can use `rnsd` to run Reticulum as a background or foreground service,
|
||||
and the `rnstatus`, `rnpath` and `rnprobe` utilities to view and query
|
||||
network status and connectivity.
|
||||
You can use `rnsd` to run Reticulum as a background or foreground service, and the `rnstatus`, `rnpath` and `rnprobe` utilities to view and query network status and connectivity.
|
||||
|
||||
To learn more about these utility programs, have a look at the
|
||||
[Using Reticulum on Your System](using.md#using-main) chapter of this manual.
|
||||
To learn more about these utility programs, have a look at the [Using Reticulum on Your System](using.md#using-main) chapter of this manual.
|
||||
|
||||
## Creating a Network With Reticulum
|
||||
|
||||
To create a network, you will need to specify one or more *interfaces* for
|
||||
Reticulum to use. This is done in the Reticulum configuration file, which by
|
||||
default is located at `~/.reticulum/config`. You can get an example
|
||||
configuration file with all options via `rnsd --exampleconfig`.
|
||||
To create a network, you will need to specify one or more *interfaces* for Reticulum to use. This is done in the Reticulum configuration file, which by default is located at `~/.reticulum/config`. You can get an example configuration file with all options via `rnsd --exampleconfig`.
|
||||
|
||||
When Reticulum is started for the first time, it will create a default
|
||||
configuration file, with one active interface. This default interface uses
|
||||
your existing Ethernet and WiFi networks (if any), and only allows you to
|
||||
communicate with other Reticulum peers within your local broadcast domains.
|
||||
When Reticulum is started for the first time, it will create a default configuration file, with one active interface. This default interface uses your existing Ethernet and WiFi networks (if any), and only allows you to communicate with other Reticulum peers within your local broadcast domains.
|
||||
|
||||
To communicate further, you will have to add one or more interfaces. The default
|
||||
configuration includes a number of examples, ranging from using TCP over the
|
||||
internet, to LoRa and Packet Radio interfaces.
|
||||
To communicate further, you will have to add one or more interfaces. The default configuration includes a number of examples, ranging from using TCP over the internet, to LoRa and Packet Radio interfaces.
|
||||
|
||||
With Reticulum, you only need to configure what interfaces you want to communicate
|
||||
over. There is no need to configure address spaces, subnets, routing tables,
|
||||
or other things you might be used to from other network types.
|
||||
With Reticulum, you only need to configure what interfaces you want to communicate over. There is no need to configure address spaces, subnets, routing tables, or other things you might be used to from other network types.
|
||||
|
||||
Once Reticulum knows which interfaces it should use, it will automatically
|
||||
discover topography and configure transport of data to any destinations it
|
||||
knows about.
|
||||
Once Reticulum knows which interfaces it should use, it will automatically discover topography and configure transport of data to any destinations it knows about.
|
||||
|
||||
In situations where you already have an established WiFi or Ethernet network, and
|
||||
many devices that want to utilise the same external Reticulum network paths (for example over
|
||||
LoRa), it will often be sufficient to let one system act as a Reticulum gateway, by
|
||||
adding any external interfaces to the configuration of this system, and then enabling transport on it. Any
|
||||
other device on your local WiFi will then be able to connect to this wider Reticulum
|
||||
network just using the default ([AutoInterface](interfaces.md#interfaces-auto)) configuration.
|
||||
In situations where you already have an established WiFi or Ethernet network, and many devices that want to utilise the same external Reticulum network paths (for example over LoRa), it will often be sufficient to let one system act as a Reticulum gateway, by adding any external interfaces to the configuration of this system, and then enabling transport on it. Any other device on your local WiFi will then be able to connect to this wider Reticulum network just using the default ([AutoInterface](interfaces.md#interfaces-auto)) configuration.
|
||||
|
||||
Possibly, the examples in the config file are enough to get you started. If
|
||||
you want more information, you can read the [Building Networks](networks.md#networks-main)
|
||||
and [Interfaces](interfaces.md#interfaces-main) chapters of this manual, but most importantly,
|
||||
start with reading the next section, [Bootstrapping Connectivity](#bootstrapping-connectivity),
|
||||
as this provides the most essential understanding of how to ensure reliable
|
||||
connectivity with a minimum of maintenance.
|
||||
Possibly, the examples in the config file are enough to get you started. If you want more information, you can read the [Building Networks](networks.md#networks-main) and [Interfaces](interfaces.md#interfaces-main) chapters of this manual, but most importantly, start with reading the next section, [Bootstrapping Connectivity](#bootstrapping-connectivity), as this provides the most essential understanding of how to ensure reliable connectivity with a minimum of maintenance.
|
||||
|
||||
## Bootstrapping Connectivity
|
||||
|
||||
@@ -188,20 +144,13 @@ As a good starting point, you can find interface definitions for connecting your
|
||||
|
||||
## Hosting Public Entrypoints
|
||||
|
||||
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
|
||||
Internet. This section offers some helpful pointers. Once you have set up your public entrypoint, it is a great idea to [make it discoverable over Reticulum](interfaces.md#interfaces-discoverable).
|
||||
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 Internet. This section offers some helpful pointers. Once you have set up your public entrypoint, it is a great idea to [make it discoverable over Reticulum](interfaces.md#interfaces-discoverable).
|
||||
|
||||
You will need a machine, physical or virtual with a public IP address, that can be reached by other devices on the Internet.
|
||||
|
||||
The most efficient and performant way to host a connectable entry-point supporting many
|
||||
users is to use the `BackboneInterface`. This interface type is fully compatible with
|
||||
the `TCPClientInterface` and `TCPServerInterface` types, but much faster and uses
|
||||
less system resources, allowing your device to handle thousands of connections even on
|
||||
small systems.
|
||||
The most efficient and performant way to host a connectable entry-point supporting many users is to use the `BackboneInterface`. This interface type is fully compatible with the `TCPClientInterface` and `TCPServerInterface` types, but much faster and uses less system resources, allowing your device to handle thousands of connections even on small systems.
|
||||
|
||||
It is also important to set your connectable interface to `gateway` mode, since this
|
||||
will greatly improve network convergence time and path resolution for anyone connecting
|
||||
to your entry-point.
|
||||
It is also important to set your connectable interface to `gateway` mode, since this will greatly improve network convergence time and path resolution for anyone connecting to your entry-point.
|
||||
|
||||
```ini
|
||||
# This example demonstrates a backbone interface
|
||||
@@ -223,8 +172,7 @@ to your entry-point.
|
||||
announce_rate_grace = 6
|
||||
```
|
||||
|
||||
If instead you want to make a private entry-point from the Internet, you can use the
|
||||
[IFAC name and passphrase options](interfaces.md#interfaces-options) to secure your interface with a network name and passphrase.
|
||||
If instead you want to make a private entry-point from the Internet, you can use the [IFAC name and passphrase options](interfaces.md#interfaces-options) to secure your interface with a network name and passphrase.
|
||||
|
||||
```ini
|
||||
# A private entry-point requiring a pre-shared
|
||||
@@ -240,124 +188,71 @@ If instead you want to make a private entry-point from the Internet, you can use
|
||||
passphrase = 2owjajquafIanPecAc
|
||||
```
|
||||
|
||||
If you are hosting an entry-point on an operating system that does not support
|
||||
`BackboneInterface`, you can use `TCPServerInterface` instead, although it will
|
||||
not be as performant.
|
||||
If you are hosting an entry-point on an operating system that does not support `BackboneInterface`, you can use `TCPServerInterface` instead, although it will not be as performant.
|
||||
|
||||
## Connecting Reticulum Instances Over the Internet
|
||||
|
||||
Reticulum currently offers three interfaces suitable for connecting instances over the Internet: [Backbone](interfaces.md#interfaces-backbone), [TCP](interfaces.md#interfaces-tcps)
|
||||
and [I2P](interfaces.md#interfaces-i2p). Each interface offers a different set of features, and Reticulum
|
||||
users should carefully choose the interface which best suites their needs.
|
||||
Reticulum currently offers three interfaces suitable for connecting instances over the Internet: [Backbone](interfaces.md#interfaces-backbone), [TCP](interfaces.md#interfaces-tcps) and [I2P](interfaces.md#interfaces-i2p). Each interface offers a different set of features, and Reticulum users should carefully choose the interface which best suites their needs.
|
||||
|
||||
The `TCPServerInterface` allows users to host an instance accessible over TCP/IP. This
|
||||
method is generally faster, lower latency, and more energy efficient than using `I2PInterface`,
|
||||
however it also leaks more data about the server host.
|
||||
The `TCPServerInterface` allows users to host an instance accessible over TCP/IP. This method is generally faster, lower latency, and more energy efficient than using `I2PInterface`, however it also leaks more data about the server host.
|
||||
|
||||
The `BackboneInterface` is a very fast and efficient interface type available on POSIX operating
|
||||
systems, designed to handle thousands of connections simultaneously with low memory, processing
|
||||
and I/O overhead. It is fully compatible with the TCP-based interface types.
|
||||
The `BackboneInterface` is a very fast and efficient interface type available on POSIX operating systems, designed to handle thousands of connections simultaneously with low memory, processing and I/O overhead. It is fully compatible with the TCP-based interface types.
|
||||
|
||||
TCP connections reveal the IP address of both your instance and the server to anyone who can
|
||||
inspect the connection. Someone could use this information to determine your location or identity. Adversaries
|
||||
inspecting your packets may be able to record packet metadata like time of transmission and packet size.
|
||||
Even though Reticulum encrypts traffic, TCP does not, so an adversary may be able to use
|
||||
packet inspection to learn that a system is running Reticulum, and what other IP addresses connect to it.
|
||||
Hosting a publicly reachable instance over TCP also requires a publicly reachable IP address,
|
||||
which most Internet connections don’t offer anymore.
|
||||
TCP connections reveal the IP address of both your instance and the server to anyone who can inspect the connection. Someone could use this information to determine your location or identity. Adversaries inspecting your packets may be able to record packet metadata like time of transmission and packet size. Even though Reticulum encrypts traffic, TCP does not, so an adversary may be able to use packet inspection to learn that a system is running Reticulum, and what other IP addresses connect to it. Hosting a publicly reachable instance over TCP also requires a publicly reachable IP address, which most Internet connections don’t offer anymore.
|
||||
|
||||
The `I2PInterface` routes messages through the [Invisible Internet Protocol
|
||||
(I2P)](https://geti2p.net/en/). To use this interface, users must also run an I2P daemon in
|
||||
parallel to `rnsd`. For always-on I2P nodes it is recommended to use [i2pd](https://i2pd.website/).
|
||||
The `I2PInterface` routes messages through the [Invisible Internet Protocol (I2P)](https://geti2p.net/en/). To use this interface, users must also run an I2P daemon in parallel to `rnsd`. For always-on I2P nodes it is recommended to use [i2pd](https://i2pd.website/).
|
||||
|
||||
By default, I2P will encrypt and mix all traffic sent over the Internet, and
|
||||
hide both the sender and receiver Reticulum instance IP addresses. Running an I2P node
|
||||
will also relay other I2P user’s encrypted packets, which will use extra
|
||||
bandwidth and compute power, but also makes timing attacks and other forms of
|
||||
deep-packet-inspection much more difficult.
|
||||
By default, I2P will encrypt and mix all traffic sent over the Internet, and hide both the sender and receiver Reticulum instance IP addresses. Running an I2P node will also relay other I2P user’s encrypted packets, which will use extra bandwidth and compute power, but also makes timing attacks and other forms of deep-packet-inspection much more difficult.
|
||||
|
||||
I2P also allows users to host globally available Reticulum instances from non-public IP’s and behind firewalls and NAT.
|
||||
|
||||
In general it is recommended to use an I2P node if you want to host a publicly accessible
|
||||
instance, while preserving anonymity. If you care more about performance, and a slightly
|
||||
easier setup, use TCP.
|
||||
In general it is recommended to use an I2P node if you want to host a publicly accessible instance, while preserving anonymity. If you care more about performance, and a slightly easier setup, use TCP.
|
||||
|
||||
## Adding Radio Interfaces
|
||||
|
||||
Once you have Reticulum installed and working, you can add radio interfaces with
|
||||
any compatible hardware you have available. Reticulum supports a wide range of radio
|
||||
hardware, and if you already have any available, it is very likely that it will
|
||||
work with Reticulum. For information on how to configure this, see the
|
||||
[Interfaces](interfaces.md#interfaces-main) section of this manual.
|
||||
Once you have Reticulum installed and working, you can add radio interfaces with any compatible hardware you have available. Reticulum supports a wide range of radio hardware, and if you already have any available, it is very likely that it will work with Reticulum. For information on how to configure this, see the [Interfaces](interfaces.md#interfaces-main) section of this manual.
|
||||
|
||||
If you do not already have transceiver hardware available, you can easily and
|
||||
cheaply build an [RNode](hardware.md#rnode-main), which is a general-purpose long-range
|
||||
digital radio transceiver, that integrates easily with Reticulum.
|
||||
If you do not already have transceiver hardware available, you can easily and cheaply build an [RNode](hardware.md#rnode-main), which is a general-purpose long-range digital radio transceiver, that integrates easily with Reticulum.
|
||||
|
||||
To build one yourself requires installing a custom firmware on a supported LoRa
|
||||
development board with an auto-install script or web-based flasher.
|
||||
Please see the [Communications Hardware](hardware.md#hardware-main) chapter for a guide.
|
||||
If you prefer purchasing a ready-made unit, you can refer to the
|
||||
list of suppliers.
|
||||
To build one yourself requires installing a custom firmware on a supported LoRa development board with an auto-install script or web-based flasher. Please see the [Communications Hardware](hardware.md#hardware-main) chapter for a guide. If you prefer purchasing a ready-made unit, you can refer to the list of suppliers.
|
||||
|
||||
Other radio-based hardware interfaces are being developed and made available by
|
||||
the broader Reticulum community. You can find more information on such topics
|
||||
over Reticulum-based information sharing systems.
|
||||
Other radio-based hardware interfaces are being developed and made available by the broader Reticulum community. You can find more information on such topics over Reticulum-based information sharing systems.
|
||||
|
||||
If you have communications hardware that is not already supported by any of the
|
||||
[existing interface types](interfaces.md#interfaces-main), it is easy to write (and potentially
|
||||
publish) a [custom interface module](interfaces.md#interfaces-custom) that makes it compatible with Reticulum.
|
||||
If you have communications hardware that is not already supported by any of the [existing interface types](interfaces.md#interfaces-main), it is easy to write (and potentially publish) a [custom interface module](interfaces.md#interfaces-custom) that makes it compatible with Reticulum.
|
||||
|
||||
## Creating and Using Custom Interfaces
|
||||
|
||||
While Reticulum includes a flexible and broad range of built-in interfaces, these
|
||||
will not cover every conceivable type of communications hardware that Reticulum
|
||||
can potentially use to communicate.
|
||||
While Reticulum includes a flexible and broad range of built-in interfaces, these will not cover every conceivable type of communications hardware that Reticulum can potentially use to communicate.
|
||||
|
||||
It is therefore possible to easily write your own interface modules, that can be
|
||||
loaded at run-time and used on-par with any of the built-in interface types.
|
||||
It is therefore possible to easily write your own interface modules, that can be loaded at run-time and used on-par with any of the built-in interface types.
|
||||
|
||||
For more information on this subject, and code examples to build on, please see
|
||||
the [Configuring Interfaces](interfaces.md#interfaces-main) chapter.
|
||||
For more information on this subject, and code examples to build on, please see the [Configuring Interfaces](interfaces.md#interfaces-main) chapter.
|
||||
|
||||
## Develop a Program with Reticulum
|
||||
|
||||
If you want to develop programs that use Reticulum, the easiest way to get
|
||||
started is to install the latest release of Reticulum via pip:
|
||||
If you want to develop programs that use Reticulum, the easiest way to get started is to install the latest release of Reticulum via pip:
|
||||
|
||||
```default
|
||||
pip install rns
|
||||
```
|
||||
|
||||
The above command will install Reticulum and dependencies, and you will be
|
||||
ready to import and use RNS in your own programs. The next step will most
|
||||
likely be to look at some [Example Programs](examples.md#examples-main).
|
||||
The above command will install Reticulum and dependencies, and you will be ready to import and use RNS in your own programs. The next step will most likely be to look at some [Example Programs](examples.md#examples-main).
|
||||
|
||||
The entire Reticulum API is documented in the [API Reference](reference.md#api-main)
|
||||
chapter of this manual. Before diving in, it’s probably a good idea to read
|
||||
this manual in full, but at least start with the [Understanding Reticulum](understanding.md#understanding-main) chapter.
|
||||
The entire Reticulum API is documented in the [API Reference](reference.md#api-main) chapter of this manual. Before diving in, it’s probably a good idea to read this manual in full, but at least start with the [Understanding Reticulum](understanding.md#understanding-main) chapter.
|
||||
|
||||
## Platform-Specific Install Notes
|
||||
|
||||
Some platforms require a slightly different installation procedure, or have
|
||||
various quirks that are worth being aware of. These are listed here.
|
||||
Some platforms require a slightly different installation procedure, or have various quirks that are worth being aware of. These are listed here.
|
||||
|
||||
### Android
|
||||
|
||||
Reticulum can be used on Android in different ways. The easiest way to get
|
||||
started is using an app like [Sideband](https://unsigned.io/sideband).
|
||||
Reticulum can be used on Android in different ways. The easiest way to get started is using an app like [Sideband](https://unsigned.io/sideband).
|
||||
|
||||
For more control and features, you can use Reticulum and related programs via
|
||||
the [Termux app](https://termux.com/), at the time of writing available on
|
||||
[F-droid](https://f-droid.org).
|
||||
For more control and features, you can use Reticulum and related programs via the [Termux app](https://termux.com/), at the time of writing available on [F-droid](https://f-droid.org).
|
||||
|
||||
Termux is a terminal emulator and Linux environment for Android based devices,
|
||||
which includes the ability to use many different programs and libraries,
|
||||
including Reticulum.
|
||||
Termux is a terminal emulator and Linux environment for Android based devices, which includes the ability to use many different programs and libraries, including Reticulum.
|
||||
|
||||
To use Reticulum within the Termux environment, you will need to install
|
||||
`python` and the `python-cryptography` library using `pkg`, the package-manager
|
||||
build into Termux. After that, you can use `pip` to install Reticulum.
|
||||
To use Reticulum within the Termux environment, you will need to install `python` and the `python-cryptography` library using `pkg`, the package-manager build into Termux. After that, you can use `pip` to install Reticulum.
|
||||
|
||||
From within Termux, execute the following:
|
||||
|
||||
@@ -376,9 +271,7 @@ pip install wheel pip --upgrade
|
||||
pip install rns
|
||||
```
|
||||
|
||||
If for some reason the `python-cryptography` package is not available for
|
||||
your platform via the Termux package manager, you can attempt to build it
|
||||
locally on your device using the following command:
|
||||
If for some reason the `python-cryptography` package is not available for your platform via the Termux package manager, you can attempt to build it locally on your device using the following command:
|
||||
|
||||
```shell
|
||||
# First, make sure indexes and packages are up to date.
|
||||
@@ -405,15 +298,11 @@ pip install cryptography
|
||||
pip install rns
|
||||
```
|
||||
|
||||
It is also possible to include Reticulum in apps compiled and distributed as
|
||||
Android APKs. A detailed tutorial and example source code will be included
|
||||
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.
|
||||
It is also possible to include Reticulum in apps compiled and distributed as Android APKs. A detailed tutorial and example source code will be included 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.
|
||||
|
||||
### ARM64
|
||||
|
||||
On some architectures, including ARM64, not all dependencies have precompiled
|
||||
binaries. On such systems, you may need to install `python3-dev` (or similar) before
|
||||
installing Reticulum or programs that depend on Reticulum.
|
||||
On some architectures, including ARM64, not all dependencies have precompiled binaries. On such systems, you may need to install `python3-dev` (or similar) before installing Reticulum or programs that depend on Reticulum.
|
||||
|
||||
```shell
|
||||
# Install Python and development packages
|
||||
@@ -429,11 +318,7 @@ on your system locally.
|
||||
|
||||
### Debian Bookworm
|
||||
|
||||
On versions of Debian released after April 2023, it is no longer possible by default
|
||||
to use `pip` to install packages onto your system. Unfortunately, you will need to
|
||||
use the replacement `pipx` command instead, which places installed packages in an
|
||||
isolated environment. This should not negatively affect Reticulum, but will not work
|
||||
for including and using Reticulum in your own scripts and programs.
|
||||
On versions of Debian released after April 2023, it is no longer possible by default to use `pip` to install packages onto your system. Unfortunately, you will need to use the replacement `pipx` command instead, which places installed packages in an isolated environment. This should not negatively affect Reticulum, but will not work for including and using Reticulum in your own scripts and programs.
|
||||
|
||||
```shell
|
||||
# Install pipx
|
||||
@@ -446,17 +331,14 @@ pipx ensurepath
|
||||
pipx install rns
|
||||
```
|
||||
|
||||
Alternatively, you can restore normal behaviour to `pip` by creating or editing
|
||||
the configuration file located at `~/.config/pip/pip.conf`, and adding the
|
||||
following section:
|
||||
Alternatively, you can restore normal behaviour to `pip` by creating or editing the configuration file located at `~/.config/pip/pip.conf`, and adding the following section:
|
||||
|
||||
```ini
|
||||
[global]
|
||||
break-system-packages = true
|
||||
```
|
||||
|
||||
For a one-shot installation of Reticulum, without globally enabling the `break-system-packages`
|
||||
option, you can use the following command:
|
||||
For a one-shot installation of Reticulum, without globally enabling the `break-system-packages` option, you can use the following command:
|
||||
|
||||
```shell
|
||||
pip install rns --break-system-packages
|
||||
@@ -471,16 +353,11 @@ not in the case of installing Reticulum.
|
||||
|
||||
### MacOS
|
||||
|
||||
To install Reticulum on macOS, you will need to have Python and the `pip` package
|
||||
manager installed.
|
||||
To install Reticulum on macOS, you will need to have Python and the `pip` package manager installed.
|
||||
|
||||
Systems running macOS can vary quite widely in whether or not Python is pre-installed,
|
||||
and if it is, which version is installed, and whether the `pip` package manager is
|
||||
also installed and set up. If in doubt, you can [download and install](https://www.python.org/downloads/)
|
||||
Python manually.
|
||||
Systems running macOS can vary quite widely in whether or not Python is pre-installed, and if it is, which version is installed, and whether the `pip` package manager is also installed and set up. If in doubt, you can [download and install](https://www.python.org/downloads/) Python manually.
|
||||
|
||||
When Python and `pip` is available on your system, simply open a terminal window
|
||||
and use one of the following commands:
|
||||
When Python and `pip` is available on your system, simply open a terminal window and use one of the following commands:
|
||||
|
||||
```shell
|
||||
# Install Reticulum and utilities with pip:
|
||||
@@ -492,16 +369,9 @@ pip3 install rns --break-system-packages
|
||||
```
|
||||
|
||||
#### NOTE
|
||||
The `--break-system-packages` directive is a somewhat misleading choice
|
||||
of words. Setting it will of course not break any system packages, but will simply
|
||||
allow installing `pip` packages user- and system-wide. While this *could* in rare
|
||||
cases lead to version conflicts, it does not generally pose any problems, especially
|
||||
not in the case of installing Reticulum.
|
||||
The `--break-system-packages` directive is a somewhat misleading choice of words. Setting it will of course not break any system packages, but will simply allow installing `pip` packages user- and system-wide. While this *could* in rare cases lead to version conflicts, it does not generally pose any problems, especially not in the case of installing Reticulum.
|
||||
|
||||
Additionally, some version combinations of macOS and Python require you to
|
||||
manually add your installed `pip` packages directory to your PATH environment
|
||||
variable, before you can use installed commands in your terminal. Usually, adding
|
||||
the following line to your shell init script (for example `~/.zshrc`) will be enough:
|
||||
Additionally, some version combinations of macOS and Python require you to manually add your installed `pip` packages directory to your PATH environment variable, before you can use installed commands in your terminal. Usually, adding the following line to your shell init script (for example `~/.zshrc`) will be enough:
|
||||
|
||||
```shell
|
||||
export PATH=$PATH:~/Library/Python/3.9/bin
|
||||
@@ -511,8 +381,7 @@ Adjust Python version and shell init script location according to your system.
|
||||
|
||||
### OpenWRT
|
||||
|
||||
On OpenWRT systems with sufficient storage and memory, you can install
|
||||
Reticulum and related utilities using the opkg package manager and pip.
|
||||
On OpenWRT systems with sufficient storage and memory, you can install Reticulum and related utilities using the opkg package manager and pip.
|
||||
|
||||
#### NOTE
|
||||
At the time of releasing this manual, work is underway to create pre-built
|
||||
@@ -521,8 +390,7 @@ and `uci` integration. Please see the [feed-reticulum](https://github.com/gretel
|
||||
and [reticulum-openwrt](https://github.com/gretel/reticulum-openwrt)
|
||||
repositories for more information.
|
||||
|
||||
To install Reticulum on OpenWRT, first log into a command line session, and
|
||||
then use the following instructions:
|
||||
To install Reticulum on OpenWRT, first log into a command line session, and then use the following instructions:
|
||||
|
||||
```shell
|
||||
# Install dependencies
|
||||
@@ -536,29 +404,15 @@ rnsd -vvv
|
||||
```
|
||||
|
||||
#### NOTE
|
||||
The above instructions have been verified and tested on OpenWRT 21.02 only.
|
||||
It is likely that other versions may require slightly altered installation
|
||||
commands or package names. You will also need enough free space in your
|
||||
overlay FS, and enough free RAM to actually run Reticulum and any related
|
||||
programs and utilities.
|
||||
The above instructions have been verified and tested on OpenWRT 21.02 only. It is likely that other versions may require slightly altered installation commands or package names. You will also need enough free space in your overlay FS, and enough free RAM to actually run Reticulum and any related programs and utilities.
|
||||
|
||||
Depending on your device configuration, you may need to adjust firewall rules
|
||||
for Reticulum connectivity to and from your device to work. Until proper
|
||||
packaging is ready, you will also need to manually create a service or startup
|
||||
script to automatically laucnh Reticulum at boot time.
|
||||
Depending on your device configuration, you may need to adjust firewall rules for Reticulum connectivity to and from your device to work. Until proper packaging is ready, you will also need to manually create a service or startup script to automatically laucnh Reticulum at boot time.
|
||||
|
||||
Please also note that the AutoInterface requires link-local IPv6 addresses
|
||||
to be enabled for any Ethernet and WiFi devices you intend to use. If `ip a`
|
||||
shows an address starting with `fe80::` for the device in question,
|
||||
`AutoInterface` should work for that device.
|
||||
Please also note that the AutoInterface requires link-local IPv6 addresses to be enabled for any Ethernet and WiFi devices you intend to use. If `ip a` shows an address starting with `fe80::` for the device in question, `AutoInterface` should work for that device.
|
||||
|
||||
### Raspberry Pi
|
||||
|
||||
It is currently recommended to use a 64-bit version of the Raspberry Pi OS
|
||||
if you want to run Reticulum on Raspberry Pi computers, since 32-bit versions
|
||||
don’t always have packages available for some dependencies. If Python and the
|
||||
pip package manager is not already installed, do that first, and then
|
||||
install Reticulum using pip.
|
||||
It is currently recommended to use a 64-bit version of the Raspberry Pi OS if you want to run Reticulum on Raspberry Pi computers, since 32-bit versions don’t always have packages available for some dependencies. If Python and the pip package manager is not already installed, do that first, and then install Reticulum using pip.
|
||||
|
||||
```shell
|
||||
# Install dependencies
|
||||
@@ -569,21 +423,13 @@ pip install rns --break-system-packages
|
||||
```
|
||||
|
||||
#### NOTE
|
||||
The `--break-system-packages` directive is a somewhat misleading choice
|
||||
of words. Setting it will of course not break any system packages, but will simply
|
||||
allow installing `pip` packages user- and system-wide. While this *could* in rare
|
||||
cases lead to version conflicts, it does not generally pose any problems, especially
|
||||
not in the case of installing Reticulum.
|
||||
The `--break-system-packages` directive is a somewhat misleading choice of words. Setting it will of course not break any system packages, but will simply allow installing `pip` packages user- and system-wide. While this *could* in rare cases lead to version conflicts, it does not generally pose any problems, especially not in the case of installing Reticulum.
|
||||
|
||||
While it is possible to install and run Reticulum on 32-bit Rasperry Pi OSes,
|
||||
it will require manually configuring and installing required build dependencies,
|
||||
and is not detailed in this manual.
|
||||
While it is possible to install and run Reticulum on 32-bit Rasperry Pi OSes, it will require manually configuring and installing required build dependencies, and is not detailed in this manual.
|
||||
|
||||
### RISC-V
|
||||
|
||||
On some architectures, including RISC-V, not all dependencies have precompiled
|
||||
binaries. On such systems, you may need to install `python3-dev` (or similar) before
|
||||
installing Reticulum or programs that depend on Reticulum.
|
||||
On some architectures, including RISC-V, not all dependencies have precompiled binaries. On such systems, you may need to install `python3-dev` (or similar) before installing Reticulum or programs that depend on Reticulum.
|
||||
|
||||
```shell
|
||||
# Install Python and development packages
|
||||
@@ -594,16 +440,11 @@ sudo apt install python3 python3-pip python3-dev
|
||||
python3 -m pip install rns
|
||||
```
|
||||
|
||||
With these packages installed, `pip` will be able to build any missing dependencies
|
||||
on your system locally.
|
||||
With these packages installed, `pip` will be able to build any missing dependencies on your system locally.
|
||||
|
||||
### Ubuntu Lunar
|
||||
|
||||
On versions of Ubuntu released after April 2023, it is no longer possible by default
|
||||
to use `pip` to install packages onto your system. Unfortunately, you will need to
|
||||
use the replacement `pipx` command instead, which places installed packages in an
|
||||
isolated environment. This should not negatively affect Reticulum, but will not work
|
||||
for including and using Reticulum in your own scripts and programs.
|
||||
On versions of Ubuntu released after April 2023, it is no longer possible by default to use `pip` to install packages onto your system. Unfortunately, you will need to use the replacement `pipx` command instead, which places installed packages in an isolated environment. This should not negatively affect Reticulum, but will not work for including and using Reticulum in your own scripts and programs.
|
||||
|
||||
```shell
|
||||
# Install pipx
|
||||
@@ -616,42 +457,29 @@ pipx ensurepath
|
||||
pipx install rns
|
||||
```
|
||||
|
||||
Alternatively, you can restore normal behaviour to `pip` by creating or editing
|
||||
the configuration file located at `~/.config/pip/pip.conf`, and adding the
|
||||
following section:
|
||||
Alternatively, you can restore normal behaviour to `pip` by creating or editing the configuration file located at `~/.config/pip/pip.conf`, and adding the following section:
|
||||
|
||||
```text
|
||||
[global]
|
||||
break-system-packages = true
|
||||
```
|
||||
|
||||
For a one-shot installation of Reticulum, without globally enabling the `break-system-packages`
|
||||
option, you can use the following command:
|
||||
For a one-shot installation of Reticulum, without globally enabling the `break-system-packages` option, you can use the following command:
|
||||
|
||||
```text
|
||||
pip install rns --break-system-packages
|
||||
```
|
||||
|
||||
#### NOTE
|
||||
The `--break-system-packages` directive is a somewhat misleading choice
|
||||
of words. Setting it will of course not break any system packages, but will simply
|
||||
allow installing `pip` packages user- and system-wide. While this *could* in rare
|
||||
cases lead to version conflicts, it does not generally pose any problems, especially
|
||||
not in the case of installing Reticulum.
|
||||
The `--break-system-packages` directive is a somewhat misleading choice of words. Setting it will of course not break any system packages, but will simply allow installing `pip` packages user- and system-wide. While this *could* in rare cases lead to version conflicts, it does not generally pose any problems, especially not in the case of installing Reticulum.
|
||||
|
||||
### Windows
|
||||
|
||||
On Windows operating systems, the easiest way to install Reticulum is by using the
|
||||
`pip` package manager from the command line (either the command prompt or Windows
|
||||
Powershell).
|
||||
On Windows operating systems, the easiest way to install Reticulum is by using the `pip` package manager from the command line (either the command prompt or Windows Powershell).
|
||||
|
||||
If you don’t already have Python installed, [download and install Python](https://www.python.org/downloads/).
|
||||
At the time of publication of this manual, the recommended version is [Python 3.12.7](https://www.python.org/downloads/release/python-3127).
|
||||
If you don’t already have Python installed, [download and install Python](https://www.python.org/downloads/). At the time of publication of this manual, the recommended version is [Python 3.12.7](https://www.python.org/downloads/release/python-3127).
|
||||
|
||||
**Important!** When asked by the installer, make sure to add the Python program to
|
||||
your PATH environment variables. If you don’t do this, you will not be able to
|
||||
use the `pip` installer, or run the included Reticulum utility programs (such as
|
||||
`rnsd` and `rnstatus`) from the command line.
|
||||
**Important!** When asked by the installer, make sure to add the Python program to your PATH environment variables. If you don’t do this, you will not be able to use the `pip` installer, or run the included Reticulum utility programs (such as `rnsd` and `rnstatus`) from the command line.
|
||||
|
||||
After installing Python, open the command prompt or Windows Powershell, and type:
|
||||
|
||||
@@ -659,8 +487,7 @@ After installing Python, open the command prompt or Windows Powershell, and type
|
||||
pip install rns
|
||||
```
|
||||
|
||||
You can now use Reticulum and all included utility programs directly from your
|
||||
preferred command line interface.
|
||||
You can now use Reticulum and all included utility programs directly from your preferred command line interface.
|
||||
|
||||
## Pure-Python Reticulum
|
||||
|
||||
@@ -670,17 +497,6 @@ do not support [PyCA/cryptography](https://github.com/pyca/cryptography), it is
|
||||
important that you read and understand the [Cryptographic Primitives](understanding.md#understanding-primitives)
|
||||
section of this manual.
|
||||
|
||||
In some rare cases, and on more obscure system types, it is not possible to
|
||||
install one or more dependencies. In such situations,
|
||||
you can use the `rnspure` package instead of the `rns` package, or use `pip`
|
||||
with the `--no-dependencies` command-line option. The `rnspure`
|
||||
package requires no external dependencies for installation. Please note that the
|
||||
actual contents of the `rns` and `rnspure` packages are *completely identical*.
|
||||
The only difference is that the `rnspure` package lists no dependencies required
|
||||
for installation.
|
||||
In some rare cases, and on more obscure system types, it is not possible to install one or more dependencies. In such situations, you can use the `rnspure` package instead of the `rns` package, or use `pip` with the `--no-dependencies` command-line option. The `rnspure` package requires no external dependencies for installation. Please note that the actual contents of the `rns` and `rnspure` packages are *completely identical*. The only difference is that the `rnspure` package lists no dependencies required for installation.
|
||||
|
||||
No matter how Reticulum is installed and started, it will load external dependencies
|
||||
only if they are *needed* and *available*. If for example you want to use Reticulum
|
||||
on a system that cannot support `pyserial`, it is perfectly possible to do so using
|
||||
the rnspure package, but Reticulum will not be able to use serial-based interfaces.
|
||||
All other available modules will still be loaded when needed.
|
||||
No matter how Reticulum is installed and started, it will load external dependencies only if they are *needed* and *available*. If for example you want to use Reticulum on a system that cannot support `pyserial`, it is perfectly possible to do so using the rnspure package, but Reticulum will not be able to use serial-based interfaces. All other available modules will still be loaded when needed.
|
||||
+11
-28
@@ -4,18 +4,14 @@
|
||||
Code Examples
|
||||
*************
|
||||
|
||||
A number of examples are included in the source distribution of Reticulum.
|
||||
You can use these examples to learn how to write your own programs.
|
||||
A number of examples are included in the source distribution of Reticulum. You can use these examples to learn how to write your own programs.
|
||||
|
||||
.. _example-minimal:
|
||||
|
||||
Minimal
|
||||
=======
|
||||
|
||||
The *Minimal* example demonstrates the bare-minimum setup required to connect to
|
||||
a Reticulum network from your program. In about five lines of code, you will
|
||||
have the Reticulum Network Stack initialised, and ready to pass traffic in your
|
||||
program.
|
||||
The *Minimal* example demonstrates the bare-minimum setup required to connect to a Reticulum network from your program. In about five lines of code, you will have the Reticulum Network Stack initialised, and ready to pass traffic in your program.
|
||||
|
||||
.. literalinclude:: ../../Examples/Minimal.py
|
||||
|
||||
@@ -26,9 +22,7 @@ This example can also be found at `<https://github.com/markqvist/Reticulum/blob/
|
||||
Announce
|
||||
========
|
||||
|
||||
The *Announce* example builds upon the previous example by exploring how to
|
||||
announce a destination on the network, and how to let your program receive
|
||||
notifications about announces from relevant destinations.
|
||||
The *Announce* example builds upon the previous example by exploring how to announce a destination on the network, and how to let your program receive notifications about announces from relevant destinations.
|
||||
|
||||
.. literalinclude:: ../../Examples/Announce.py
|
||||
|
||||
@@ -38,8 +32,7 @@ This example can also be found at `<https://github.com/markqvist/Reticulum/blob/
|
||||
|
||||
Broadcast
|
||||
=========
|
||||
The *Broadcast* example explores how to transmit plaintext broadcast messages
|
||||
over the network.
|
||||
The *Broadcast* example explores how to transmit plaintext broadcast messages over the network.
|
||||
|
||||
.. literalinclude:: ../../Examples/Broadcast.py
|
||||
|
||||
@@ -50,8 +43,7 @@ This example can also be found at `<https://github.com/markqvist/Reticulum/blob/
|
||||
Echo
|
||||
====
|
||||
|
||||
The *Echo* example demonstrates communication between two destinations using
|
||||
the Packet interface.
|
||||
The *Echo* example demonstrates communication between two destinations using the Packet interface.
|
||||
|
||||
.. literalinclude:: ../../Examples/Echo.py
|
||||
|
||||
@@ -62,8 +54,7 @@ This example can also be found at `<https://github.com/markqvist/Reticulum/blob/
|
||||
Link
|
||||
====
|
||||
|
||||
The *Link* example explores establishing an encrypted link to a remote
|
||||
destination, and passing traffic back and forth over the link.
|
||||
The *Link* example explores establishing an encrypted link to a remote destination, and passing traffic back and forth over the link.
|
||||
|
||||
.. literalinclude:: ../../Examples/Link.py
|
||||
|
||||
@@ -74,8 +65,7 @@ This example can also be found at `<https://github.com/markqvist/Reticulum/blob/
|
||||
Identification
|
||||
==============
|
||||
|
||||
The *Identify* example explores identifying an intiator of a link, once
|
||||
the link has been established.
|
||||
The *Identify* example explores identifying an intiator of a link, once the link has been established.
|
||||
|
||||
.. literalinclude:: ../../Examples/Identify.py
|
||||
|
||||
@@ -97,8 +87,7 @@ This example can also be found at `<https://github.com/markqvist/Reticulum/blob/
|
||||
Channel
|
||||
=======
|
||||
|
||||
The *Channel* example explores using a ``Channel`` to send structured
|
||||
data between peers of a ``Link``.
|
||||
The *Channel* example explores using a ``Channel`` to send structured data between peers of a ``Link``.
|
||||
|
||||
.. literalinclude:: ../../Examples/Channel.py
|
||||
|
||||
@@ -107,8 +96,7 @@ This example can also be found at `<https://github.com/markqvist/Reticulum/blob/
|
||||
Buffer
|
||||
======
|
||||
|
||||
The *Buffer* example explores using buffered readers and writers to send
|
||||
binary data between peers of a ``Link``.
|
||||
The *Buffer* example explores using buffered readers and writers to send binary data between peers of a ``Link``.
|
||||
|
||||
.. literalinclude:: ../../Examples/Buffer.py
|
||||
|
||||
@@ -119,9 +107,7 @@ This example can also be found at `<https://github.com/markqvist/Reticulum/blob/
|
||||
Filetransfer
|
||||
============
|
||||
|
||||
The *Filetransfer* example implements a basic file-server program that
|
||||
allow clients to connect and download files. The program uses the Resource
|
||||
interface to efficiently pass files of any size over a Reticulum :ref:`Link<api-link>`.
|
||||
The *Filetransfer* example implements a basic file-server program that allow clients to connect and download files. The program uses the Resource interface to efficiently pass files of any size over a Reticulum :ref:`Link<api-link>`.
|
||||
|
||||
.. literalinclude:: ../../Examples/Filetransfer.py
|
||||
|
||||
@@ -132,10 +118,7 @@ This example can also be found at `<https://github.com/markqvist/Reticulum/blob/
|
||||
Custom Interfaces
|
||||
=================
|
||||
|
||||
The *ExampleInterface* demonstrates creating custom interfaces for Reticulum.
|
||||
Any number of custom interfaces can be loaded and utilised by Reticulum, and
|
||||
will be fully on-par with natively included interfaces, including all supported
|
||||
:ref:`interface modes<interfaces-modes>` and :ref:`common configuration options<interfaces-options>`.
|
||||
The *ExampleInterface* demonstrates creating custom interfaces for Reticulum. Any number of custom interfaces can be loaded and utilised by Reticulum, and will be fully on-par with natively included interfaces, including all supported :ref:`interface modes<interfaces-modes>` and :ref:`common configuration options<interfaces-options>`.
|
||||
|
||||
.. literalinclude:: ../../Examples/ExampleInterface.py
|
||||
|
||||
|
||||
@@ -2,51 +2,38 @@
|
||||
Getting Started Fast
|
||||
********************
|
||||
|
||||
The best way to get started with the Reticulum Network Stack depends on what
|
||||
you want to do. This guide will outline sensible starting paths for different
|
||||
scenarios.
|
||||
The best way to get started with the Reticulum Network Stack depends on what you want to do. This guide will outline sensible starting paths for different scenarios.
|
||||
|
||||
|
||||
Standalone Reticulum Installation
|
||||
=================================
|
||||
If you simply want to install Reticulum and related utilities on a system,
|
||||
the easiest way is via the ``pip`` package manager:
|
||||
If you simply want to install Reticulum and related utilities on a system, the easiest way is via the ``pip`` package manager:
|
||||
|
||||
.. code:: shell
|
||||
|
||||
pip install rns
|
||||
|
||||
If you do not already have pip installed, you can install it using the package manager
|
||||
of your system with a command like ``sudo apt install python3-pip``,
|
||||
``sudo pamac install python-pip`` or similar.
|
||||
If you do not already have pip installed, you can install it using the package manager of your system with a command like ``sudo apt install python3-pip``, ``sudo pamac install python-pip`` or similar.
|
||||
|
||||
You can also dowload the Reticulum release wheels from GitHub, or other release channels,
|
||||
and install them offline using ``pip``:
|
||||
You can also dowload the Reticulum release wheels from GitHub, or other release channels, and install them offline using ``pip``:
|
||||
|
||||
.. code:: shell
|
||||
|
||||
pip install ./rns-1.1.2-py3-none-any.whl
|
||||
|
||||
On platforms that limit user package installation via ``pip``, you may need to manually
|
||||
allow this using the ``--break-system-packages`` command line flag when installing. This
|
||||
will not actually break any packages, unless you have installed Reticulum directly via
|
||||
your operating system's package manager.
|
||||
On platforms that limit user package installation via ``pip``, you may need to manually allow this using the ``--break-system-packages`` command line flag when installing. This will not actually break any packages, unless you have installed Reticulum directly via your operating system's package manager.
|
||||
|
||||
.. code:: shell
|
||||
|
||||
pip install rns --break-system-packages
|
||||
|
||||
For more detailed installation instructions, please see the
|
||||
:ref:`Platform-Specific Install Notes<install-guides>` section.
|
||||
For more detailed installation instructions, please see the :ref:`Platform-Specific Install Notes<install-guides>` section.
|
||||
|
||||
After installation is complete, it might be helpful to refer to the
|
||||
:ref:`Using Reticulum on Your System<using-main>` chapter.
|
||||
After installation is complete, it might be helpful to refer to the :ref:`Using Reticulum on Your System<using-main>` chapter.
|
||||
|
||||
Resolving Dependency & Installation Issues
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
On some platforms, there may not be binary packages available for all dependencies, and
|
||||
``pip`` installation may fail with an error message. In these cases, the issue can usually
|
||||
be resolved by installing the development essentials packages for your platform:
|
||||
On some platforms, there may not be binary packages available for all dependencies, and ``pip`` installation may fail with an error message. In these cases, the issue can usually be resolved by installing the development essentials packages for your platform:
|
||||
|
||||
.. code:: shell
|
||||
|
||||
@@ -59,69 +46,38 @@ be resolved by installing the development essentials packages for your platform:
|
||||
# Fedora
|
||||
sudo dnf groupinstall "Development Tools" "Development Libraries"
|
||||
|
||||
With the base development packages installed, ``pip`` should be able to compile any missing
|
||||
dependencies from source, and complete installation even on platforms that don't have pre-
|
||||
compiled packages available.
|
||||
With the base development packages installed, ``pip`` should be able to compile any missing dependencies from source, and complete installation even on platforms that don't have pre-compiled packages available.
|
||||
|
||||
Try Using a Reticulum-based Program
|
||||
=============================================
|
||||
===================================
|
||||
|
||||
If you simply want to try using a program built with Reticulum, a :ref:`range of different
|
||||
programs <software-main>` exist that allow basic communication and a various other useful functions,
|
||||
even over extremely low-bandwidth Reticulum networks.
|
||||
If you simply want to try using a program built with Reticulum, a :ref:`range of different programs <software-main>` exist that allow basic communication and a various other useful functions, even over extremely low-bandwidth Reticulum networks.
|
||||
|
||||
|
||||
Using the Included Utilities
|
||||
=============================================
|
||||
Reticulum comes with a range of included utilities that make it easier to
|
||||
manage your network, check connectivity and make Reticulum available to other
|
||||
programs on your system.
|
||||
============================
|
||||
Reticulum comes with a range of included utilities that make it easier to manage your network, check connectivity and make Reticulum available to other programs on your system.
|
||||
|
||||
You can use ``rnsd`` to run Reticulum as a background or foreground service,
|
||||
and the ``rnstatus``, ``rnpath`` and ``rnprobe`` utilities to view and query
|
||||
network status and connectivity.
|
||||
You can use ``rnsd`` to run Reticulum as a background or foreground service, and the ``rnstatus``, ``rnpath`` and ``rnprobe`` utilities to view and query network status and connectivity.
|
||||
|
||||
To learn more about these utility programs, have a look at the
|
||||
:ref:`Using Reticulum on Your System<using-main>` chapter of this manual.
|
||||
To learn more about these utility programs, have a look at the :ref:`Using Reticulum on Your System<using-main>` chapter of this manual.
|
||||
|
||||
|
||||
Creating a Network With Reticulum
|
||||
=============================================
|
||||
To create a network, you will need to specify one or more *interfaces* for
|
||||
Reticulum to use. This is done in the Reticulum configuration file, which by
|
||||
default is located at ``~/.reticulum/config``. You can get an example
|
||||
configuration file with all options via ``rnsd --exampleconfig``.
|
||||
=================================
|
||||
To create a network, you will need to specify one or more *interfaces* for Reticulum to use. This is done in the Reticulum configuration file, which by default is located at ``~/.reticulum/config``. You can get an example configuration file with all options via ``rnsd --exampleconfig``.
|
||||
|
||||
When Reticulum is started for the first time, it will create a default
|
||||
configuration file, with one active interface. This default interface uses
|
||||
your existing Ethernet and WiFi networks (if any), and only allows you to
|
||||
communicate with other Reticulum peers within your local broadcast domains.
|
||||
When Reticulum is started for the first time, it will create a default configuration file, with one active interface. This default interface uses your existing Ethernet and WiFi networks (if any), and only allows you to communicate with other Reticulum peers within your local broadcast domains.
|
||||
|
||||
To communicate further, you will have to add one or more interfaces. The default
|
||||
configuration includes a number of examples, ranging from using TCP over the
|
||||
internet, to LoRa and Packet Radio interfaces.
|
||||
To communicate further, you will have to add one or more interfaces. The default configuration includes a number of examples, ranging from using TCP over the internet, to LoRa and Packet Radio interfaces.
|
||||
|
||||
With Reticulum, you only need to configure what interfaces you want to communicate
|
||||
over. There is no need to configure address spaces, subnets, routing tables,
|
||||
or other things you might be used to from other network types.
|
||||
With Reticulum, you only need to configure what interfaces you want to communicate over. There is no need to configure address spaces, subnets, routing tables, or other things you might be used to from other network types.
|
||||
|
||||
Once Reticulum knows which interfaces it should use, it will automatically
|
||||
discover topography and configure transport of data to any destinations it
|
||||
knows about.
|
||||
Once Reticulum knows which interfaces it should use, it will automatically discover topography and configure transport of data to any destinations it knows about.
|
||||
|
||||
In situations where you already have an established WiFi or Ethernet network, and
|
||||
many devices that want to utilise the same external Reticulum network paths (for example over
|
||||
LoRa), it will often be sufficient to let one system act as a Reticulum gateway, by
|
||||
adding any external interfaces to the configuration of this system, and then enabling transport on it. Any
|
||||
other device on your local WiFi will then be able to connect to this wider Reticulum
|
||||
network just using the default (:ref:`AutoInterface<interfaces-auto>`) configuration.
|
||||
In situations where you already have an established WiFi or Ethernet network, and many devices that want to utilise the same external Reticulum network paths (for example over LoRa), it will often be sufficient to let one system act as a Reticulum gateway, by adding any external interfaces to the configuration of this system, and then enabling transport on it. Any other device on your local WiFi will then be able to connect to this wider Reticulum network just using the default (:ref:`AutoInterface<interfaces-auto>`) configuration.
|
||||
|
||||
Possibly, the examples in the config file are enough to get you started. If
|
||||
you want more information, you can read the :ref:`Building Networks<networks-main>`
|
||||
and :ref:`Interfaces<interfaces-main>` chapters of this manual, but most importantly,
|
||||
start with reading the next section, :ref:`Bootstrapping Connectivity<bootstrapping-connectivity>`,
|
||||
as this provides the most essential understanding of how to ensure reliable
|
||||
connectivity with a minimum of maintenance.
|
||||
Possibly, the examples in the config file are enough to get you started. If you want more information, you can read the :ref:`Building Networks<networks-main>` and :ref:`Interfaces<interfaces-main>` chapters of this manual, but most importantly, start with reading the next section, :ref:`Bootstrapping Connectivity<bootstrapping-connectivity>`, as this provides the most essential understanding of how to ensure reliable connectivity with a minimum of maintenance.
|
||||
|
||||
|
||||
.. _bootstrapping-connectivity:
|
||||
@@ -216,20 +172,13 @@ As a good starting point, you can find interface definitions for connecting your
|
||||
Hosting Public Entrypoints
|
||||
==========================
|
||||
|
||||
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
|
||||
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>`.
|
||||
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 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>`.
|
||||
|
||||
You will need a machine, physical or virtual with a public IP address, that can be reached by other devices on the Internet.
|
||||
|
||||
The most efficient and performant way to host a connectable entry-point supporting many
|
||||
users is to use the ``BackboneInterface``. This interface type is fully compatible with
|
||||
the ``TCPClientInterface`` and ``TCPServerInterface`` types, but much faster and uses
|
||||
less system resources, allowing your device to handle thousands of connections even on
|
||||
small systems.
|
||||
The most efficient and performant way to host a connectable entry-point supporting many users is to use the ``BackboneInterface``. This interface type is fully compatible with the ``TCPClientInterface`` and ``TCPServerInterface`` types, but much faster and uses less system resources, allowing your device to handle thousands of connections even on small systems.
|
||||
|
||||
It is also important to set your connectable interface to ``gateway`` mode, since this
|
||||
will greatly improve network convergence time and path resolution for anyone connecting
|
||||
to your entry-point.
|
||||
It is also important to set your connectable interface to ``gateway`` mode, since this will greatly improve network convergence time and path resolution for anyone connecting to your entry-point.
|
||||
|
||||
.. code:: ini
|
||||
|
||||
@@ -251,8 +200,7 @@ to your entry-point.
|
||||
announce_rate_penalty = 3600
|
||||
announce_rate_grace = 6
|
||||
|
||||
If instead you want to make a private entry-point from the Internet, you can use the
|
||||
:ref:`IFAC name and passphrase options<interfaces-options>` to secure your interface with a network name and passphrase.
|
||||
If instead you want to make a private entry-point from the Internet, you can use the :ref:`IFAC name and passphrase options<interfaces-options>` to secure your interface with a network name and passphrase.
|
||||
|
||||
.. code:: ini
|
||||
|
||||
@@ -268,132 +216,79 @@ If instead you want to make a private entry-point from the Internet, you can use
|
||||
network_name = private_ret
|
||||
passphrase = 2owjajquafIanPecAc
|
||||
|
||||
If you are hosting an entry-point on an operating system that does not support
|
||||
``BackboneInterface``, you can use ``TCPServerInterface`` instead, although it will
|
||||
not be as performant.
|
||||
If you are hosting an entry-point on an operating system that does not support ``BackboneInterface``, you can use ``TCPServerInterface`` instead, although it will not be as performant.
|
||||
|
||||
|
||||
Connecting Reticulum Instances Over the Internet
|
||||
================================================
|
||||
Reticulum currently offers three interfaces suitable for connecting instances over the Internet: :ref:`Backbone<interfaces-backbone>`, :ref:`TCP<interfaces-tcps>`
|
||||
and :ref:`I2P<interfaces-i2p>`. Each interface offers a different set of features, and Reticulum
|
||||
users should carefully choose the interface which best suites their needs.
|
||||
Reticulum currently offers three interfaces suitable for connecting instances over the Internet: :ref:`Backbone<interfaces-backbone>`, :ref:`TCP<interfaces-tcps>` and :ref:`I2P<interfaces-i2p>`. Each interface offers a different set of features, and Reticulum users should carefully choose the interface which best suites their needs.
|
||||
|
||||
The ``TCPServerInterface`` allows users to host an instance accessible over TCP/IP. This
|
||||
method is generally faster, lower latency, and more energy efficient than using ``I2PInterface``,
|
||||
however it also leaks more data about the server host.
|
||||
The ``TCPServerInterface`` allows users to host an instance accessible over TCP/IP. This method is generally faster, lower latency, and more energy efficient than using ``I2PInterface``, however it also leaks more data about the server host.
|
||||
|
||||
The ``BackboneInterface`` is a very fast and efficient interface type available on POSIX operating
|
||||
systems, designed to handle thousands of connections simultaneously with low memory, processing
|
||||
and I/O overhead. It is fully compatible with the TCP-based interface types.
|
||||
The ``BackboneInterface`` is a very fast and efficient interface type available on POSIX operating systems, designed to handle thousands of connections simultaneously with low memory, processing and I/O overhead. It is fully compatible with the TCP-based interface types.
|
||||
|
||||
TCP connections reveal the IP address of both your instance and the server to anyone who can
|
||||
inspect the connection. Someone could use this information to determine your location or identity. Adversaries
|
||||
inspecting your packets may be able to record packet metadata like time of transmission and packet size.
|
||||
Even though Reticulum encrypts traffic, TCP does not, so an adversary may be able to use
|
||||
packet inspection to learn that a system is running Reticulum, and what other IP addresses connect to it.
|
||||
Hosting a publicly reachable instance over TCP also requires a publicly reachable IP address,
|
||||
which most Internet connections don't offer anymore.
|
||||
TCP connections reveal the IP address of both your instance and the server to anyone who can inspect the connection. Someone could use this information to determine your location or identity. Adversaries inspecting your packets may be able to record packet metadata like time of transmission and packet size. Even though Reticulum encrypts traffic, TCP does not, so an adversary may be able to use packet inspection to learn that a system is running Reticulum, and what other IP addresses connect to it. Hosting a publicly reachable instance over TCP also requires a publicly reachable IP address, which most Internet connections don't offer anymore.
|
||||
|
||||
The ``I2PInterface`` routes messages through the `Invisible Internet Protocol
|
||||
(I2P) <https://geti2p.net/en/>`_. To use this interface, users must also run an I2P daemon in
|
||||
parallel to ``rnsd``. For always-on I2P nodes it is recommended to use `i2pd <https://i2pd.website/>`_.
|
||||
The ``I2PInterface`` routes messages through the `Invisible Internet Protocol (I2P) <https://geti2p.net/en/>`_. To use this interface, users must also run an I2P daemon in parallel to ``rnsd``. For always-on I2P nodes it is recommended to use `i2pd <https://i2pd.website/>`_.
|
||||
|
||||
By default, I2P will encrypt and mix all traffic sent over the Internet, and
|
||||
hide both the sender and receiver Reticulum instance IP addresses. Running an I2P node
|
||||
will also relay other I2P user's encrypted packets, which will use extra
|
||||
bandwidth and compute power, but also makes timing attacks and other forms of
|
||||
deep-packet-inspection much more difficult.
|
||||
By default, I2P will encrypt and mix all traffic sent over the Internet, and hide both the sender and receiver Reticulum instance IP addresses. Running an I2P node will also relay other I2P user's encrypted packets, which will use extra bandwidth and compute power, but also makes timing attacks and other forms of deep-packet-inspection much more difficult.
|
||||
|
||||
I2P also allows users to host globally available Reticulum instances from non-public IP's and behind firewalls and NAT.
|
||||
|
||||
In general it is recommended to use an I2P node if you want to host a publicly accessible
|
||||
instance, while preserving anonymity. If you care more about performance, and a slightly
|
||||
easier setup, use TCP.
|
||||
In general it is recommended to use an I2P node if you want to host a publicly accessible instance, while preserving anonymity. If you care more about performance, and a slightly easier setup, use TCP.
|
||||
|
||||
Adding Radio Interfaces
|
||||
=======================
|
||||
Once you have Reticulum installed and working, you can add radio interfaces with
|
||||
any compatible hardware you have available. Reticulum supports a wide range of radio
|
||||
hardware, and if you already have any available, it is very likely that it will
|
||||
work with Reticulum. For information on how to configure this, see the
|
||||
:ref:`Interfaces<interfaces-main>` section of this manual.
|
||||
Once you have Reticulum installed and working, you can add radio interfaces with any compatible hardware you have available. Reticulum supports a wide range of radio hardware, and if you already have any available, it is very likely that it will work with Reticulum. For information on how to configure this, see the :ref:`Interfaces<interfaces-main>` section of this manual.
|
||||
|
||||
If you do not already have transceiver hardware available, you can easily and
|
||||
cheaply build an :ref:`RNode<rnode-main>`, which is a general-purpose long-range
|
||||
digital radio transceiver, that integrates easily with Reticulum.
|
||||
If you do not already have transceiver hardware available, you can easily and cheaply build an :ref:`RNode<rnode-main>`, which is a general-purpose long-range digital radio transceiver, that integrates easily with Reticulum.
|
||||
|
||||
To build one yourself requires installing a custom firmware on a supported LoRa
|
||||
development board with an auto-install script or web-based flasher.
|
||||
Please see the :ref:`Communications Hardware<hardware-main>` chapter for a guide.
|
||||
If you prefer purchasing a ready-made unit, you can refer to the
|
||||
:ref:`list of suppliers<rnode-suppliers>`.
|
||||
To build one yourself requires installing a custom firmware on a supported LoRa development board with an auto-install script or web-based flasher. Please see the :ref:`Communications Hardware<hardware-main>` chapter for a guide. If you prefer purchasing a ready-made unit, you can refer to the :ref:`list of suppliers<rnode-suppliers>`.
|
||||
|
||||
Other radio-based hardware interfaces are being developed and made available by
|
||||
the broader Reticulum community. You can find more information on such topics
|
||||
over Reticulum-based information sharing systems.
|
||||
Other radio-based hardware interfaces are being developed and made available by the broader Reticulum community. You can find more information on such topics over Reticulum-based information sharing systems.
|
||||
|
||||
If you have communications hardware that is not already supported by any of the
|
||||
:ref:`existing interface types<interfaces-main>`, it is easy to write (and potentially
|
||||
publish) a :ref:`custom interface module<interfaces-custom>` that makes it compatible with Reticulum.
|
||||
If you have communications hardware that is not already supported by any of the :ref:`existing interface types<interfaces-main>`, it is easy to write (and potentially publish) a :ref:`custom interface module<interfaces-custom>` that makes it compatible with Reticulum.
|
||||
|
||||
|
||||
Creating and Using Custom Interfaces
|
||||
====================================
|
||||
|
||||
While Reticulum includes a flexible and broad range of built-in interfaces, these
|
||||
will not cover every conceivable type of communications hardware that Reticulum
|
||||
can potentially use to communicate.
|
||||
While Reticulum includes a flexible and broad range of built-in interfaces, these will not cover every conceivable type of communications hardware that Reticulum can potentially use to communicate.
|
||||
|
||||
It is therefore possible to easily write your own interface modules, that can be
|
||||
loaded at run-time and used on-par with any of the built-in interface types.
|
||||
It is therefore possible to easily write your own interface modules, that can be loaded at run-time and used on-par with any of the built-in interface types.
|
||||
|
||||
For more information on this subject, and code examples to build on, please see
|
||||
the :ref:`Configuring Interfaces<interfaces-main>` chapter.
|
||||
For more information on this subject, and code examples to build on, please see the :ref:`Configuring Interfaces<interfaces-main>` chapter.
|
||||
|
||||
|
||||
Develop a Program with Reticulum
|
||||
===========================================
|
||||
If you want to develop programs that use Reticulum, the easiest way to get
|
||||
started is to install the latest release of Reticulum via pip:
|
||||
================================
|
||||
If you want to develop programs that use Reticulum, the easiest way to get started is to install the latest release of Reticulum via pip:
|
||||
|
||||
.. code::
|
||||
|
||||
pip install rns
|
||||
|
||||
The above command will install Reticulum and dependencies, and you will be
|
||||
ready to import and use RNS in your own programs. The next step will most
|
||||
likely be to look at some :ref:`Example Programs<examples-main>`.
|
||||
The above command will install Reticulum and dependencies, and you will be ready to import and use RNS in your own programs. The next step will most likely be to look at some :ref:`Example Programs<examples-main>`.
|
||||
|
||||
The entire Reticulum API is documented in the :ref:`API Reference<api-main>`
|
||||
chapter of this manual. Before diving in, it's probably a good idea to read
|
||||
this manual in full, but at least start with the :ref:`Understanding Reticulum<understanding-main>` chapter.
|
||||
The entire Reticulum API is documented in the :ref:`API Reference<api-main>` chapter of this manual. Before diving in, it's probably a good idea to read this manual in full, but at least start with the :ref:`Understanding Reticulum<understanding-main>` chapter.
|
||||
|
||||
|
||||
.. _install-guides:
|
||||
|
||||
Platform-Specific Install Notes
|
||||
==============================================
|
||||
===============================
|
||||
|
||||
Some platforms require a slightly different installation procedure, or have
|
||||
various quirks that are worth being aware of. These are listed here.
|
||||
Some platforms require a slightly different installation procedure, or have various quirks that are worth being aware of. These are listed here.
|
||||
|
||||
Android
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
Reticulum can be used on Android in different ways. The easiest way to get
|
||||
started is using an app like `Sideband <https://unsigned.io/sideband>`_.
|
||||
^^^^^^^
|
||||
Reticulum can be used on Android in different ways. The easiest way to get started is using an app like `Sideband <https://unsigned.io/sideband>`_.
|
||||
|
||||
For more control and features, you can use Reticulum and related programs via
|
||||
the `Termux app <https://termux.com/>`_, at the time of writing available on
|
||||
`F-droid <https://f-droid.org>`_.
|
||||
For more control and features, you can use Reticulum and related programs via the `Termux app <https://termux.com/>`_, at the time of writing available on `F-droid <https://f-droid.org>`_.
|
||||
|
||||
Termux is a terminal emulator and Linux environment for Android based devices,
|
||||
which includes the ability to use many different programs and libraries,
|
||||
including Reticulum.
|
||||
Termux is a terminal emulator and Linux environment for Android based devices, which includes the ability to use many different programs and libraries, including Reticulum.
|
||||
|
||||
To use Reticulum within the Termux environment, you will need to install
|
||||
``python`` and the ``python-cryptography`` library using ``pkg``, the package-manager
|
||||
build into Termux. After that, you can use ``pip`` to install Reticulum.
|
||||
To use Reticulum within the Termux environment, you will need to install ``python`` and the ``python-cryptography`` library using ``pkg``, the package-manager build into Termux. After that, you can use ``pip`` to install Reticulum.
|
||||
|
||||
From within Termux, execute the following:
|
||||
|
||||
@@ -412,9 +307,7 @@ From within Termux, execute the following:
|
||||
# Install Reticulum
|
||||
pip install rns
|
||||
|
||||
If for some reason the ``python-cryptography`` package is not available for
|
||||
your platform via the Termux package manager, you can attempt to build it
|
||||
locally on your device using the following command:
|
||||
If for some reason the ``python-cryptography`` package is not available for your platform via the Termux package manager, you can attempt to build it locally on your device using the following command:
|
||||
|
||||
.. code:: shell
|
||||
|
||||
@@ -441,16 +334,12 @@ locally on your device using the following command:
|
||||
# Reticulum and any related software
|
||||
pip install rns
|
||||
|
||||
It is also possible to include Reticulum in apps compiled and distributed as
|
||||
Android APKs. A detailed tutorial and example source code will be included
|
||||
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.
|
||||
It is also possible to include Reticulum in apps compiled and distributed as Android APKs. A detailed tutorial and example source code will be included 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.
|
||||
|
||||
|
||||
ARM64
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
On some architectures, including ARM64, not all dependencies have precompiled
|
||||
binaries. On such systems, you may need to install ``python3-dev`` (or similar) before
|
||||
installing Reticulum or programs that depend on Reticulum.
|
||||
^^^^^
|
||||
On some architectures, including ARM64, not all dependencies have precompiled binaries. On such systems, you may need to install ``python3-dev`` (or similar) before installing Reticulum or programs that depend on Reticulum.
|
||||
|
||||
.. code:: shell
|
||||
|
||||
@@ -466,12 +355,8 @@ on your system locally.
|
||||
|
||||
|
||||
Debian Bookworm
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
On versions of Debian released after April 2023, it is no longer possible by default
|
||||
to use ``pip`` to install packages onto your system. Unfortunately, you will need to
|
||||
use the replacement ``pipx`` command instead, which places installed packages in an
|
||||
isolated environment. This should not negatively affect Reticulum, but will not work
|
||||
for including and using Reticulum in your own scripts and programs.
|
||||
^^^^^^^^^^^^^^^
|
||||
On versions of Debian released after April 2023, it is no longer possible by default to use ``pip`` to install packages onto your system. Unfortunately, you will need to use the replacement ``pipx`` command instead, which places installed packages in an isolated environment. This should not negatively affect Reticulum, but will not work for including and using Reticulum in your own scripts and programs.
|
||||
|
||||
.. code:: shell
|
||||
|
||||
@@ -484,42 +369,30 @@ for including and using Reticulum in your own scripts and programs.
|
||||
# Install Reticulum
|
||||
pipx install rns
|
||||
|
||||
Alternatively, you can restore normal behaviour to ``pip`` by creating or editing
|
||||
the configuration file located at ``~/.config/pip/pip.conf``, and adding the
|
||||
following section:
|
||||
Alternatively, you can restore normal behaviour to ``pip`` by creating or editing the configuration file located at ``~/.config/pip/pip.conf``, and adding the following section:
|
||||
|
||||
.. code:: ini
|
||||
|
||||
[global]
|
||||
break-system-packages = true
|
||||
|
||||
For a one-shot installation of Reticulum, without globally enabling the ``break-system-packages``
|
||||
option, you can use the following command:
|
||||
For a one-shot installation of Reticulum, without globally enabling the ``break-system-packages`` option, you can use the following command:
|
||||
|
||||
.. code:: shell
|
||||
|
||||
pip install rns --break-system-packages
|
||||
|
||||
.. note::
|
||||
The ``--break-system-packages`` directive is a somewhat misleading choice
|
||||
of words. Setting it will of course not break any system packages, but will simply
|
||||
allow installing ``pip`` packages user- and system-wide. While this *could* in rare
|
||||
cases lead to version conflicts, it does not generally pose any problems, especially
|
||||
not in the case of installing Reticulum.
|
||||
The ``--break-system-packages`` directive is a somewhat misleading choice of words. Setting it will of course not break any system packages, but will simply allow installing ``pip`` packages user- and system-wide. While this *could* in rare cases lead to version conflicts, it does not generally pose any problems, especially not in the case of installing Reticulum.
|
||||
|
||||
|
||||
MacOS
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
To install Reticulum on macOS, you will need to have Python and the ``pip`` package
|
||||
manager installed.
|
||||
^^^^^
|
||||
To install Reticulum on macOS, you will need to have Python and the ``pip`` package manager installed.
|
||||
|
||||
Systems running macOS can vary quite widely in whether or not Python is pre-installed,
|
||||
and if it is, which version is installed, and whether the ``pip`` package manager is
|
||||
also installed and set up. If in doubt, you can `download and install <https://www.python.org/downloads/>`_
|
||||
Python manually.
|
||||
Systems running macOS can vary quite widely in whether or not Python is pre-installed, and if it is, which version is installed, and whether the ``pip`` package manager is also installed and set up. If in doubt, you can `download and install <https://www.python.org/downloads/>`_ Python manually.
|
||||
|
||||
When Python and ``pip`` is available on your system, simply open a terminal window
|
||||
and use one of the following commands:
|
||||
When Python and ``pip`` is available on your system, simply open a terminal window and use one of the following commands:
|
||||
|
||||
.. code:: shell
|
||||
|
||||
@@ -531,16 +404,9 @@ and use one of the following commands:
|
||||
pip3 install rns --break-system-packages
|
||||
|
||||
.. note::
|
||||
The ``--break-system-packages`` directive is a somewhat misleading choice
|
||||
of words. Setting it will of course not break any system packages, but will simply
|
||||
allow installing ``pip`` packages user- and system-wide. While this *could* in rare
|
||||
cases lead to version conflicts, it does not generally pose any problems, especially
|
||||
not in the case of installing Reticulum.
|
||||
The ``--break-system-packages`` directive is a somewhat misleading choice of words. Setting it will of course not break any system packages, but will simply allow installing ``pip`` packages user- and system-wide. While this *could* in rare cases lead to version conflicts, it does not generally pose any problems, especially not in the case of installing Reticulum.
|
||||
|
||||
Additionally, some version combinations of macOS and Python require you to
|
||||
manually add your installed ``pip`` packages directory to your `PATH` environment
|
||||
variable, before you can use installed commands in your terminal. Usually, adding
|
||||
the following line to your shell init script (for example ``~/.zshrc``) will be enough:
|
||||
Additionally, some version combinations of macOS and Python require you to manually add your installed ``pip`` packages directory to your `PATH` environment variable, before you can use installed commands in your terminal. Usually, adding the following line to your shell init script (for example ``~/.zshrc``) will be enough:
|
||||
|
||||
.. code:: shell
|
||||
|
||||
@@ -550,20 +416,13 @@ Adjust Python version and shell init script location according to your system.
|
||||
|
||||
|
||||
OpenWRT
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
On OpenWRT systems with sufficient storage and memory, you can install
|
||||
Reticulum and related utilities using the `opkg` package manager and `pip`.
|
||||
^^^^^^^
|
||||
On OpenWRT systems with sufficient storage and memory, you can install Reticulum and related utilities using the `opkg` package manager and `pip`.
|
||||
|
||||
.. note::
|
||||
At the time of releasing this manual, work is underway to create pre-built Reticulum packages for OpenWRT, with full configuration, service and ``uci`` integration. Please see the `feed-reticulum <https://github.com/gretel/feed-reticulum>`_ and `reticulum-openwrt <https://github.com/gretel/reticulum-openwrt>`_ repositories for more information.
|
||||
|
||||
At the time of releasing this manual, work is underway to create pre-built
|
||||
Reticulum packages for OpenWRT, with full configuration, service
|
||||
and ``uci`` integration. Please see the `feed-reticulum <https://github.com/gretel/feed-reticulum>`_
|
||||
and `reticulum-openwrt <https://github.com/gretel/reticulum-openwrt>`_
|
||||
repositories for more information.
|
||||
|
||||
To install Reticulum on OpenWRT, first log into a command line session, and
|
||||
then use the following instructions:
|
||||
To install Reticulum on OpenWRT, first log into a command line session, and then use the following instructions:
|
||||
|
||||
.. code:: shell
|
||||
|
||||
@@ -577,30 +436,15 @@ then use the following instructions:
|
||||
rnsd -vvv
|
||||
|
||||
.. note::
|
||||
|
||||
The above instructions have been verified and tested on OpenWRT 21.02 only.
|
||||
It is likely that other versions may require slightly altered installation
|
||||
commands or package names. You will also need enough free space in your
|
||||
overlay FS, and enough free RAM to actually run Reticulum and any related
|
||||
programs and utilities.
|
||||
The above instructions have been verified and tested on OpenWRT 21.02 only. It is likely that other versions may require slightly altered installation commands or package names. You will also need enough free space in your overlay FS, and enough free RAM to actually run Reticulum and any related programs and utilities.
|
||||
|
||||
Depending on your device configuration, you may need to adjust firewall rules
|
||||
for Reticulum connectivity to and from your device to work. Until proper
|
||||
packaging is ready, you will also need to manually create a service or startup
|
||||
script to automatically laucnh Reticulum at boot time.
|
||||
Depending on your device configuration, you may need to adjust firewall rules for Reticulum connectivity to and from your device to work. Until proper packaging is ready, you will also need to manually create a service or startup script to automatically laucnh Reticulum at boot time.
|
||||
|
||||
Please also note that the `AutoInterface` requires link-local IPv6 addresses
|
||||
to be enabled for any Ethernet and WiFi devices you intend to use. If ``ip a``
|
||||
shows an address starting with ``fe80::`` for the device in question,
|
||||
``AutoInterface`` should work for that device.
|
||||
Please also note that the `AutoInterface` requires link-local IPv6 addresses to be enabled for any Ethernet and WiFi devices you intend to use. If ``ip a`` shows an address starting with ``fe80::`` for the device in question, ``AutoInterface`` should work for that device.
|
||||
|
||||
Raspberry Pi
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
It is currently recommended to use a 64-bit version of the Raspberry Pi OS
|
||||
if you want to run Reticulum on Raspberry Pi computers, since 32-bit versions
|
||||
don't always have packages available for some dependencies. If Python and the
|
||||
`pip` package manager is not already installed, do that first, and then
|
||||
install Reticulum using `pip`.
|
||||
^^^^^^^^^^^^
|
||||
It is currently recommended to use a 64-bit version of the Raspberry Pi OS if you want to run Reticulum on Raspberry Pi computers, since 32-bit versions don't always have packages available for some dependencies. If Python and the `pip` package manager is not already installed, do that first, and then install Reticulum using `pip`.
|
||||
|
||||
.. code:: shell
|
||||
|
||||
@@ -611,22 +455,14 @@ install Reticulum using `pip`.
|
||||
pip install rns --break-system-packages
|
||||
|
||||
.. note::
|
||||
The ``--break-system-packages`` directive is a somewhat misleading choice
|
||||
of words. Setting it will of course not break any system packages, but will simply
|
||||
allow installing ``pip`` packages user- and system-wide. While this *could* in rare
|
||||
cases lead to version conflicts, it does not generally pose any problems, especially
|
||||
not in the case of installing Reticulum.
|
||||
The ``--break-system-packages`` directive is a somewhat misleading choice of words. Setting it will of course not break any system packages, but will simply allow installing ``pip`` packages user- and system-wide. While this *could* in rare cases lead to version conflicts, it does not generally pose any problems, especially not in the case of installing Reticulum.
|
||||
|
||||
While it is possible to install and run Reticulum on 32-bit Rasperry Pi OSes,
|
||||
it will require manually configuring and installing required build dependencies,
|
||||
and is not detailed in this manual.
|
||||
While it is possible to install and run Reticulum on 32-bit Rasperry Pi OSes, it will require manually configuring and installing required build dependencies, and is not detailed in this manual.
|
||||
|
||||
|
||||
RISC-V
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
On some architectures, including RISC-V, not all dependencies have precompiled
|
||||
binaries. On such systems, you may need to install ``python3-dev`` (or similar) before
|
||||
installing Reticulum or programs that depend on Reticulum.
|
||||
^^^^^^
|
||||
On some architectures, including RISC-V, not all dependencies have precompiled binaries. On such systems, you may need to install ``python3-dev`` (or similar) before installing Reticulum or programs that depend on Reticulum.
|
||||
|
||||
.. code:: shell
|
||||
|
||||
@@ -637,17 +473,12 @@ installing Reticulum or programs that depend on Reticulum.
|
||||
# Install Reticulum
|
||||
python3 -m pip install rns
|
||||
|
||||
With these packages installed, ``pip`` will be able to build any missing dependencies
|
||||
on your system locally.
|
||||
With these packages installed, ``pip`` will be able to build any missing dependencies on your system locally.
|
||||
|
||||
|
||||
Ubuntu Lunar
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
On versions of Ubuntu released after April 2023, it is no longer possible by default
|
||||
to use ``pip`` to install packages onto your system. Unfortunately, you will need to
|
||||
use the replacement ``pipx`` command instead, which places installed packages in an
|
||||
isolated environment. This should not negatively affect Reticulum, but will not work
|
||||
for including and using Reticulum in your own scripts and programs.
|
||||
^^^^^^^^^^^^
|
||||
On versions of Ubuntu released after April 2023, it is no longer possible by default to use ``pip`` to install packages onto your system. Unfortunately, you will need to use the replacement ``pipx`` command instead, which places installed packages in an isolated environment. This should not negatively affect Reticulum, but will not work for including and using Reticulum in your own scripts and programs.
|
||||
|
||||
.. code:: shell
|
||||
|
||||
@@ -660,42 +491,29 @@ for including and using Reticulum in your own scripts and programs.
|
||||
# Install Reticulum
|
||||
pipx install rns
|
||||
|
||||
Alternatively, you can restore normal behaviour to ``pip`` by creating or editing
|
||||
the configuration file located at ``~/.config/pip/pip.conf``, and adding the
|
||||
following section:
|
||||
Alternatively, you can restore normal behaviour to ``pip`` by creating or editing the configuration file located at ``~/.config/pip/pip.conf``, and adding the following section:
|
||||
|
||||
.. code:: text
|
||||
|
||||
[global]
|
||||
break-system-packages = true
|
||||
|
||||
For a one-shot installation of Reticulum, without globally enabling the ``break-system-packages``
|
||||
option, you can use the following command:
|
||||
For a one-shot installation of Reticulum, without globally enabling the ``break-system-packages`` option, you can use the following command:
|
||||
|
||||
.. code:: text
|
||||
|
||||
pip install rns --break-system-packages
|
||||
|
||||
.. note::
|
||||
The ``--break-system-packages`` directive is a somewhat misleading choice
|
||||
of words. Setting it will of course not break any system packages, but will simply
|
||||
allow installing ``pip`` packages user- and system-wide. While this *could* in rare
|
||||
cases lead to version conflicts, it does not generally pose any problems, especially
|
||||
not in the case of installing Reticulum.
|
||||
The ``--break-system-packages`` directive is a somewhat misleading choice of words. Setting it will of course not break any system packages, but will simply allow installing ``pip`` packages user- and system-wide. While this *could* in rare cases lead to version conflicts, it does not generally pose any problems, especially not in the case of installing Reticulum.
|
||||
|
||||
Windows
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
On Windows operating systems, the easiest way to install Reticulum is by using the
|
||||
``pip`` package manager from the command line (either the command prompt or Windows
|
||||
Powershell).
|
||||
^^^^^^^
|
||||
On Windows operating systems, the easiest way to install Reticulum is by using the ``pip`` package manager from the command line (either the command prompt or Windows Powershell).
|
||||
|
||||
If you don't already have Python installed, `download and install Python <https://www.python.org/downloads/>`_.
|
||||
At the time of publication of this manual, the recommended version is `Python 3.12.7 <https://www.python.org/downloads/release/python-3127>`_.
|
||||
If you don't already have Python installed, `download and install Python <https://www.python.org/downloads/>`_. At the time of publication of this manual, the recommended version is `Python 3.12.7 <https://www.python.org/downloads/release/python-3127>`_.
|
||||
|
||||
**Important!** When asked by the installer, make sure to add the Python program to
|
||||
your PATH environment variables. If you don't do this, you will not be able to
|
||||
use the ``pip`` installer, or run the included Reticulum utility programs (such as
|
||||
``rnsd`` and ``rnstatus``) from the command line.
|
||||
**Important!** When asked by the installer, make sure to add the Python program to your PATH environment variables. If you don't do this, you will not be able to use the ``pip`` installer, or run the included Reticulum utility programs (such as ``rnsd`` and ``rnstatus``) from the command line.
|
||||
|
||||
After installing Python, open the command prompt or Windows Powershell, and type:
|
||||
|
||||
@@ -703,11 +521,10 @@ After installing Python, open the command prompt or Windows Powershell, and type
|
||||
|
||||
pip install rns
|
||||
|
||||
You can now use Reticulum and all included utility programs directly from your
|
||||
preferred command line interface.
|
||||
You can now use Reticulum and all included utility programs directly from your preferred command line interface.
|
||||
|
||||
Pure-Python Reticulum
|
||||
==============================================
|
||||
=====================
|
||||
|
||||
.. warning::
|
||||
If you use the ``rnspure`` package to run Reticulum on systems that
|
||||
@@ -715,17 +532,6 @@ Pure-Python Reticulum
|
||||
important that you read and understand the :ref:`Cryptographic Primitives <understanding-primitives>`
|
||||
section of this manual.
|
||||
|
||||
In some rare cases, and on more obscure system types, it is not possible to
|
||||
install one or more dependencies. In such situations,
|
||||
you can use the ``rnspure`` package instead of the ``rns`` package, or use ``pip``
|
||||
with the ``--no-dependencies`` command-line option. The ``rnspure``
|
||||
package requires no external dependencies for installation. Please note that the
|
||||
actual contents of the ``rns`` and ``rnspure`` packages are *completely identical*.
|
||||
The only difference is that the ``rnspure`` package lists no dependencies required
|
||||
for installation.
|
||||
In some rare cases, and on more obscure system types, it is not possible to install one or more dependencies. In such situations, you can use the ``rnspure`` package instead of the ``rns`` package, or use ``pip`` with the ``--no-dependencies`` command-line option. The ``rnspure`` package requires no external dependencies for installation. Please note that the actual contents of the ``rns`` and ``rnspure`` packages are *completely identical*. The only difference is that the ``rnspure`` package lists no dependencies required for installation.
|
||||
|
||||
No matter how Reticulum is installed and started, it will load external dependencies
|
||||
only if they are *needed* and *available*. If for example you want to use Reticulum
|
||||
on a system that cannot support ``pyserial``, it is perfectly possible to do so using
|
||||
the `rnspure` package, but Reticulum will not be able to use serial-based interfaces.
|
||||
All other available modules will still be loaded when needed.
|
||||
No matter how Reticulum is installed and started, it will load external dependencies only if they are *needed* and *available*. If for example you want to use Reticulum on a system that cannot support ``pyserial``, it is perfectly possible to do so using the `rnspure` package, but Reticulum will not be able to use serial-based interfaces. All other available modules will still be loaded when needed.
|
||||
|
||||
Reference in New Issue
Block a user