From b6f0784311fc6e3601d958083d40fec1a1a08583 Mon Sep 17 00:00:00 2001 From: Mark Qvist Date: Mon, 18 Sep 2023 12:35:54 +0200 Subject: [PATCH] Added rnid utility to manual. Updated communications hardware section. --- docs/source/hardware.rst | 58 +++++++++++++++++-------- docs/source/using.rst | 92 ++++++++++++++++++++++++++++++++++++++-- 2 files changed, 128 insertions(+), 22 deletions(-) diff --git a/docs/source/hardware.rst b/docs/source/hardware.rst index d82d581..e676949 100644 --- a/docs/source/hardware.rst +++ b/docs/source/hardware.rst @@ -24,11 +24,20 @@ starting from scratch. This chapter will outline a few different sensible starting paths to get real-world functional wireless communications up and running with minimal cost and effort. Two fundamental devices categories will be covered, *RNodes* and -*WiFi-based radios*. +*WiFi-based radios*. Additionally, other common options will be briefly described. + +Knowing how to employ just a few different types of hardware will make it possible +to build a wide range of useful networks with little effort. + +Combining Hardware Types +======================== + +It is useful to combine different link and hardware types when designing and +building a network. One useful design pattern is to employ high-capacity point-to-point +links based on WiFi or millimeter-wave radios (with high-gain directional antennas) +for the network backbone, and using LoRa-based RNodes for covering large areas with +connectivity for client devices. -While there are many other device categories that are useful in building Reticulum -networks, knowing how to employ just these two will make it possible to build -a wide range of useful networks with little effort. .. _rnode-main: @@ -190,13 +199,6 @@ such as serial port and on-air parameters. For v2.x firmwares, you just need to the Connection ID of the RNode, and Reticulum will automatically locate and connect to the RNode, using the parameters stored in the RNode itself. -.. _rnode-suppliers: - -Suppliers -^^^^^^^^^ -Get in touch if you want to have your RNode supplier listed here, or if you want help to -get started with producing RNodes. - WiFi-based Hardware =================== @@ -231,11 +233,31 @@ that is relatively cheap while providing long range and high capacity for Reticu networks. As in all other cases, it is also possible for Reticulum to co-exist with IP networks running concurrently on such devices. -Combining Hardware Types -======================== +Ethernet-based Hardware +======================= -It is useful to combine different link and hardware types when designing and -building a network. One useful design pattern is to employ high-capacity point-to-point -links based on WiFi or millimeter-wave radios (with high-gain directional antennas) -for the network backbone, and using LoRa-based RNodes for covering large areas with -connectivity for client devices. +Reticulum can run over any kind of hardware that can provide a switched Ethernet-based +medium. This means that anything from a plain Ethernet switch, to fiber-optic systems, +to data radios with Ethernet interfaces can be used by Reticulum. + +The Ethernet medium does not need to have any IP infrastructure such as DHCP servers +or routing set up, but in case such infrastructure does exist, Reticulum will simply +co-exist with. + +To use Reticulum over Ethernet-based mediums, it is generally enough to use the included +:ref:`AutoInterface`. This interface also works over any kind of +virtual networking adapter, such as ``tun`` and ``tap`` devices in Linux. + +Serial Lines & Devices +====================== + +Using Reticulum over any kind of raw serial line is also possible with the +:ref:`SerialInterface`. This interface type is also useful for +using Reticulum over communications hardware that provides a serial port interface. + +Packet Radio Modems +=================== + +Any packet radio modem that provides a standard KISS interface over USB, serial or TCP +can be used with Reticulum. This includes virtual software modems such as +`FreeDV TNC `_ and `Dire Wolf `_. diff --git a/docs/source/using.rst b/docs/source/using.rst index d80e811..44e8491 100644 --- a/docs/source/using.rst +++ b/docs/source/using.rst @@ -145,10 +145,19 @@ configuration file is created. The default configuration looks like this: If Reticulum infrastructure already exists locally, you probably don't need to change anything, and you may already be connected to a wider network. If not, you will probably need to add relevant *interfaces* to the configuration, in -order to communicate with other systems. It is a good idea to read the comments -and explanations in the above default config. It will teach you the basic -concepts you need to understand to configure your network. Once you have done that, -take a look at the :ref:`Interfaces` chapter of this manual. +order to communicate with other systems. + +You can generate a much more verbose configuration example by running the command: + +``rnsd --exampleconfig`` + +The output includes examples for most interface types supported +by Reticulum, along with additional options and configuration parameters. + +It is a good idea to read the comments and explanations in the above default config. +It will teach you the basic concepts you need to understand to configure your network. +Once you have done that, take a look at the :ref:`Interfaces` chapter +of this manual. Included Utility Programs ------------------------- @@ -254,6 +263,81 @@ interfaces, similar to the ``ifconfig`` program. -v, --verbose +The rnid Utility +==================== + +With the ``rnid`` utility, you can generate, manage and view Reticulum Identities. +The program can also calculate Destination hashes, and perform encryption and +decryption of files. Using ``rnid``, it is possible to asymmetrically encrypt +files and information for any destination hash, and also to create and verify +cryptographic signatures. + +.. code:: text + + # Generate a new Identity + rnid -g ./new_identity + + # Display Identity key information + rnid -i ./new_identity -p + + Loaded Identity <984b74a3f768bef236af4371e6f248cd> from new_id + Public Key : 0f4259fef4521ab75a3409e353fe9073eb10783b4912a6a9937c57bf44a62c1e + Private Key : Hidden + + # Encrypt a file for an LXMF user + rnid -i 8dd57a738226809646089335a6b03695 -e my_file.txt + + Recalled Identity for destination <8dd57a738226809646089335a6b03695> + Encrypting my_file.txt + File my_file.txt encrypted for to my_file.txt.rfe + + # If the Identity for the destination is not already known, + # you can fetch it from the network by using the -R option + rnid -R -i 30602def3b3506a28ed33db6f60cc6c9 -e my_file.txt + + Requesting unknown Identity for <30602def3b3506a28ed33db6f60cc6c9>... + Received Identity <2b489d06eaf7c543808c76a5332a447d> for destination <30602def3b3506a28ed33db6f60cc6c9> from the network + Encrypting my_file.txt + File my_file.txt encrypted for <2b489d06eaf7c543808c76a5332a447d> to my_file.txt.rfe + +.. code:: text + + usage: rnid [-h] [--config path] [-i identity] [-g path] [-v] [-q] [-a aspects] [-H aspects] [-e path] [-d path] [-s path] [-V path] [-r path] [-w path] [-f] [-R] [-t seconds] [-p] [-P] + [--version] + + Reticulum Identity & Encryption Utility + + options: + -h, --help show this help message and exit + --config path path to alternative Reticulum config directory + -i identity, --identity identity + hexadecimal Reticulum Destination hash or path to Identity file + -g path, --generate path + generate a new Identity + -v, --verbose increase verbosity + -q, --quiet decrease verbosity + -a aspects, --announce aspects + announce a destination based on this Identity + -H aspects, --hash aspects + show destination hashes for other aspects for this Identity + -e path, --encrypt path + encrypt file + -d path, --decrypt path + decrypt file + -s path, --sign path sign file + -V path, --validate path + validate signature + -r path, --read path input file path + -w path, --write path + output file path + -f, --force write output even if it overwrites existing files + -R, --request request unknown Identities from the network + -t seconds identity request timeout before giving up + -p, --print-identity print identity info and exit + -P, --print-private allow displaying private keys + --version show program's version number and exit + + The rnpath Utility ====================