William/Reticulum
1
0
Fork 0
mirror of https://github.com/markqvist/Reticulum.git synced 2024-11-22 21:50:18 +00:00
Code Issues Packages Projects Releases Wiki Activity

Updated docs

Browse Source
This commit is contained in:
Mark Qvist 2023-02-02 19:04:52 +01:00
parent 08e480387b
commit 86ae42a049
8 changed files with 30 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
docs/Reticulum Manual.pdf
View File

Binary file not shown.

4
docs/manual/_sources/gettingstartedfast.rst.txt
View File

@ -115,8 +115,8 @@ Creating a Network With Reticulum
============================================= =============================================
To create a network, you will need to specify one or more *interfaces* for 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 Reticulum to use. This is done in the Reticulum configuration file, which by
default is located at ``~/.reticulum/config``. You can edit this file by hand, default is located at ``~/.reticulum/config``. You can get an example
or use the interactive ``rnsconfig`` utility. configuration file with all options via ``rnsd --exampleconfig``.
When Reticulum is started for the first time, it will create a default When Reticulum is started for the first time, it will create a default
configuration file, with one active interface. This default interface uses configuration file, with one active interface. This default interface uses

22
docs/manual/_sources/understanding.rst.txt
View File

@ -107,13 +107,13 @@ guide the design of Reticulum:
Introduction & Basic Functionality Introduction & Basic Functionality
================================== ==================================
Reticulum is a networking stack suited for high-latency, low-bandwidth links. Reticulum is at it’s Reticulum is a networking stack suited for high-latency, low-bandwidth links. Reticulum is at its
core a *message oriented* system. It is suited for both local point-to-point or point-to-multipoint core a *message oriented* system. It is suited for both local point-to-point or point-to-multipoint
scenarios where all nodes are within range of each other, as well as scenarios where packets need scenarios where all nodes are within range of each other, as well as scenarios where packets need
to be transported over multiple hops in a complex network to reach the recipient. to be transported over multiple hops in a complex network to reach the recipient.
Reticulum does away with the idea of addresses and ports known from IP, TCP and UDP. Instead Reticulum does away with the idea of addresses and ports known from IP, TCP and UDP. Instead
Reticulum uses the singular concept of *destinations*. Any application using Reticulum as it’s Reticulum uses the singular concept of *destinations*. Any application using Reticulum as its
networking stack will need to create one or more destinations to receive data, and know the networking stack will need to create one or more destinations to receive data, and know the
destinations it needs to send data to. destinations it needs to send data to.
@ -220,7 +220,7 @@ packet.
In actual use of *single* destination naming, it is advisable not to use any uniquely identifying In actual use of *single* destination naming, it is advisable not to use any uniquely identifying
features in aspect naming. Aspect names should be general terms describing what kind of destination features in aspect naming. Aspect names should be general terms describing what kind of destination
is represented. The uniquely identifying aspect is always achieved by the appending the public key, is represented. The uniquely identifying aspect is always achieved by appending the public key,
which expands the destination into a uniquely identifiable one. Reticulum does this automatically. which expands the destination into a uniquely identifiable one. Reticulum does this automatically.
Any destination on a Reticulum network can be addressed and reached simply by knowing its Any destination on a Reticulum network can be addressed and reached simply by knowing its
@ -239,7 +239,7 @@ To recap, the different destination types should be used in the following situat
* **Plain** * **Plain**
When plain-text communication is desirable, for example when broadcasting information, or for local discovery purposes. When plain-text communication is desirable, for example when broadcasting information, or for local discovery purposes.
To communicate with a *single* destination, you need to know it’s public key. Any method for To communicate with a *single* destination, you need to know its public key. Any method for
obtaining the public key is valid, but Reticulum includes a simple mechanism for making other obtaining the public key is valid, but Reticulum includes a simple mechanism for making other
nodes aware of your destinations public key, called the *announce*. It is also possible to request nodes aware of your destinations public key, called the *announce*. It is also possible to request
an unknown public key from the network, as all transport instances serve as a distributed ledger an unknown public key from the network, as all transport instances serve as a distributed ledger
@ -287,7 +287,7 @@ In Reticulum, destinations are allowed to move around the network at will. This
protocols such as IP, where an address is always expected to stay within the network segment it was assigned in. protocols such as IP, where an address is always expected to stay within the network segment it was assigned in.
This limitation does not exist in Reticulum, and any destination is *completely portable* over the entire topography This limitation does not exist in Reticulum, and any destination is *completely portable* over the entire topography
of the network, and *can even be moved to other Reticulum networks* than the one it was created in, and of the network, and *can even be moved to other Reticulum networks* than the one it was created in, and
still become reachable. To update it's reachability, a destination simply needs to send an announce on any still become reachable. To update its reachability, a destination simply needs to send an announce on any
networks it is part of. After a short while, it will be globally reachable in the network. networks it is part of. After a short while, it will be globally reachable in the network.
Seeing how *single* destinations are always tied to a private/public key pair leads us to the next topic. Seeing how *single* destinations are always tied to a private/public key pair leads us to the next topic.
@ -368,7 +368,7 @@ If it is a *Transport Node*, it should be given the configuration directive ``en
The Announce Mechanism in Detail The Announce Mechanism in Detail
-------------------------------- --------------------------------
When an *announce* for a destination is transmitted by from a Reticulum instance, it will be forwarded by When an *announce* for a destination is transmitted by a Reticulum instance, it will be forwarded by
any transport node receiving it, but according to some specific rules: any transport node receiving it, but according to some specific rules:
@ -385,7 +385,7 @@ any transport node receiving it, but according to some specific rules:
announces is set at 2%, but can be configured on a per-interface basis. announces is set at 2%, but can be configured on a per-interface basis.
* | If any given interface does not have enough bandwidth available for retransmitting the announce, * | If any given interface does not have enough bandwidth available for retransmitting the announce,
the announce will be assigned a priority inversely proportional to it's hop count, and be inserted the announce will be assigned a priority inversely proportional to its hop count, and be inserted
into a queue managed by the interface. into a queue managed by the interface.
* | When the interface has bandwidth available for processing an announce, it will prioritise announces * | When the interface has bandwidth available for processing an announce, it will prioritise announces
@ -431,7 +431,7 @@ For exchanges of small amounts of information, Reticulum offers the *Packet* API
* | A packet is always created with an associated destination and some payload data. When the packet is sent * | A packet is always created with an associated destination and some payload data. When the packet is sent
to a *single* destination type, Reticulum will automatically create an ephemeral encryption key, perform to a *single* destination type, Reticulum will automatically create an ephemeral encryption key, perform
an ECDH key exchange with the destinations public key, and encrypt the information. an ECDH key exchange with the destination's public key, and encrypt the information.
* | It is important to note that this key exchange does not require any network traffic. The sender already * | It is important to note that this key exchange does not require any network traffic. The sender already
knows the public key of the destination from an earlier received *announce*, and can thus perform the ECDH knows the public key of the destination from an earlier received *announce*, and can thus perform the ECDH
@ -447,8 +447,8 @@ For exchanges of small amounts of information, Reticulum offers the *Packet* API
* | Once the packet has been received and decrypted by the addressed destination, that destination can opt * | Once the packet has been received and decrypted by the addressed destination, that destination can opt
to *prove* its receipt of the packet. It does this by calculating the SHA-256 hash of the received packet, to *prove* its receipt of the packet. It does this by calculating the SHA-256 hash of the received packet,
and signing this hash with it's Ed25519 signing key. Transport nodes in the network can then direct this and signing this hash with its Ed25519 signing key. Transport nodes in the network can then direct this
*proof* back to the packets origin, where the signature can be verified against the destinations known *proof* back to the packets origin, where the signature can be verified against the destination's known
public signing key. public signing key.
* | In case the packet is addressed to a *group* destination type, the packet will be encrypted with the * | In case the packet is addressed to a *group* destination type, the packet will be encrypted with the
@ -465,7 +465,7 @@ For exchanges of larger amounts of data, or when longer sessions of bidirectiona
forward the packet will take note of this *link request*. forward the packet will take note of this *link request*.
* | Second, if the destination accepts the *link request* , it will send back a packet that proves the * | Second, if the destination accepts the *link request* , it will send back a packet that proves the
authenticity of it’s identity (and the receipt of the link request) to the initiating node. All authenticity of its identity (and the receipt of the link request) to the initiating node. All
nodes that initially forwarded the packet will also be able to verify this proof, and thus nodes that initially forwarded the packet will also be able to verify this proof, and thus
accept the validity of the *link* throughout the network. accept the validity of the *link* throughout the network.

