Mirror/Reticulum
1
0
Fork 0
mirror of https://github.com/markqvist/Reticulum.git synced 2026-06-08 14:11:53 -07:00
Code Issues Packages Projects Releases Wiki Activity

Updated rngit documentation

Browse Source
This commit is contained in:
Mark Qvist
2026-05-28 17:43:35 +02:00
parent 2cf07099e3
commit c59f1e3dd6
10 changed files with 93 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/manual/_sources/git.rst.txt
+20 -12
View File
@@ -853,10 +853,28 @@ Or to retrieve all source archives:
If your pattern contains no wildcard characters, it must match an artifact name exactly, which is useful for fetching single, specific artifacts. When a pattern matches multiple artifacts, all matched files are fetched and verified. If no artifacts match the pattern, the fetch aborts with an error indicating no matches were found.
**Offline Verification**
Offline Verification
--------------------
Because the release manifest contains embedded signatures, you can verify the integrity of release artifacts offline, without connecting to the repository node. The ``rnid`` and ``rngit`` utilities can validate artifact signatures against ``.rsg`` and manifest files.
**Using a release manifest:**
Ensure the release manifest is located in the same directory as the release artifacts, then run:
.. code:: text
# Verify all artifacts in the manifest
$ rngit release myapp-1.2.0.rsm verify
# Or, verify only specific artifacts
$ rngit release myapp-1.2.0.rsm verify "latest:*.whl"
This will load the manifest, and verify all files currently on-disk, but will not attempt to fetch the latest release manifest from the origin, or update local files to match it.
.. note::
The ``verify`` operation is functionally equivalent to using the ``fetch`` operation with the ``--offline`` flag, and they can be used interchangably.
**For individual files:**
Ensure the ``.rsg`` signature is located in the same directory as the release artifact, then run:
@@ -867,16 +885,6 @@ Ensure the ``.rsg`` signature is located in the same directory as the release ar
This validates that the artifact file matches the signature created during the release process. Combined with the manifest's own signature, this provides end-to-end verification from the original release creation to the final installation.
**For a complete release:**
Ensure the release manifest is located in the same directory as the release artifacts, then run:
.. code:: text
$ rngit release myapp-1.2.0.rsm fetch --offline
This will load the manifest, and verify all files currently on-disk, but will not attempt to fetch the latest release manifest from the origin, or update local files to match it.
.. _git-release-create:
Creating Signed Releases
@@ -886,7 +894,7 @@ Reticulum and the ``rngit`` system makes it easy to create signed releases that
1. Generates an Ed25519 signature for each artifact file using your identity's signing key
2. Creates ``.rsg`` signature files alongside each artifact in your distribution directory
3. Constructs a signed release manifest (``manifest.rsm``) containing metadata, an artifact list, and embedded signatures
3. Constructs a signed ``manifest.rsm`` release manifest containing metadata, an artifact list, and embedded signatures
4. Transmits both artifacts, signatures and manifest to the remote node specified as release origin
As an example, to create and publish a release from all files in the folder named ``dist``, simply run:
docs/manual/_sources/using.rst.txt
+4 -1
View File
@@ -1316,7 +1316,7 @@ To see all identities currently blackholed on your local instance, use the ``-b`
Automated List Sourcing
=======================
Manually blocking identities is effective for immediate threats, but maintaining an up-to-date blocklist for a large network is impractical. Reticulum supports **automated list sourcing**, allowing your node to subscribe to blackhole lists maintained by trusted peers, or a central authority you manage yourself.
Manually blocking identities is effective for immediate threats and annoyances, but maintaining an up-to-date blocklist across many nodes on a large network is impractical. Reticulum supports **automated list sourcing**, allowing your node to subscribe to blackhole lists maintained by trusted peers, or a central authority you manage yourself.
.. warning::
**Verify Before Subscribing!** Subscribing to a blackhole source is a powerful action that grants that source the ability to dictate who you can communicate with. Before adding a source to your configuration, verify that the maintainer aligns with your usage policy and values. Blindly subscribing to untrusted lists could inadvertently block legitimate peers or essential services.
@@ -1333,6 +1333,9 @@ To enable automated sourcing, add the ``blackhole_sources`` option to the ``[ret
...
# Automatically fetch blackhole lists from these trusted sources
blackhole_sources = 521c87a83afb8f29e4455e77930b973b, 68a4aa91ac350c4087564e8a69f84e86
# Optional update interval, defaults to one hour
blackhole_update_interval = 60
...
**How It Works**
docs/manual/git.html
+19 -8
View File
@@ -946,20 +946,30 @@ argument to <code class="docutils literal notranslate"><span class="pre">rngit</
</pre></div>
</div>
<p>If your pattern contains no wildcard characters, it must match an artifact name exactly, which is useful for fetching single, specific artifacts. When a pattern matches multiple artifacts, all matched files are fetched and verified. If no artifacts match the pattern, the fetch aborts with an error indicating no matches were found.</p>
<p><strong>Offline Verification</strong></p>
</section>
<section id="offline-verification">
<h3>Offline Verification<a class="headerlink" href="#offline-verification" title="Link to this heading"></a></h3>
<p>Because the release manifest contains embedded signatures, you can verify the integrity of release artifacts offline, without connecting to the repository node. The <code class="docutils literal notranslate"><span class="pre">rnid</span></code> and <code class="docutils literal notranslate"><span class="pre">rngit</span></code> utilities can validate artifact signatures against <code class="docutils literal notranslate"><span class="pre">.rsg</span></code> and manifest files.</p>
<p><strong>Using a release manifest:</strong></p>
<p>Ensure the release manifest is located in the same directory as the release artifacts, then run:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span># Verify all artifacts in the manifest
$ rngit release myapp-1.2.0.rsm verify
# Or, verify only specific artifacts
$ rngit release myapp-1.2.0.rsm verify &quot;latest:*.whl&quot;
</pre></div>
</div>
<p>This will load the manifest, and verify all files currently on-disk, but will not attempt to fetch the latest release manifest from the origin, or update local files to match it.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The <code class="docutils literal notranslate"><span class="pre">verify</span></code> operation is functionally equivalent to using the <code class="docutils literal notranslate"><span class="pre">fetch</span></code> operation with the <code class="docutils literal notranslate"><span class="pre">--offline</span></code> flag, and they can be used interchangably.</p>
</div>
<p><strong>For individual files:</strong></p>
<p>Ensure the <code class="docutils literal notranslate"><span class="pre">.rsg</span></code> signature is located in the same directory as the release artifact, then run:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnid -V myapp-1.2.0.tar.gz
</pre></div>
</div>
<p>This validates that the artifact file matches the signature created during the release process. Combined with the manifest’s own signature, this provides end-to-end verification from the original release creation to the final installation.</p>
<p><strong>For a complete release:</strong></p>
<p>Ensure the release manifest is located in the same directory as the release artifacts, then run:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rngit release myapp-1.2.0.rsm fetch --offline
</pre></div>
</div>
<p>This will load the manifest, and verify all files currently on-disk, but will not attempt to fetch the latest release manifest from the origin, or update local files to match it.</p>
</section>
<section id="creating-signed-releases">
<span id="git-release-create"></span><h3>Creating Signed Releases<a class="headerlink" href="#creating-signed-releases" title="Link to this heading"></a></h3>
@@ -967,7 +977,7 @@ argument to <code class="docutils literal notranslate"><span class="pre">rngit</
<ol class="arabic simple">
<li><p>Generates an Ed25519 signature for each artifact file using your identity’s signing key</p></li>
<li><p>Creates <code class="docutils literal notranslate"><span class="pre">.rsg</span></code> signature files alongside each artifact in your distribution directory</p></li>
<li><p>Constructs a signed release manifest (<code class="docutils literal notranslate"><span class="pre">manifest.rsm</span></code>) containing metadata, an artifact list, and embedded signatures</p></li>
<li><p>Constructs a signed <code class="docutils literal notranslate"><span class="pre">manifest.rsm</span></code> release manifest containing metadata, an artifact list, and embedded signatures</p></li>
<li><p>Transmits both artifacts, signatures and manifest to the remote node specified as release origin</p></li>
</ol>
<p>As an example, to create and publish a release from all files in the folder named <code class="docutils literal notranslate"><span class="pre">dist</span></code>, simply run:</p>
@@ -1529,6 +1539,7 @@ Date: Mon Jan 15 09:30:00 2026 +0100
</li>
<li><a class="reference internal" href="#verified-releases">Verified Releases</a><ul>
<li><a class="reference internal" href="#obtaining-verified-releases">Obtaining Verified Releases</a></li>
<li><a class="reference internal" href="#offline-verification">Offline Verification</a></li>
<li><a class="reference internal" href="#creating-signed-releases">Creating Signed Releases</a></li>
</ul>
</li>
docs/manual/index.html
+1
View File
@@ -581,6 +581,7 @@ to participate in the development of Reticulum itself.</p>
</li>
<li class="toctree-l2"><a class="reference internal" href="git.html#verified-releases">Verified Releases</a><ul>
<li class="toctree-l3"><a class="reference internal" href="git.html#obtaining-verified-releases">Obtaining Verified Releases</a></li>
<li class="toctree-l3"><a class="reference internal" href="git.html#offline-verification">Offline Verification</a></li>
<li class="toctree-l3"><a class="reference internal" href="git.html#creating-signed-releases">Creating Signed Releases</a></li>
</ul>
</li>
docs/manual/searchindex.js
+1 -1
View File
File diff suppressed because one or more lines are too long
docs/manual/using.html
+4 -1
View File
@@ -1374,7 +1374,7 @@ remote_management_allowed = 9fb6d773498fb3feda407ed8ef2c3229, 2d882c5586e548d79b
</section>
<section id="automated-list-sourcing">
<h3>Automated List Sourcing<a class="headerlink" href="#automated-list-sourcing" title="Link to this heading"></a></h3>
<p>Manually blocking identities is effective for immediate threats, but maintaining an up-to-date blocklist for a large network is impractical. Reticulum supports <strong>automated list sourcing</strong>, allowing your node to subscribe to blackhole lists maintained by trusted peers, or a central authority you manage yourself.</p>
<p>Manually blocking identities is effective for immediate threats and annoyances, but maintaining an up-to-date blocklist across many nodes on a large network is impractical. Reticulum supports <strong>automated list sourcing</strong>, allowing your node to subscribe to blackhole lists maintained by trusted peers, or a central authority you manage yourself.</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p><strong>Verify Before Subscribing!</strong> Subscribing to a blackhole source is a powerful action that grants that source the ability to dictate who you can communicate with. Before adding a source to your configuration, verify that the maintainer aligns with your usage policy and values. Blindly subscribing to untrusted lists could inadvertently block legitimate peers or essential services.</p>
@@ -1386,6 +1386,9 @@ remote_management_allowed = 9fb6d773498fb3feda407ed8ef2c3229, 2d882c5586e548d79b
<span class="na">...</span>
<span class="c1"># Automatically fetch blackhole lists from these trusted sources</span>
<span class="na">blackhole_sources</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">521c87a83afb8f29e4455e77930b973b, 68a4aa91ac350c4087564e8a69f84e86</span>
<span class="c1"># Optional update interval, defaults to one hour</span>
<span class="na">blackhole_update_interval</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">60</span>
<span class="na">...</span>
</pre></div>
</div>
docs/markdown/git.md
+19 -12
View File
@@ -797,10 +797,27 @@ $ rngit release rns://remote_node/public/myrepo fetch "1.2.0:source_*.tgz"
If your pattern contains no wildcard characters, it must match an artifact name exactly, which is useful for fetching single, specific artifacts. When a pattern matches multiple artifacts, all matched files are fetched and verified. If no artifacts match the pattern, the fetch aborts with an error indicating no matches were found.
**Offline Verification**
### Offline Verification
Because the release manifest contains embedded signatures, you can verify the integrity of release artifacts offline, without connecting to the repository node. The `rnid` and `rngit` utilities can validate artifact signatures against `.rsg` and manifest files.
**Using a release manifest:**
Ensure the release manifest is located in the same directory as the release artifacts, then run:
```text
# Verify all artifacts in the manifest
$ rngit release myapp-1.2.0.rsm verify
# Or, verify only specific artifacts
$ rngit release myapp-1.2.0.rsm verify "latest:*.whl"
```
This will load the manifest, and verify all files currently on-disk, but will not attempt to fetch the latest release manifest from the origin, or update local files to match it.
#### NOTE
The `verify` operation is functionally equivalent to using the `fetch` operation with the `--offline` flag, and they can be used interchangably.
**For individual files:**
Ensure the `.rsg` signature is located in the same directory as the release artifact, then run:
@@ -811,23 +828,13 @@ $ rnid -V myapp-1.2.0.tar.gz
This validates that the artifact file matches the signature created during the release process. Combined with the manifest’s own signature, this provides end-to-end verification from the original release creation to the final installation.
**For a complete release:**
Ensure the release manifest is located in the same directory as the release artifacts, then run:
```text
$ rngit release myapp-1.2.0.rsm fetch --offline
```
This will load the manifest, and verify all files currently on-disk, but will not attempt to fetch the latest release manifest from the origin, or update local files to match it.
### Creating Signed Releases
Reticulum and the `rngit` system makes it easy to create signed releases that your users can verify and update securely. When you create a release using `rngit`, the program automatically:
1. Generates an Ed25519 signature for each artifact file using your identity’s signing key
2. Creates `.rsg` signature files alongside each artifact in your distribution directory
3. Constructs a signed release manifest (`manifest.rsm`) containing metadata, an artifact list, and embedded signatures
3. Constructs a signed `manifest.rsm` release manifest containing metadata, an artifact list, and embedded signatures
4. Transmits both artifacts, signatures and manifest to the remote node specified as release origin
As an example, to create and publish a release from all files in the folder named `dist`, simply run:
docs/markdown/index.md
+1
View File
@@ -234,6 +234,7 @@ to participate in the development of Reticulum itself.
* [Configuration Example](git.md#configuration-example)
* [Verified Releases](git.md#verified-releases)
* [Obtaining Verified Releases](git.md#obtaining-verified-releases)
* [Offline Verification](git.md#offline-verification)
* [Creating Signed Releases](git.md#creating-signed-releases)
* [Release Management](git.md#release-management)
* [The Release Workflow](git.md#the-release-workflow)
docs/markdown/using.md
+4 -1
View File
@@ -1262,7 +1262,7 @@ $ rnpath -b
### Automated List Sourcing
Manually blocking identities is effective for immediate threats, but maintaining an up-to-date blocklist for a large network is impractical. Reticulum supports **automated list sourcing**, allowing your node to subscribe to blackhole lists maintained by trusted peers, or a central authority you manage yourself.
Manually blocking identities is effective for immediate threats and annoyances, but maintaining an up-to-date blocklist across many nodes on a large network is impractical. Reticulum supports **automated list sourcing**, allowing your node to subscribe to blackhole lists maintained by trusted peers, or a central authority you manage yourself.
#### WARNING
**Verify Before Subscribing!** Subscribing to a blackhole source is a powerful action that grants that source the ability to dictate who you can communicate with. Before adding a source to your configuration, verify that the maintainer aligns with your usage policy and values. Blindly subscribing to untrusted lists could inadvertently block legitimate peers or essential services.
@@ -1278,6 +1278,9 @@ To enable automated sourcing, add the `blackhole_sources` option to the `[reticu
...
# Automatically fetch blackhole lists from these trusted sources
blackhole_sources = 521c87a83afb8f29e4455e77930b973b, 68a4aa91ac350c4087564e8a69f84e86
# Optional update interval, defaults to one hour
blackhole_update_interval = 60
...
```
docs/source/git.rst
+20 -12
View File
@@ -853,10 +853,28 @@ Or to retrieve all source archives:
If your pattern contains no wildcard characters, it must match an artifact name exactly, which is useful for fetching single, specific artifacts. When a pattern matches multiple artifacts, all matched files are fetched and verified. If no artifacts match the pattern, the fetch aborts with an error indicating no matches were found.
**Offline Verification**
Offline Verification
--------------------
Because the release manifest contains embedded signatures, you can verify the integrity of release artifacts offline, without connecting to the repository node. The ``rnid`` and ``rngit`` utilities can validate artifact signatures against ``.rsg`` and manifest files.
**Using a release manifest:**
Ensure the release manifest is located in the same directory as the release artifacts, then run:
.. code:: text
# Verify all artifacts in the manifest
$ rngit release myapp-1.2.0.rsm verify
# Or, verify only specific artifacts
$ rngit release myapp-1.2.0.rsm verify "latest:*.whl"
This will load the manifest, and verify all files currently on-disk, but will not attempt to fetch the latest release manifest from the origin, or update local files to match it.
.. note::
The ``verify`` operation is functionally equivalent to using the ``fetch`` operation with the ``--offline`` flag, and they can be used interchangably.
**For individual files:**
Ensure the ``.rsg`` signature is located in the same directory as the release artifact, then run:
@@ -867,16 +885,6 @@ Ensure the ``.rsg`` signature is located in the same directory as the release ar
This validates that the artifact file matches the signature created during the release process. Combined with the manifest's own signature, this provides end-to-end verification from the original release creation to the final installation.
**For a complete release:**
Ensure the release manifest is located in the same directory as the release artifacts, then run:
.. code:: text
$ rngit release myapp-1.2.0.rsm fetch --offline
This will load the manifest, and verify all files currently on-disk, but will not attempt to fetch the latest release manifest from the origin, or update local files to match it.
.. _git-release-create:
Creating Signed Releases
@@ -886,7 +894,7 @@ Reticulum and the ``rngit`` system makes it easy to create signed releases that
1. Generates an Ed25519 signature for each artifact file using your identity's signing key
2. Creates ``.rsg`` signature files alongside each artifact in your distribution directory
3. Constructs a signed release manifest (``manifest.rsm``) containing metadata, an artifact list, and embedded signatures
3. Constructs a signed ``manifest.rsm`` release manifest containing metadata, an artifact list, and embedded signatures
4. Transmits both artifacts, signatures and manifest to the remote node specified as release origin
As an example, to create and publish a release from all files in the folder named ``dist``, simply run: