Reticulum/docs/source/gettingstartedfast.rst

374 lines
16 KiB
ReStructuredText
Raw Normal View History

2021-05-16 17:18:21 +00:00
********************
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.
2022-02-01 22:07:18 +00:00
2021-05-16 17:18:21 +00:00
Try Using a Reticulum-based Program
=============================================
2022-04-28 08:19:43 +00:00
If you simply want to try using a program built with Reticulum, a few different
programs exist that allow basic communication and a range of other useful functions
over even extremely low-bandwidth Reticulum networks.
These programs will let you get a feel for how Reticulum works. They have been designed
to run well over networks based on LoRa or packet radio, but can also be used completely
2022-08-05 21:38:23 +00:00
over local WiFi, wired Ethernet, the Internet, or any combination.
2022-04-28 08:19:43 +00:00
As such, it is easy to get started experimenting, without having to set up any radio
transceivers or infrastructure just to try it out. Launching the programs on separate
devices connected to the same WiFi network is enough to get started, and physical
radio interfaces can then be added later.
Nomad Network
^^^^^^^^^^^^^
The terminal-based program `Nomad Network <https://github.com/markqvist/nomadnet>`_
provides a complete encrypted communications suite built with Reticulum. It features
encrypted messaging (both direct and delayed-delivery for offline users), file sharing,
and has a built-in text-browser and page server with support for dynamically rendered pages,
user authentication and more.
2021-05-16 17:18:21 +00:00
2021-09-18 14:29:47 +00:00
.. image:: screenshots/nomadnet_3.png
:target: _images/nomadnet_3.png
2021-05-17 18:01:53 +00:00
`Nomad Network <https://github.com/markqvist/nomadnet>`_ is a user-facing client
2021-12-06 13:10:22 +00:00
for the messaging and information-sharing protocol
2021-05-17 18:01:53 +00:00
`LXMF <https://github.com/markqvist/lxmf>`_, another project built with Reticulum.
2021-09-18 14:29:47 +00:00
You can install Nomad Network via pip:
.. code::
2021-09-25 19:39:31 +00:00
# Install ...
2021-09-18 14:29:47 +00:00
pip3 install nomadnet
2021-09-25 19:39:31 +00:00
# ... and run
2021-09-18 14:29:47 +00:00
nomadnet
2022-02-01 22:07:18 +00:00
**Please Note**: If this is the very first time you use pip to install a program
on your system, you might need to reboot your system for your program to become
available. If you get a "command not found" error or similar when running the
program, reboot your system and try again.
2021-09-18 14:29:47 +00:00
2022-04-28 08:19:43 +00:00
Sideband
^^^^^^^^
2022-04-07 16:59:42 +00:00
If you would rather use a program with a graphical user interface, you can take
a look at `Sideband <https://unsigned.io/sideband>`_, which is available for Android,
Linux and macOS.
.. image:: screenshots/sideband_1.png
:align: center
:target: _images/sideband_1.png
2022-04-28 08:19:43 +00:00
Sideband is currently in the early stages of development, but already provides basic
communication features, and interoperates with Nomad Network, or any other LXMF client.
2021-09-18 14:29:47 +00:00
2021-10-08 16:30:17 +00:00
Using the Included Utilities
2021-09-25 19:39:31 +00:00
=============================================
2021-10-08 16:30:17 +00:00
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.
To learn more about these utility programs, have a look at the
:ref:`Using Reticulum on Your System<using-main>` chapter of this manual.
2021-09-25 19:39:31 +00:00
2022-02-01 22:07:18 +00:00
2021-10-08 16:30:17 +00:00
Creating a Network With Reticulum
=============================================
2021-09-25 19:39:31 +00:00
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
2022-09-30 18:37:03 +00:00
default is located at ``~/.reticulum/config``. You can edit this file by hand,
2021-12-06 13:10:22 +00:00
or use the interactive ``rnsconfig`` utility.
2021-09-25 19:39:31 +00:00
When Reticulum is started for the first time, it will create a default
configuration file, with one active interface. This default interface uses
2022-08-05 21:38:23 +00:00
your existing Ethernet and WiFi networks (if any), and only allows you to
2022-04-07 16:59:42 +00:00
communicate with other Reticulum peers within your local broadcast domains.
2021-09-25 19:39:31 +00:00
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.
2022-04-07 16:59:42 +00:00
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.
2022-06-22 13:19:18 +00:00
Once Reticulum knows which interfaces it should use, it will automatically
2022-04-07 16:59:42 +00:00
discover topography and configure transport of data to any destinations it
knows about.
2022-08-05 21:38:23 +00:00
In situations where you already have an established WiFi or Ethernet network, and
2022-06-22 13:19:18 +00:00
many devices that want to utilise the same external Reticulum network paths (for example over
2022-04-28 08:19:43 +00:00
LoRa), it will often be sufficient to let one system act as a Reticulum gateway, by
2022-06-22 13:19:18 +00:00
adding any external interfaces to the configuration of this system, and then enabling transport on it. Any
2022-04-28 08:19:43 +00:00
other device on your local WiFi will then be able to connect to this wider Reticulum
2022-06-22 13:19:18 +00:00
network just using the default (:ref:`AutoInterface<interfaces-auto>`) configuration.
2022-04-28 08:19:43 +00:00
2021-09-25 21:22:33 +00:00
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.
2021-09-25 19:39:31 +00:00
2022-04-07 16:59:42 +00:00
Connecting Reticulum Instances Over the Internet
================================================
2022-04-28 08:19:43 +00:00
Reticulum currently offers two interfaces suitable for connecting instances over the Internet: :ref:`TCP<interfaces-tcps>`
2022-04-07 16:59:42 +00:00
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.
2022-04-07 16:59:42 +00:00
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``,
2022-04-28 08:19:43 +00:00
however it also leaks more data about the server host.
2022-04-28 08:19:43 +00:00
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
2022-04-07 18:15:35 +00:00
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
2022-08-05 21:38:23 +00:00
packet inspection to learn that a system is running Reticulum, and what other IP addresses connect to it.
2022-04-07 18:15:35 +00:00
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
2022-06-22 13:19:18 +00:00
(I2P) <https://geti2p.net/en/>`_. To use this interface, users must also run an I2P daemon in
2022-04-28 08:19:43 +00:00
parallel to ``rnsd``. For always-on I2P nodes it is recommended to use `i2pd <https://i2pd.website/>`_.
2022-04-28 08:19:43 +00:00
By default, I2P will encrypt and mix all traffic sent over the Internet, and
2022-04-07 18:15:35 +00:00
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
2022-04-07 18:15:35 +00:00
deep-packet-inspection much more difficult.
2022-08-05 21:38:23 +00:00
I2P also allows users to host globally available Reticulum instances from non-public IP's and behind firewalls and NAT.
2022-08-05 21:38:23 +00:00
In general it is recommended to use an I2P node if you want to host a publicly accessible
2022-04-07 16:59:42 +00:00
instance, while preserving anonymity. If you care more about performance, and a slightly
easier setup, use TCP.
2022-06-22 13:19:18 +00:00
2022-04-07 18:15:35 +00:00
Connect to the Public Testnet
===========================================
An experimental public testnet has been made accessible over both I2P and TCP. You can join it
by adding one of the following interfaces to your ``.reticulum/config`` file:
.. code::
# TCP/IP interface to the Dublin hub
[[RNS Testnet Dublin]]
type = TCPClientInterface
enabled = yes
target_host = dublin.connect.reticulum.network
target_port = 4965
# TCP/IP interface to the Frankfurt hub
[[RNS Testnet Dublin]]
type = TCPClientInterface
enabled = yes
target_host = frankfurt.connect.reticulum.network
target_port = 5377
# Interface to I2P hub A
[[RNS Testnet I2P Hub A]]
type = I2PInterface
enabled = yes
peers = uxg5kubabakh3jtnvsipingbr5574dle7bubvip7llfvwx2tgrua.b32.i2p
2022-04-07 18:15:35 +00:00
Many other Reticulum instances are connecting to this testnet, and you can also join it
via other entry points if you know them. There is absolutely no control over the network
topography, usage or what types of instances connect. It will also occasionally be used
to test various failure scenarios, and there are no availability or service guarantees.
2022-06-22 13:19:18 +00:00
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.
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. 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>`. For more information on RNode, you can also
refer to these additional external resources:
* `How To Make Your Own RNodes <https://unsigned.io/how-to-make-your-own-rnodes/>`_
* `Installing RNode Firmware on Compatible LoRa Devices <https://unsigned.io/installing-rnode-firmware-on-t-beam-and-lora32-devices/>`_
* `Private, Secure and Uncensorable Messaging Over a LoRa Mesh <https://unsigned.io/private-messaging-over-lora/>`_
* `RNode Firmware <https://github.com/markqvist/RNode_Firmware/>`_
If you have communications hardware that is not already supported by any of the
:ref:`existing interface types<interfaces-main>`, but you think would be suitable for use with Reticulum,
you are welcome to head over to the `GitHub discussion pages <https://github.com/markqvist/Reticulum/discussions>`_
and propose adding an interface for the hardware.
2021-05-16 17:18:21 +00:00
Develop a Program with Reticulum
===========================================
If you want to develop programs that use Reticulum, the easiest way to get
2021-05-20 14:06:12 +00:00
started is to install the latest release of Reticulum via pip:
2021-05-16 17:18:21 +00:00
.. code::
pip3 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
2021-05-16 19:58:11 +00:00
likely be to look at some :ref:`Example Programs<examples-main>`.
2021-05-16 17:18:21 +00:00
2021-12-02 17:33:00 +00:00
For extended functionality, you can install optional dependencies:
.. code::
pip3 install pyserial netifaces
2021-05-16 19:58:11 +00:00
Further information can be found in the :ref:`API Reference<api-main>`.
2021-05-16 17:18:21 +00:00
Participate in Reticulum Development
==============================================
If you want to participate in the development of Reticulum and associated
utilities, you'll want to get the latest source from GitHub. In that case,
don't use pip, but try this recipe:
.. code::
# Install dependencies
2021-09-25 19:39:31 +00:00
pip3 install cryptography pyserial netifaces
2021-05-16 17:18:21 +00:00
# Clone repository
git clone https://github.com/markqvist/Reticulum.git
# Move into Reticulum folder and symlink library to examples folder
cd Reticulum
ln -s ../RNS ./Examples/
# Run an example
python3 Examples/Echo.py -s
# Unless you've manually created a config file, Reticulum will do so now,
# and immediately exit. Make any necessary changes to the file:
2022-09-30 18:37:03 +00:00
nano ~/.reticulum/config
2021-05-16 17:18:21 +00:00
# ... and launch the example again.
python3 Examples/Echo.py -s
# You can now repeat the process on another computer,
# and run the same example with -h to get command line options.
python3 Examples/Echo.py -h
# Run the example in client mode to "ping" the server.
# Replace the hash below with the actual destination hash of your server.
python3 Examples/Echo.py 3e12fc71692f8ec47bc5
# Have a look at another example
python3 Examples/Filetransfer.py -h
When you have experimented with the basic examples, it's time to go read the
2022-10-06 15:35:38 +00:00
:ref:`Understanding Reticulum<understanding-main>` chapter. Before submitting
your first pull request, it is probably a good idea to introduce yourself on
the `disucssion forum on GitHub <https://github.com/markqvist/Reticulum/discussions>`_,
or ask one of the developers or maintainers for a good place to start.
2021-12-05 22:24:30 +00:00
2021-12-09 17:12:18 +00:00
Reticulum on ARM64
==============================================
On some architectures, including ARM64, not all dependencies have precompiled
binaries. On such systems, you will need to install ``python3-dev`` before
installing Reticulum or programs that depend on Reticulum.
.. code::
# Install Python and development packages
sudo apt update
sudo apt install python3 python3-pip python3-dev
# Install Reticulum
python3 -m pip install rns
2021-12-05 22:24:30 +00:00
Reticulum on Android
==============================================
Reticulum can be used on Android in different ways. The easiest way to get
2022-04-07 16:59:42 +00:00
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>`_.
2021-12-05 22:26:52 +00:00
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.
2021-12-05 22:24:30 +00:00
Since the Python cryptography.io module does not offer pre-built wheels for
Android, the standard one-line install of Reticulum does not work on Android,
and a few extra commands are required.
From within Termux, execute the following:
.. code::
# First, make sure indexes and packages are up to date.
pkg update
pkg upgrade
2021-12-06 13:10:22 +00:00
# Then install dependencies for the cryptography library.
2021-12-05 22:24:30 +00:00
pkg install python build-essential openssl libffi rust
2021-12-05 22:28:15 +00:00
# Make sure pip is up to date, and install the wheel module.
2021-12-05 22:24:30 +00:00
pip3 install wheel pip --upgrade
2021-12-09 17:53:28 +00:00
# To allow the installer to build the cryptography module,
# we need to let it know what platform we are compiling for:
export CARGO_BUILD_TARGET="aarch64-linux-android"
2021-12-05 22:24:30 +00:00
# Start the install process for the cryptography module.
# Depending on your device, this can take several minutes,
# since the module must be compiled locally on your device.
pip3 install cryptography
# If the above installation succeeds, you can now install
# Reticulum and any related software
pip3 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
2022-10-06 15:35:38 +00:00
here at a later point. Until then you can use the `Sideband source code <https://github.com/markqvist/sideband>`_ as an example and startig point.
2022-04-07 16:59:42 +00:00
2022-06-22 13:19:18 +00:00
Pure-Python Reticulum
2022-04-07 16:59:42 +00:00
==============================================
2022-06-22 13:19:18 +00:00
In some rare cases, and on more obscure system types, it is not possible to
install one or more dependencies
On more unusual systems, and in some rare cases, it might not be possible to
install or even compile one or more of the above modules. In such situations,
you can use the ``rnspure`` package instead of the ``rns`` package. 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.
**Please Note!** If you use the `rnspure` package to run Reticulum on systems that
do not support `PyCA/cryptography <https://github.com/pyca/cryptography>`_, it is
important that you read and understand the :ref:`Cryptographic Primitives <understanding-primitives>`
2022-08-05 21:38:23 +00:00
section of this manual.