2
docs/manual/_sources/using.rst.txt
View File

@ -377,7 +377,7 @@ output.
# Run rnx on the listening system, specifying which identities # Run rnx on the listening system, specifying which identities
# are allowed to execute commands # are allowed to execute commands
rncp --listen -a 941bed5e228775e5a8079fc38b1ccf3f -a 1b03013c25f1c2ca068a4f080b844a10 rnx --listen -a 941bed5e228775e5a8079fc38b1ccf3f -a 1b03013c25f1c2ca068a4f080b844a10
# From another system, run a command # From another system, run a command
rnx 7a55144adf826958a9529a3bcf08b149 "cat /proc/cpuinfo" rnx 7a55144adf826958a9529a3bcf08b149 "cat /proc/cpuinfo"

4
docs/manual/gettingstartedfast.html
View File

@ -304,8 +304,8 @@ network status and connectivity.</p>
<h2>Creating a Network With Reticulum<a class="headerlink" href="#creating-a-network-with-reticulum" title="Permalink to this heading">#</a></h2> <h2>Creating a Network With Reticulum<a class="headerlink" href="#creating-a-network-with-reticulum" title="Permalink to this heading">#</a></h2>
<p>To create a network, you will need to specify one or more <em>interfaces</em> for <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 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 edit this file by hand, default is located at <code class="docutils literal notranslate"><span class="pre">~/.reticulum/config</span></code>. You can get an example
or use the interactive <code class="docutils literal notranslate"><span class="pre">rnsconfig</span></code> utility.</p> 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 <p>When Reticulum is started for the first time, it will create a default
configuration file, with one active interface. This default interface uses configuration file, with one active interface. This default interface uses
your existing Ethernet and WiFi networks (if any), and only allows you to your existing Ethernet and WiFi networks (if any), and only allows you to

2
docs/manual/searchindex.js
View File

File diff suppressed because one or more lines are too long

22
docs/manual/understanding.html
View File

@ -337,12 +337,12 @@ needs to be purchased.</p>
</section> </section>
<section id="introduction-basic-functionality"> <section id="introduction-basic-functionality">
<span id="understanding-basicfunctionality"></span><h2>Introduction &amp; Basic Functionality<a class="headerlink" href="#introduction-basic-functionality" title="Permalink to this heading">#</a></h2> <span id="understanding-basicfunctionality"></span><h2>Introduction &amp; Basic Functionality<a class="headerlink" href="#introduction-basic-functionality" title="Permalink to this heading">#</a></h2>
<p>Reticulum is a networking stack suited for high-latency, low-bandwidth links. Reticulum is at it’s <p>Reticulum is a networking stack suited for high-latency, low-bandwidth links. Reticulum is at its
core a <em>message oriented</em> system. It is suited for both local point-to-point or point-to-multipoint core a <em>message oriented</em> system. It is suited for both local point-to-point or point-to-multipoint
scenarios where all nodes are within range of each other, as well as scenarios where packets need scenarios where all nodes are within range of each other, as well as scenarios where packets need
to be transported over multiple hops in a complex network to reach the recipient.</p> to be transported over multiple hops in a complex network to reach the recipient.</p>
<p>Reticulum does away with the idea of addresses and ports known from IP, TCP and UDP. Instead <p>Reticulum does away with the idea of addresses and ports known from IP, TCP and UDP. Instead
Reticulum uses the singular concept of <em>destinations</em>. Any application using Reticulum as it’s Reticulum uses the singular concept of <em>destinations</em>. Any application using Reticulum as its
networking stack will need to create one or more destinations to receive data, and know the networking stack will need to create one or more destinations to receive data, and know the
destinations it needs to send data to.</p> destinations it needs to send data to.</p>
<p>All destinations in Reticulum are _represented_ as a 16 byte hash. This hash is derived from truncating a full <p>All destinations in Reticulum are _represented_ as a 16 byte hash. This hash is derived from truncating a full
@ -442,7 +442,7 @@ addressable, because their public keys will differ.</p></li>
</ul> </ul>
<p>In actual use of <em>single</em> destination naming, it is advisable not to use any uniquely identifying <p>In actual use of <em>single</em> destination naming, it is advisable not to use any uniquely identifying
features in aspect naming. Aspect names should be general terms describing what kind of destination features in aspect naming. Aspect names should be general terms describing what kind of destination
is represented. The uniquely identifying aspect is always achieved by the appending the public key, is represented. The uniquely identifying aspect is always achieved by appending the public key,
which expands the destination into a uniquely identifiable one. Reticulum does this automatically.</p> which expands the destination into a uniquely identifiable one. Reticulum does this automatically.</p>
<p>Any destination on a Reticulum network can be addressed and reached simply by knowing its <p>Any destination on a Reticulum network can be addressed and reached simply by knowing its
destination hash (and public key, but if the public key is not known, it can be requested from the destination hash (and public key, but if the public key is not known, it can be requested from the
@ -468,7 +468,7 @@ indirectly, but must first be established through a <em>single</em> destination.
</dl> </dl>
</li> </li>
</ul> </ul>
<p>To communicate with a <em>single</em> destination, you need to know it’s public key. Any method for <p>To communicate with a <em>single</em> destination, you need to know its public key. Any method for
obtaining the public key is valid, but Reticulum includes a simple mechanism for making other obtaining the public key is valid, but Reticulum includes a simple mechanism for making other
nodes aware of your destinations public key, called the <em>announce</em>. It is also possible to request nodes aware of your destinations public key, called the <em>announce</em>. It is also possible to request
an unknown public key from the network, as all transport instances serve as a distributed ledger an unknown public key from the network, as all transport instances serve as a distributed ledger
@ -509,7 +509,7 @@ certain pattern. This will be detailed in the section
protocols such as IP, where an address is always expected to stay within the network segment it was assigned in. protocols such as IP, where an address is always expected to stay within the network segment it was assigned in.
This limitation does not exist in Reticulum, and any destination is <em>completely portable</em> over the entire topography This limitation does not exist in Reticulum, and any destination is <em>completely portable</em> over the entire topography
of the network, and <em>can even be moved to other Reticulum networks</em> than the one it was created in, and of the network, and <em>can even be moved to other Reticulum networks</em> than the one it was created in, and
still become reachable. To update it’s reachability, a destination simply needs to send an announce on any still become reachable. To update its reachability, a destination simply needs to send an announce on any
networks it is part of. After a short while, it will be globally reachable in the network.</p> networks it is part of. After a short while, it will be globally reachable in the network.</p>
<p>Seeing how <em>single</em> destinations are always tied to a private/public key pair leads us to the next topic.</p> <p>Seeing how <em>single</em> destinations are always tied to a private/public key pair leads us to the next topic.</p>
</section> </section>
@ -565,7 +565,7 @@ is the default setting.</p>
</section> </section>
<section id="the-announce-mechanism-in-detail"> <section id="the-announce-mechanism-in-detail">
<span id="understanding-announce"></span><h3>The Announce Mechanism in Detail<a class="headerlink" href="#the-announce-mechanism-in-detail" title="Permalink to this heading">#</a></h3> <span id="understanding-announce"></span><h3>The Announce Mechanism in Detail<a class="headerlink" href="#the-announce-mechanism-in-detail" title="Permalink to this heading">#</a></h3>
<p>When an <em>announce</em> for a destination is transmitted by from a Reticulum instance, it will be forwarded by <p>When an <em>announce</em> for a destination is transmitted by a Reticulum instance, it will be forwarded by
any transport node receiving it, but according to some specific rules:</p> any transport node receiving it, but according to some specific rules:</p>
<ul> <ul>
<li><div class="line-block"> <li><div class="line-block">
@ -590,7 +590,7 @@ announces is set at 2%, but can be configured on a per-interface basis.</div>
</li> </li>
<li><div class="line-block"> <li><div class="line-block">
<div class="line">If any given interface does not have enough bandwidth available for retransmitting the announce, <div class="line">If any given interface does not have enough bandwidth available for retransmitting the announce,
the announce will be assigned a priority inversely proportional to it’s hop count, and be inserted the announce will be assigned a priority inversely proportional to its hop count, and be inserted
into a queue managed by the interface.</div> into a queue managed by the interface.</div>
</div> </div>
</li> </li>
@ -639,7 +639,7 @@ expect. Reticulum offers two ways to do this.</p>
<li><div class="line-block"> <li><div class="line-block">
<div class="line">A packet is always created with an associated destination and some payload data. When the packet is sent <div class="line">A packet is always created with an associated destination and some payload data. When the packet is sent
to a <em>single</em> destination type, Reticulum will automatically create an ephemeral encryption key, perform to a <em>single</em> destination type, Reticulum will automatically create an ephemeral encryption key, perform
an ECDH key exchange with the destinations public key, and encrypt the information.</div> an ECDH key exchange with the destination’s public key, and encrypt the information.</div>
</div> </div>
</li> </li>
<li><div class="line-block"> <li><div class="line-block">
@ -665,8 +665,8 @@ packet.</div>
<li><div class="line-block"> <li><div class="line-block">
<div class="line">Once the packet has been received and decrypted by the addressed destination, that destination can opt <div class="line">Once the packet has been received and decrypted by the addressed destination, that destination can opt
to <em>prove</em> its receipt of the packet. It does this by calculating the SHA-256 hash of the received packet, to <em>prove</em> its receipt of the packet. It does this by calculating the SHA-256 hash of the received packet,
and signing this hash with it’s Ed25519 signing key. Transport nodes in the network can then direct this and signing this hash with its Ed25519 signing key. Transport nodes in the network can then direct this
<em>proof</em> back to the packets origin, where the signature can be verified against the destinations known <em>proof</em> back to the packets origin, where the signature can be verified against the destination’s known
public signing key.</div> public signing key.</div>
</div> </div>
</li> </li>
@ -689,7 +689,7 @@ forward the packet will take note of this <em>link request</em>.</div>
</li> </li>
<li><div class="line-block"> <li><div class="line-block">
<div class="line">Second, if the destination accepts the <em>link request</em> , it will send back a packet that proves the <div class="line">Second, if the destination accepts the <em>link request</em> , it will send back a packet that proves the
authenticity of it’s identity (and the receipt of the link request) to the initiating node. All authenticity of its identity (and the receipt of the link request) to the initiating node. All
nodes that initially forwarded the packet will also be able to verify this proof, and thus nodes that initially forwarded the packet will also be able to verify this proof, and thus
accept the validity of the <em>link</em> throughout the network.</div> accept the validity of the <em>link</em> throughout the network.</div>
</div> </div>

2
docs/manual/using.html
View File

@ -557,7 +557,7 @@ execute commands on remote systems over Reticulum, and to view returned command
output.</p> output.</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span># Run rnx on the listening system, specifying which identities <div class="highlight-text notranslate"><div class="highlight"><pre><span></span># Run rnx on the listening system, specifying which identities
# are allowed to execute commands # are allowed to execute commands
rncp --listen -a 941bed5e228775e5a8079fc38b1ccf3f -a 1b03013c25f1c2ca068a4f080b844a10 rnx --listen -a 941bed5e228775e5a8079fc38b1ccf3f -a 1b03013c25f1c2ca068a4f080b844a10
# From another system, run a command # From another system, run a command
rnx 7a55144adf826958a9529a3bcf08b149 &quot;cat /proc/cpuinfo&quot; rnx 7a55144adf826958a9529a3bcf08b149 &quot;cat /proc/cpuinfo&quot;