Prepare release

Added custom identity support to rncp utility

.github/workflows/build.yml

@@ -93,6 +93,6 @@ jobs:
 #            .artifacts/documentation/latex/reticulumnetworkstack.pdf
 #            .artifacts/documentation/epub/ReticulumNetworkStack.epub
           draft: true
-          generate_release_notes: true
+          generate_release_notes: false
           prerelease: ${{ contains(github.ref, '-') }}
           fail_on_unmatched_files: true

.gitignore

@@ -13,3 +13,4 @@ tests/rnsconfig/storage
 tests/rnsconfig/logfile*
 *.data
 *.result
+.buildinfo.bak

Changelog.md

@@ -1,3 +1,297 @@
+### 2026-05-05: RNS 1.2.3
+
+This release adds Work Document and update/commenting support to `rngit`. 
+
+**Changes**
+- Added Work Document management to `rngit`.
+- Added Work pages to the page node of `rngit`.
+- Added `interact` permission type to `rngit`.
+- Added `admin` permission type to `rngit`.
+- Added markdown blockquote support to the `rngit` markdown-to-micron converter.
+- Improved markdown-to-micron conversion and syntax highlighting accuracy in `rngit`.
+
+**Release Hashes**
+```
+8562130f297a6b33be9d72c449bbe6ae83cad41e1530e0fa112f5fa545a3f364 rns-1.2.3-py3-none-any.whl
+0862f46a08e610add1bcac0916c6554f3e79590ab2765900178d5e1f1f0c7026 rnspure-1.2.3-py3-none-any.whl
+```
+
+**Release Signatures**
+Release artifacts include `rsg` signature files that can be validated against the RNS release signing identity `<bc7291552be7a58f361522990465165c>` using `rnid`:
+
+```sh
+rnid -i bc7291552be7a58f361522990465165c -V rns-1.2.2-py3-none-any.whl.rsg
+```
+
+### 2026-05-05: RNS 1.2.2
+
+This release adds release management workflows to the `rngit` utility. Downloading files and release artifacts from `rngit` will require the latest version of Nomad Network. Other nomadnet clients *may* have to update their file download link handling, if they don't already support passing query parameters for file download links.
+
+**Changes**
+- Added release management to `rngit`.
+- Added release pages to the page node of `rngit`.
+- Added file downloads in the tree browser of `rngit`.
+
+**Release Hashes**
+```
+4bf0a376a9778de8a91b9ec8a5bc4b929be928eede8784b20022c7fe52bbce62 rns-1.2.2-py3-none-any.whl
+d85f8b765dcf718d284388b249ca0e48e785f250bb41773a83e159e46c5bcf70 rnspure-1.2.2-py3-none-any.whl
+```
+
+**Release Signatures**
+Release artifacts include `rsg` signature files that can be validated against the RNS release signing identity `<bc7291552be7a58f361522990465165c>` using `rnid`:
+
+```sh
+rnid -i bc7291552be7a58f361522990465165c -V rns-1.2.2-py3-none-any.whl.rsg
+```
+
+### 2026-05-04: RNS 1.2.1
+
+This release adds a nomadnet Git page node to the `rngit` utility.
+
+**Changes**
+- Added nomadnet page node to `rngit`.
+
+**Release Hashes**
+```
+5ccbfc31b528133c4dd06c132034c2151e4eed74bc2dcf40af52385094492c9e rns-1.2.1-py3-none-any.whl
+cda45994a58f18bf25244a1f396c9197240bc012dd85c86bffc2e73dcf0607de rnspure-1.2.1-py3-none-any.whl
+```
+
+**Release Signatures**
+Release artifacts include `rsg` signature files that can be validated against the RNS release signing identity `<bc7291552be7a58f361522990465165c>` using `rnid`:
+
+```sh
+rnid -i bc7291552be7a58f361522990465165c -V rns-1.2.1-py3-none-any.whl.rsg
+```
+
+### 2026-04-28: RNS 1.2.0
+
+This release brings the ability to use Git natively over Reticulum networks, adds the `rnsh` program as part of the included utilities, and additionally includes several improvements and performance optimizations.
+
+**Changes**
+- Added Reticulum Git Repositories Node utility as part of included utility programs.
+- Added git remote helper to interact with git repositories over Reticulum.
+- Added the `rnsh` program to the included utilities.
+- Added LocalInterface client TX hold on client app sleep on Android.
+- Added AutoInterface filters for `rmnet` interfaces on Android.
+- Added inbound packet wait during transport core initialization.
+- Added the ability to set logfile destination before RNS initialization.
+- Added automatic active link teardown on instance shutdown.
+- Improved link teardown on SIGINT/SIGTERM.
+- Improved ratchet cleaning.
+
+**Release Hashes**
+```
+b58e97332241755ed32e309d46e09615a123490430ae85fcbdec9318c9e26154 rns-1.2.0-py3-none-any.whl
+9813a6c2236edba18af7d3a072a6226bc65ae384d23b1f41467cb3617d65fdae rnspure-1.2.0-py3-none-any.whl
+```
+
+**Release Signatures**
+Release artifacts include `rsg` signature files that can be validated against the RNS release signing identity `<bc7291552be7a58f361522990465165c>` using `rnid`:
+
+```sh
+rnid -i bc7291552be7a58f361522990465165c -V rns-1.2.0-py3-none-any.whl.rsg
+```
+
+### 2026-04-22: RNS 1.1.9
+
+This maintenance release fixes a critical security issue, that would allow an attacker to craft a BZ2 decompression bomb via Resource transfers or Buffer StreamDataMessage, causing an out-of-memory condition and crashing the receiving process via OOM killer.
+
+Big thanks to @defidude (github.com/ratspeak) for discovering and reporting this vulnerability!
+
+**Changes**
+- Fixed bz2 decompression bomb vulnerability in Resource transfer assembly and Buffer StreamDataMessage unpacking.
+
+**Release Hashes**
+```
+39a131aeb5d76fd73bfc67f68135f49ab0cf8628af154e04096a05c208ce77b6 rns-1.1.9-py3-none-any.whl
+aab7bfc8c65514c9bdf4c22f00d288faf6c9e1777fc002dbe3eb29c286e67128 rnspure-1.1.9-py3-none-any.whl
+```
+
+**Release Signatures**
+Release artifacts include `rsg` signature files that can be validated against the RNS release signing identity `<bc7291552be7a58f361522990465165c>` using `rnid`:
+
+```sh
+rnid -i bc7291552be7a58f361522990465165c -V rns-1.1.9-py3-none-any.whl.rsg
+```
+
+### 2026-04-21: RNS 1.1.8
+
+This maintenance release fixes a critical bug in path state management, that could result in significant path convergence degradation under certain conditions.
+
+**Changes**
+- Fixed path state potentially being applied before path table entry exists, causing worse paths to be selected.
+
+**Release Hashes**
+```
+9cf728e9e9a9fe113e4ac14e6b833f7ee65feedf8468e6ab94a261bf205f2632 rns-1.1.8-py3-none-any.whl
+407dc3975335e9eabaaddb7ed1dc75fc3a1b8d24a7207e740797440c2ad0b3e5 rnspure-1.1.8-py3-none-any.wh
+```
+
+**Release Signatures**
+Release artifacts include `rsg` signature files that can be validated against the RNS release signing identity `<bc7291552be7a58f361522990465165c>` using `rnid`:
+
+```sh
+rnid -i bc7291552be7a58f361522990465165c -V rns-1.1.8-py3-none-any.whl.rsg
+```
+
+### 2026-04-21: RNS 1.1.7
+
+**Changes**
+- Added periodic known destination data cleaning based on local relevance.
+- Improved resource transfer sequencing timing calculations and reliability.
+- Improved BackboneInterface error handling on EPOLL errors.
+- Ensured non-background data persist runs synchronously.
+
+**Release Hashes**
+```
+4d9702c5d9bb8a3c8b94766cb51cccad5afd78d615af9a6b146730347044e6f0 rns-1.1.7-py3-none-any.whl
+172dede7656b41b85e4319354ed04649b518e58c54586da7e443579c620a0a5b rnspure-1.1.7-py3-none-any.whl
+```
+
+**Release Signatures**
+Release artifacts include `rsg` signature files that can be validated against the RNS release signing identity `<bc7291552be7a58f361522990465165c>` using `rnid`:
+
+```sh
+rnid -i bc7291552be7a58f361522990465165c -V rns-1.1.7-py3-none-any.whl.rsg
+```
+
+### 2026-04-18: RNS 1.1.6
+
+**Changes**
+- Improved transport memory consumption.
+- Improved transport tunnel handling.
+- Improved gracious transport data persist handling.
+- Added ingress control bypass for pending path requests.
+- Added local destinations lookup map for better transport efficiency to local destinations.
+- Fixed disk I/O bound thread execution time starvation on cache management jobs.
+- Fixed invalid EPOLL modification error handler.
+- Fixed incorrect default IFAC size for autoconnected, discovered interfaces. Thanks @taprootmx!
+- Ensure loop-originating closures have variables captured at iteration-time. Thanks @taprootmx!
+
+**Release Hashes**
+```
+2ce4451668f8c464295cc269188c232e7805ddd618ec0135550a5e6809df5de0 rns-1.1.6-py3-none-any.whl
+ba3e541e69a2f4892177383c8ec4e7d172d298546317e08270928c0163865aa3 rnspure-1.1.6-py3-none-any.wh
+```
+
+**Release Signatures**
+Release artifacts include `rsg` signature files that can be validated against the RNS release signing identity `<bc7291552be7a58f361522990465165c>` using `rnid`:
+
+```sh
+rnid -i bc7291552be7a58f361522990465165c -V rns-1.1.6-py3-none-any.whl.rsg
+```
+
+### 2026-04-13: RNS 1.1.5
+
+**Changes**
+- Initial refactoring work for free-threaded transport I/O.
+- Improved interface discovery validation.
+- Fixed invalid ingress control burst activation and subsequent path resolution failure due to incorrect announce frequency calculation.
+- Fixed missing configuration entry generation for discovered I2P interfaces.
+- Fixed resource transfer cancellation failing on in-flight split resource transfers.
+- Fixed ingress control configuration not inheriting down to spawned interfaces on some interface types.
+
+**Release Hashes**
+```
+28f39ad97ef307a1e270b91ef19db07d8e1a7bbc8628c478303725894c64deff rns-1.1.5-py3-none-any.whl
+1a90db16d2cff4ad909b44baf9b4fd0177da2ed545cdb9cfb2c51423707b49e9 rnspure-1.1.5-py3-none-any.whl
+```
+
+**Release Signatures**
+Release artifacts include `rsg` signature files that can be validated against the RNS release signing identity `<bc7291552be7a58f361522990465165c>` using `rnid`:
+
+```sh
+rnid -i bc7291552be7a58f361522990465165c -V rns-1.1.5-py3-none-any.whl.rsg
+```
+
+#
+
+### 2026-03-12: RNS 1.1.4
+
+**Changes**
+- Fixed invalid application of IP/hostname validation for on non-relevant interfaces. Thanks @joakim!
+
+**Release Hashes**
+```
+b2a175abd64d1581dd058206832793dbf7053a304c819ff8bc143a79c49cb747 rns-1.1.4-py3-none-any.whl
+16c4ae6722bbd016e8db046e7bdd60eb24f9ec55966ec5723dc39301265d0186 rnspure-1.1.4-py3-none-any.whl
+```
+
+**Release Signatures**
+Release artifacts include `rsg` signature files that can be validated against the RNS release signing identity `<bc7291552be7a58f361522990465165c>` using `rnid`:
+
+```sh
+rnid -i bc7291552be7a58f361522990465165c -V rns-1.1.4-py3-none-any.whl.rsg
+```
+
+### 2026-01-17: RNS 1.1.3
+
+**Changes**
+- Improved discovered interface auto-connect handling
+- Improved interface discovery handling
+- Added `discovered_interfaces` API method
+- Fixed a potential race condition in request timeout handling
+- Fixed a regression in resource file transfers
+
+**Release Hashes**
+```
+1de9b46c8f24931fa41974664ddbf4251d3fdd069be4de03c64b42a7cf4f8fb4 rns-1.1.3-py3-none-any.whl
+eac8d223fcb6ce94e1bd3f04730d8542675caf4b22286e11988e9402ea9b69c0 rnspure-1.1.3-py3-none-any.whl
+```
+
+**Release Signatures**
+Release artifacts include `rsg` signature files that can be validated against the RNS release signing identity `<bc7291552be7a58f361522990465165c>` using `rnid`:
+
+```sh
+rnid -i bc7291552be7a58f361522990465165c -V rns-1.1.3-py3-none-any.whl.rsg
+```
+
+### 2026-01-04: RNS 1.1.0
+
+Enjoy.
+
+**Changes**
+- Added on-network global interface discovery. Hello world.
+- Added discovered interface auto-connection. Robotic.
+- Added external IP resolution for discovery-enabled interfaces. Snip-snip.
+- Added encrypted interface discovery announces. Welcome home.
+- Added bootstrap interface functionality. Decent.
+- Added blackhole handling and management. Thank the Chinese guy.
+- Added distributed blackhole list publishing and updating. Spammers go home.
+- Added foundational network identity implementation. All your base.
+- Added `await_path` method to API. Tick-tock.
+- Added reverse-unicast peer discovery packet mechanism to AutoInterface. Ping-pong.
+- Added custom identity support to `rncp`, thanks MikelCalvo!
+- Added monitor mode to `rnstatus`, thanks MikelCalvo!
+- Improved announce processing. Swoosh.
+- Updated documentation quite a bit. Looky.
+- Enabled per-peer ingress limiting on Weave and Auto interfaces. Hammertime.
+- Fixed **the** typo, yes it's the olny one I'm sure.
+- Fixed bugs. Squish.
+
+**Release Hashes**
+```
+180b8baec2ec7d21abe2cec25ff763e70b2129c012fb02fc23c2fd654f94c1f5 dist/rns-1.1.0-py3-none-any.whl
+d9e32caf66a9c53199e901d2c173e1de1bf50f1f0c9d5250e5d1b3b07bedcd7c dist/rnspure-1.1.0-py3-none-any.whl
+```
+
+### 2025-11-19: RNS 1.0.4
+
+This maintenance release adds improved handling for RNodes with a PA/LNA combo.
+
+**Changes**
+- Improved handling for RNodes with PA/LNA combo
+- Added interference detection stats to `rnstatus` output for RNode interfaces
+- Updated documentation
+
+**Release Hashes**
+```
+7a2b7893410833b42c0fa7f9a9e3369cebb085cdd26bd83f3031fa6c1051653c rns-1.0.4-py3-none-any.whl
+ee647e7b3b94abdf1fab618a861390531a4aacc93eecce12c9e97280195c0e2d rnspure-1.0.4-py3-none-any.whl
+```
+
 ### 2025-11-19: RNS 1.0.3
 
 This release includes updates to RNode BLE reliability, and adds support for connecting RNodes to a host over WiFi and Ethernet.
@@ -11,8 +305,8 @@ This release includes updates to RNode BLE reliability, and adds support for con
 
 **Release Hashes**
 ```
-6bafde4c838ad778bf6878967e84c798e34d6ca621b255f59a60f38cb04ac138  dist/rns-1.0.3-py3-none-any.whl
-f277899f95c1189c6bf3beb40ac656c8b36dfd3d7e4cfb2bc3b4a1e6dc3484fa  dist/rnspure-1.0.3-py3-none-any.whl
+6bafde4c838ad778bf6878967e84c798e34d6ca621b255f59a60f38cb04ac138 rns-1.0.3-py3-none-any.whl
+f277899f95c1189c6bf3beb40ac656c8b36dfd3d7e4cfb2bc3b4a1e6dc3484fa rnspure-1.0.3-py3-none-any.whl
 ```
 
 ### 2025-11-10: RNS 1.0.2

Contributing.md

@@ -8,21 +8,28 @@ Apart from writing code, there are many ways in which you can contribute. Before
 
 First and foremost, there is one simple requirement for taking part in this community: While we primarily interact virtually, your actions matter and have real consequences. Therefore: **Act like a responsible, civilized person** - especially in the face of disputes and heated disagreements. Speak your mind here; discussions are welcome. Just do so in the spirit of being face-to-face with everyone else. Thank you.
 
+In order to keep the discussion forums and issue trackers navigable and useful, the following types of posts will be deleted without notice:
+
+- Spam.
+- Questions that have already been adequately answered elsewhere. Use the search function.
+- Low-effort posts or comments that contain no actual information or useful content. This is not a tea-house.
+- Post or comments solely containing personal opinions or beliefs without adding anything to the discussion. Facebook and X exists.
+- Content that simply waste the developer's / maintainer's time with completely obvious "ideas", "insights" or "recommendations". Yes, we have *at least* 8 neurons ourselves.
+- Posts that fail to understand that developing a highly complex software project with a very small amount of resources and people takes time. Imagining perfection on our behalf is useless.
+
+If you're new to the community and start out your engagement with any of the above transgressions, you will simply be banned without notice or explanation, and your post will be deleted.
+
+If you find this "harsh", "unfair" or "unwelcoming", go somewhere else. This is not social club, but a work environment for the people contributing to the project.
+
 ## Asking Questions
 
-If you want to ask a question, **do not open an issue**. The issue tracker is used by people *working on Reticulum* to track bugs, issues and improvements.
+If you want to ask a question, **do not open an issue**. The issue tracker is used by people *working on Reticulum* to track bugs, issues and improvements. Instead, ask away on the [discussions](https://github.com/markqvist/Reticulum/discussions).
 
-Instead, ask away on the [discussions](https://github.com/markqvist/Reticulum/discussions) or on the [Reticulum Matrix channel](https://matrix.to/#/#reticulum:matrix.org) at `#reticulum:matrix.org`
-
-## Providing Feedback & Ideas
-
-Likewise, feedback, ideas and feature requests are a very welcome way to contribute, and should also be posted on the [discussions](https://github.com/markqvist/Reticulum/discussions), or on the [Reticulum Matrix channel](https://matrix.to/#/#reticulum:matrix.org) at `#reticulum:matrix.org`.
-
-Please do not post feature requests or general ideas on the issue tracker, or in direct messages to the primary developers. You are much more likely to get a response and start a constructive discussion by posting your ideas in the public channels created for these purposes.
+Do not post feature requests or general ideas on the issue tracker, or in direct messages to the primary developers. You are much more likely to get a response and start a constructive discussion by posting your ideas in the public channels created for these purposes.
 
 ## Reporting Issues
 
-If you have found a bug or issue in this project, please report it using the [issue tracker](https://github.com/markqvist/Reticulum/issues). If at all possible, be sure to include details on how to reproduce the bug.
+If you have found a bug or issue in this project, please report it using the [issue tracker](https://github.com/markqvist/Reticulum/issues). Be sure to include details on how to reproduce the bug.
 
 Anything submitted to the issue tracker that does not follow these guidelines will be closed and removed without comments or explanation.
 
@@ -42,9 +49,9 @@ Even new ideas and proposals that have not been approved by a maintainer, or fal
 
 ## Generative AI Policy
 
-Contributions written using large language models (LLMs) or other generative 'AI' programs are prohibited. LLMs produce errors so frequently and in a way that is so unlike human error that issues will regularly remain undetected and slip through, even with stringent review. This is not a worthwhile tradeoff for Reticulum, especially considering the limited time maintainers have to correct these issues, and we ask that you refrain from using any such output in your contributions.
+Contributions written using large language models (LLMs) or other generative 'AI' programs are prohibited. LLMs produce errors so frequently and in a way that is so unlike human error that such issues are incredibly time-consuming to spot and fix. This is not a worthwhile tradeoff for Reticulum.
 
-This applies to all official Reticlulm projects and documentation as well as all submitted issues and discussion in official channels, except in cases where language translation and/or speech recogntion technologies are required for communication.  We also ask that you avoid using LLMs for troubleshooting, as results can be misleading, and instead request help in one of our [various communities](https://reticulum.network/start.html).
+This applies to all Reticulum-related projects and documentation, as well as all submitted issues and discussion in official channels, except in cases where language translation and/or speech recogntion technologies are required for communication.
 
 ## Contributor License Agreement
 

Examples/Resource.py

@@ -222,7 +222,7 @@ def link_established(link):
 
     # Inform the user that the server is
     # connected
-    RNS.log("Link established with server, hit enter to sand a resource, or type in \"quit\" to quit")
+    RNS.log("Link established with server, hit enter to send a resource, or type in \"quit\" to quit")
 
 # When a link is closed, we'll inform the
 # user, and exit the program

FUNDING.json

@@ -0,0 +1,7 @@
+{
+  "drips": {
+    "ethereum": {
+      "ownedBy": "0xae89F3B94fC4AD6563F0864a55F9a697a90261ff"
+    }
+  }
+}

LICENSE

@@ -1,6 +1,6 @@
 Reticulum License
 
-Copyright (c) 2016-2025 Mark Qvist
+Copyright (c) 2016-2026 Mark Qvist
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

MIRROR.md

@@ -0,0 +1,33 @@
+This repository is a public mirror. All potential future development is happening elsewhere.
+
+I am stepping back from all public-facing interaction with this project. Reticulum has always been primarily my work, and continuing in the current public, internet-facing model is no longer sustainable.
+
+The software remains available for use as-is. Occasional updates may appear at unpredictable intervals, but there will be no support, no responses to issues, no discussions, and no community management in this or any other public venue. If it doesn't work for you, it doesn't work. That is the entire extent of available troubleshooting assistance I can offer you.
+
+If you've followed this project for a while, you already know what this means. You know who designed, wrote and tested this, and you know how many years of my life it took. You'll also know about both my particular challenges and strengths, and how I believe anything worth building needs to be built and  maintained with our own hands.
+
+Seven months ago, I said I needed to step back, that I was exhausted, and that I needed to recover. I believed a public resolve would be enough to effectuate that, but while striving to get just a few more useful features and protocols out, the unproductive requests and demands also ramped up, and I got pulled back into the same patterns and draining interactions that I'd explicitly said I couldn't sustain anymore.
+
+So here's what you might have already guessed: I'm done playing the game by rules I can't win at.
+
+Everything you need is right here, and by any sensible measure, it's done. Anyone who wants to invest the time, skill and persistence can build on it, or completely re-imagine it with different priorities. That was always the point.
+
+The people who actually contributed - you know who you are, and you know I mean it when I say: Thank you. All of you who've used this to build something real - that was the goal, and you did it without needing me to hold your hand.
+
+The rest of you: You have what you need. Use it or don't. I am not going to be the person who explains it to you anymore.
+
+This is not a temporary break. It's not "see you after some rest", but a recognition that the current model is fundamentally incompatible with my life, my health, and my reality.
+
+If you want to support continued work, you can do so at the donation links listed in this repository. But please understand, that this is not purchasing support or guaranteeing updates. It is support for work that happens on my timeline, according to my capacity, which at the moment is not what it was.
+
+If you want Reticulum to continue evolving, you have the power to make that happen. The protocol is public domain. The code is open source. Everything you need is right here. I've provided the tools, but building what comes next is not my responsibility anymore. It's yours.
+
+To the small group of people who has actually been here, and understood what this work was and what it cost - you already know where to find me if it actually matters.
+
+To everyone else: This is where we part ways. No hard feelings. It's just time.
+
+---
+
+असतो मा सद्गमय
+तमसो मा ज्योतिर्गमय
+मृत्योर्मा अमृतं गमय

Makefile

@@ -55,13 +55,24 @@ documentation:
 manual:
 	make -C docs latexpdf epub
 
+build_spkg: remove_symlinks build_sdist create_symlinks
+
 release: test remove_symlinks build_sdist build_wheel build_pure_wheel documentation manual create_symlinks
 
 debug: remove_symlinks build_wheel build_pure_wheel create_symlinks
 
-upload:
-	@echo Ready to publish release, hit enter to continue
+upload: upload-rns upload-rnspure
+
+upload-rns:
+	@echo Ready to publish rns release, hit enter to continue
 	@read VOID
 	@echo Uploading to PyPi...
-	twine upload dist/*
+	twine upload dist/rns-*.whl dist/rns-*.tar.gz
 	@echo Release published
+
+upload-rnspure:
+	@echo Ready to publish rnspure release, hit enter to continue
+	@read VOID
+	@echo Uploading to PyPi...
+	twine upload dist/rnspure-*.whl
+	@echo Release published

README.md

@@ -3,6 +3,10 @@ Reticulum Network Stack <img align="right" src="https://static.pepy.tech/persona
 
 <p align="center"><img width="200" src="https://raw.githubusercontent.com/markqvist/Reticulum/master/docs/source/graphics/rns_logo_512.png"></p>
 
+*This repository is [a public mirror](./MIRROR.md). All development is happening elsewhere.*
+
+To understand the foundational philosophy and goals of this system, read the [Zen of Reticulum](Zen%20of%20Reticulum.md).
+
 Reticulum is the cryptography-based networking stack for building local and wide-area
 networks with readily available hardware. It can operate even with very high latency
 and extremely low bandwidth. Reticulum allows you to build wide-area networks
@@ -74,22 +78,32 @@ For more info, see [reticulum.network](https://reticulum.network/) and [the FAQ
   - Low cost of keeping links open at only 0.44 bits per second
 - Reliable sequential delivery with Channel and Buffer mechanisms
 
-## Roadmap
-While Reticulum is already a fully featured and functional networking stack,
-many improvements and additions are actively being worked on, and planned for the future.
+## Reference Implementation
 
-To learn more about the direction and future of Reticulum, please see the [Development Roadmap](./Roadmap.md).
+The Python code in this repository is the Reference Implementation of Reticulum.
+The Reticulum Protocol is defined entirely and authoritatively by this reference
+implementation, and its associated manual. It is maintained by Mark Qvist,
+identified by the Reticulum Identity `<bc7291552be7a58f361522990465165c>`.
+
+Compatibility with the Reticulum Protocol is defined as having full interoperability,
+and sufficient functional parity with this reference implementation. Any specific protocol
+implementation that achieves this is Reticulum. Any that does not is not Reticulum.
+
+The reference implementation is licensed under the Reticulum License.
+
+The Reticulum Protocol was dedicated to the Public Domain in 2016.
 
 ## Examples of Reticulum Applications
 If you want to quickly get an idea of what Reticulum can do, take a look at the
-following resources.
+[Programs Using Reticulum](https://reticulum.network/manual/software.html)
+section of the manual, or the following resources:
 
-- You can use the [rnsh](https://github.com/acehoss/rnsh) program to establish remote shell sessions over Reticulum.
 - [LXMF](https://github.com/markqvist/lxmf) is a distributed, delay and disruption tolerant message transfer protocol built on Reticulum
 - The [LXST](https://github.com/markqvist/lxst) protocol and framework provides real-time audio and signals transport over Reticulum. It includes primitives and utilities for building voice-based applications and hardware devices, such as the `rnphone` program, that can be used to build hardware telephones.
 - For an off-grid, encrypted and resilient mesh communications platform, see [Nomad Network](https://github.com/markqvist/NomadNet)
 - The Android, Linux, macOS and Windows app [Sideband](https://github.com/markqvist/Sideband) has a graphical interface and many advanced features, such as file transfers, image and voice messages, real-time voice calls, a distributed telemetry system, mapping capabilities and full plugin extensibility.
-- [MeshChat](https://github.com/liamcottle/reticulum-meshchat) is a user-friendly LXMF client with a web-based interface, that also supports image and voice messages, as well as file transfers. It also includes a built-in page browser for browsing Nomad Network nodes.
+- [MeshChatX](https://git.quad4.io/RNS-Things/MeshChatX) is a full-featured LXMF client with many built-in tools and functionalities, that also supports image and voice messages, file transfers and voice calls. It also includes a built-in page browser for browsing Nomad Network nodes.
+- You can use the included [rnsh](https://reticulum.network/manual/using.html#the-rnsh-utility) program to establish remote shell sessions over Reticulum.
 
 ## Where can Reticulum be used?
 Over practically any medium that can support at least a half-duplex channel
@@ -170,8 +184,10 @@ section of the [Reticulum Manual](https://markqvist.github.io/Reticulum/manual/)
 - A diagnostics tool called `rnprobe` for checking connectivity to destinations
 - A simple file transfer program called `rncp` making it easy to transfer files between systems
 - The identity management and encryption utility `rnid` let's you manage Identities and encrypt/decrypt files
-- The remote command execution program `rnx` let's you run commands and
-  programs and retrieve output from remote systems
+- The `rnsh` program allows you to establish fully interactive shell session with remote systems
+- The remote command execution program `rnx` let's you run simple commands and programs and retrieve output from remote systems
+- The `rngit` program provides a full multi-repository Git node for serving repositories over Reticulum
+- The included `git-remote-rns` helper allows you to interact with Git repositories over Reticulum
 
 All tools, including `rnx` and `rncp`, work reliably and well even over very
 low-bandwidth links like LoRa or Packet Radio. For full-featured remote shells
@@ -216,7 +232,7 @@ probably occur as real-world use is explored and understood. The API and wire-fo
 can be considered stable.
 
 ## Dependencies
-The installation of the default `rns` package requires the dependencies listed
+The installation of the default `rns` package requires only two external dependencies, listed
 below. Almost all systems and distributions have readily available packages for
 these dependencies, and when the `rns` package is installed with `pip`, they
 will be downloaded and installed as well.
@@ -244,53 +260,24 @@ that do not support [PyCA/cryptography](https://github.com/pyca/cryptography),
 it is important that you read and understand the [Cryptographic
 Primitives](#cryptographic-primitives) section of this document.
 
+## Bootstrapping Connectivity
+
+Reticulum is not a service you subscribe to, nor is it a single global network you "join".
+Reticulum provides functionality for discovering available public interfaces
+over the network itself, and the broader community has provided various directories
+of publicly available entrypoints to bootstrap connectivity.
+
+To learn how to establish initial connectivity over Reticulum, read the [Bootstrapping Connectivity](https://reticulum.network/manual/gettingstartedfast.html#bootstrapping-connectivity) section of the manual.
+
+If you already have a general idea of how this works, you can use community-run
+sites such as [directory.rns.recipes](https://directory.rns.recipes/) and [rmap.world](https://rmap.world)
+to find interface definitions for initial connectivity to the global distributed Reticulum backbone.
+
 ## Public Testnet
-If you just want to get started experimenting without building any physical
-networks, you are welcome to join the RNS Development Testnet.
-
-The testnet is just that, an informal network for testing and experimenting.
-It will be up most of the time, and anyone can join, but it also means that
-there's no guarantees for service availability.
-
-It probably goes without saying, but *don't use the testnet entry-points as 
-hardcoded or default interfaces in any applications you ship to users*. When
-shipping applications, the best practice is to provide your own default
-connectivity solutions, if needed and applicable, or in most cases, simply
-leave it up to the user which networks to connect to, and how.
-
-The testnet runs the very latest version of Reticulum (often even a short while
-before it is publicly released). Sometimes experimental versions of Reticulum
-might be deployed to nodes on the testnet, which means strange behaviour might
-occur. If none of that scares you, you can join the testnet via either TCP or
-I2P. Just add one of the following interfaces to your Reticulum configuration
-file:
-
-```
-# TCP/IP interface to the RNS Amsterdam Hub
-  [[RNS Testnet Amsterdam]]
-    type = TCPClientInterface
-    enabled = yes
-    target_host = amsterdam.connect.reticulum.network
-    target_port = 4965
-
-# TCP/IP interface to the BetweenTheBorders Hub (community-provided)
-  [[RNS Testnet BetweenTheBorders]]
-    type = TCPClientInterface
-    enabled = yes
-    target_host = reticulum.betweentheborders.com
-    target_port = 4242
-
-# Interface to Testnet I2P Hub
-  [[RNS Testnet I2P Hub]]
-    type = I2PInterface
-    enabled = yes
-    peers = g3br23bvx3lq5uddcsjii74xgmn6y5q325ovrkq2zw2wbzbqgbuq.b32.i2p
-```
-
-The testnet also contains a number of [Nomad Network](https://github.com/markqvist/nomadnet) nodes, and LXMF propagation nodes.
+***Important!** Historically, a developer-targeted testnet was made available by the Reticulum project itself. As the amount of global Reticulum nodes and entrypoints have grown to a substantial quantity, this public testnet, including the Amsterdam Testnet entrypoint, has now been decommissioned. If your still have instances that relied on this entrypoint for connectivity, transition to using the distributed backbone instead. Reticulum now includes a full on-network interface discovery and connectivity bootstrapping system. Read the [Bootstrapping Connectivity](https://reticulum.network/manual/gettingstartedfast.html#bootstrapping-connectivity) section of the manual for pointers.*
 
 ## Support Reticulum
-You can help support the continued development of open, free and private communications systems by donating via one of the following channels:
+For this to be possible, I need your help. Please support the continued development of open, free and private communications systems by donating via one of the following channels:
 
 - Monero:
   ```
@@ -298,11 +285,11 @@ You can help support the continued development of open, free and private communi
   ```
 - Bitcoin
   ```
-  bc1p4a6axuvl7n9hpapfj8sv5reqj8kz6uxa67d5en70vzrttj0fmcusgxsfk5
+  bc1pgqgu8h8xvj4jtafslq396v7ju7hkgymyrzyqft4llfslz5vp99psqfk3a6
   ```
 - Ethereum
   ```
-  0xae89F3B94fC4AD6563F0864a55F9a697a90261ff
+  0x91C421DdfB8a30a49A71d63447ddb54cEBe3465E
   ```
 - Liberapay: https://liberapay.com/Reticulum/
 
@@ -393,4 +380,5 @@ projects:
 - [Configobj](https://github.com/DiffSK/configobj) by Michael Foord, Nicola Larosa, Rob Dennis & Eli Courtwright, *BSD License*
 - [ifaddr](https://github.com/pydron/ifaddr) by Stefan C. Mueller, *MIT License*
 - [Umsgpack.py](https://github.com/vsergeev/u-msgpack-python) by [Ivan A. Sergeev](https://github.com/vsergeev)
+- [rnsh](https://github.com/acehoss/rnsh) by [Aaron Heise](https://github.com/acehoss)
 - [Python](https://www.python.org)

README.mu

@@ -0,0 +1,269 @@
+>> Reticulum Network Stack
+
+To understand the foundational philosophy and goals of this system, read the `!`[Zen of Reticulum`:/page/blob.mu`g=reticulum|r=reticulum|ref=HEAD|path=Zen+of+Reticulum.md]`!.
+
+Reticulum is the cryptography-based networking stack for building local and wide-area networks with readily available hardware. It can operate even with very high latency and extremely low bandwidth. Reticulum allows you to build wide-area networks with off-the-shelf tools, and offers end-to-end encryption and connectivity, initiator anonymity, autoconfiguring cryptographically backed multi-hop transport, efficient addressing, unforgeable delivery acknowledgements and more.
+
+The vision of Reticulum is to allow anyone to be their own network operator, and to make it cheap and easy to cover vast areas with a myriad of independent, inter-connectable and autonomous networks. Reticulum **is not** *one* network. It is **a tool** for building *thousands of networks*. Networks without kill-switches, surveillance, censorship and control. Networks that can freely interoperate, associate and disassociate with each other, and require no central oversight. Networks for human beings. *Networks for the people*.
+
+Reticulum is a complete networking stack, and does not rely on IP or higher layers, but it is possible to use IP as the underlying carrier for Reticulum. It is therefore trivial to tunnel Reticulum over the Internet or private IP networks.
+
+Having no dependencies on traditional networking stacks frees up overhead that has been used to implement a networking stack built directly on cryptographic principles, allowing resilience and stable functionality, even in open and trustless networks.
+
+No kernel modules or drivers are required. Reticulum runs completely in userland, and can run on practically any system that runs Python 3.
+
+>> Read The Manual
+
+The full documentation for Reticulum is available at [markqvist.github.io/Reticulum/manual/](https://markqvist.github.io/Reticulum/manual/).
+
+You can also download the `!`[Reticulum manual as a PDF`:/file/download`g=reticulum|r=reticulum|ref=HEAD|path=docs%2FReticulum+Manual.pdf]`! or `!`[as an e-book in EPUB format`:/file/download`g=reticulum|r=reticulum|ref=HEAD|path=docs%2FReticulum+Manual.pdf]`!.
+
+For more info, see [reticulum.network](https://reticulum.network/) and [the FAQ section of the wiki](https://github.com/markqvist/Reticulum/wiki/Frequently-Asked-Questions).
+
+>> Notable Features
+
+• Coordination-less globally unique addressing and identification
+• Fully self-configuring multi-hop routing over heterogeneous carriers
+• Flexible scalability over heterogeneous topologies
+  • Reticulum can carry data over any mixture of physical mediums and topologies
+  • Low-bandwidth networks can co-exist and interoperate with large, high-bandwidth networks
+• Initiator anonymity, communicate without revealing your identity
+  • Reticulum does not include source addresses on any packets
+• Asymmetric X25519 encryption and Ed25519 signatures as a basis for all communication
+  • The foundational Reticulum Identity Keys are 512-bit Elliptic Curve keysets
+• Forward Secrecy is available for all communication types, both for single packets and over links
+• Reticulum uses the following format for encrypted tokens:
+  • Ephemeral per-packet and link keys and derived from an ECDH key exchange on Curve25519
+  • AES-256 in CBC mode with PKCS7 padding
+  • HMAC using SHA256 for authentication
+  • IVs are generated through os.urandom()
+• Unforgeable packet delivery confirmations
+• Flexible and extensible interface system
+  • Reticulum includes a large variety of built-in interface types
+  • Ability to load and utilise custom user- or community-supplied interface types
+  • Easily create your own custom interfaces for communicating over anything
+• Authentication and virtual network segmentation on all supported interface types
+• An intuitive and easy-to-use API
+  • Simpler and easier to use than sockets APIs, but more powerful
+  • Makes building distributed and decentralised applications much simpler
+• Reliable and efficient transfer of arbitrary amounts of data
+  • Reticulum can handle a few bytes of data or files of many gigabytes
+  • Sequencing, compression, transfer coordination and checksumming are automatic
+  • The API is very easy to use, and provides transfer progress
+• Lightweight, flexible and expandable Request/Response mechanism
+• Efficient link establishment
+  • Total cost of setting up an encrypted and verified link is only 3 packets, totalling 297 bytes
+  • Low cost of keeping links open at only 0.44 bits per second
+• Reliable sequential delivery with Channel and Buffer mechanisms
+
+>> Reference Implementation
+
+The Python code in this repository is the Reference Implementation of Reticulum. The Reticulum Protocol is defined entirely and authoritatively by this reference implementation, and its associated manual. It is maintained by Mark Qvist, identified by the Reticulum Identity `B333<bc7291552be7a58f361522990465165c>`b.
+
+Compatibility with the Reticulum Protocol is defined as having full interoperability, and sufficient functional parity with this reference implementation. Any specific protocol implementation that achieves this is Reticulum. Any that does not is not Reticulum.
+
+The reference implementation is licensed under the Reticulum License.
+
+The Reticulum Protocol was dedicated to the Public Domain in 2016.
+
+>> Examples of Reticulum Applications
+
+If you want to quickly get an idea of what Reticulum can do, take a look at the [Programs Using Reticulum](https://reticulum.network/manual/software.html) section of the manual, or the following resources:
+
+• [LXMF](https://github.com/markqvist/lxmf) is a distributed, delay and disruption tolerant message transfer
+  protocol built on Reticulum
+
+• The [LXST](https://github.com/markqvist/lxst) protocol and framework provides real-time audio and signals
+  transport over Reticulum. It includes primitives and utilities for building voice-based applications and
+  hardware devices, such as the `B333rnphone`b program, that can be used to build hardware telephones.
+
+• For an off-grid, encrypted and resilient mesh communications platform, see [Nomad Network](https://github.com/markqvist/NomadNet)
+
+• The Android, Linux, macOS and Windows app [Sideband](https://github.com/markqvist/Sideband) has a graphical
+  interface and many advanced features, such as file transfers, image and voice messages, real-time voice calls,
+  a distributed telemetry system, mapping capabilities and full plugin extensibility.
+
+• [MeshChatX](https://git.quad4.io/RNS-Things/MeshChatX) is a full-featured LXMF client with many built-in tools
+  and functionalities, that also supports image and voice messages, file transfers and voice calls. It also
+  includes a built-in page browser for browsing Nomad Network nodes.
+
+• You can use the included [rnsh](https://reticulum.network/manual/using.html#the-rnsh-utility) program to
+  establish remote shell sessions over Reticulum.
+
+>> Where can Reticulum be used?
+
+Over practically any medium that can support at least a half-duplex channel with greater throughput than 5 bits per second, and an MTU of 500 bytes. Data radios, modems, LoRa radios, serial lines, AX.25 TNCs, amateur radio digital modes, WiFi and Ethernet devices, free-space optical links, and similar systems are all examples of the types of physical devices Reticulum can use.
+
+An open-source LoRa-based interface called [RNode](https://markqvist.github.io/Reticulum/manual/hardware.html#rnode) has been designed specifically for use with Reticulum. It is possible to build yourself, or it can be purchased as a complete transceiver that just needs a USB connection to the host.
+
+Reticulum can also be encapsulated over existing IP networks, so there's nothing stopping you from using it over wired Ethernet, your local WiFi network or the Internet, where it'll work just as well. In fact, one of the strengths of Reticulum is how easily it allows you to connect different mediums into a self-configuring, resilient and encrypted mesh, using any available mixture of available infrastructure.
+
+As an example, it's possible to set up a Raspberry Pi connected to both a LoRa radio, a packet radio TNC and a WiFi network. Once the interfaces are configured, Reticulum will take care of the rest, and any device on the WiFi network can communicate with nodes on the LoRa and packet radio sides of the network, and vice versa.
+
+>> How do I get started?
+
+The best way to get started with the Reticulum Network Stack depends on what you want to do. For full details and examples, have a look at the  [Getting Started Fast](https://markqvist.github.io/Reticulum/manual/gettingstartedfast.html)  section of the [Reticulum Manual](https://markqvist.github.io/Reticulum/manual/).
+
+To simply install Reticulum and related utilities on your system, the easiest way is via `B333pip`b. You can then start any program that uses Reticulum, or start Reticulum as a system service with [the rnsd utility](https://markqvist.github.io/Reticulum/manual/using.html#the-rnsd-utility).
+
+`B333
+`=
+pip install rns
+`=
+`b
+
+If you are using an operating system that blocks normal user package installation via `B333pip`b, you can return `B333pip`b to normal behaviour by editing the `B333~/.config/pip/pip.conf`b file, and adding the following directive in the `B333[global]`b section:
+
+`B333
+`=
+[global]
+break-system-packages = true
+`=
+`b
+
+Alternatively, you can use the `B333pipx`b tool to install Reticulum in an isolated environment:
+
+`B333
+`=
+pipx install rns
+`=
+`b
+
+When first started, Reticulum will create a default configuration file, providing basic connectivity to other Reticulum peers that might be locally reachable. The default config file contains a few examples, and references for creating a more complex configuration.
+
+If you have an old version of `B333pip`b on your system, you may need to upgrade it first with `B333pip install pip --upgrade`b. If you no not already have `B333pip`b installed, you can install it using the package manager of your system with `B333sudo apt install python3-pip`b or similar.
+
+For more detailed examples on how to expand communication over many mediums such as packet radio or LoRa, serial ports, or over fast IP links and the Internet using the UDP and TCP interfaces, take a look at the [Supported Interfaces](https://markqvist.github.io/Reticulum/manual/interfaces.html) section of the [Reticulum Manual](https://markqvist.github.io/Reticulum/manual/).
+
+>> Included Utilities
+Reticulum includes a range of useful utilities for managing your networks, viewing status and information, and other tasks. You can read more about these programs in the [Included Utility Programs](https://markqvist.github.io/Reticulum/manual/using.html#included-utility-programs) section of the [Reticulum Manual](https://markqvist.github.io/Reticulum/manual/).
+
+• The system daemon `B333rnsd`b for running Reticulum as an always-available service
+• An interface status utility called `B333rnstatus`b, that displays information about interfaces
+• The path lookup and management tool `B333rnpath`b letting you view and modify path tables
+• A diagnostics tool called `B333rnprobe`b for checking connectivity to destinations
+• A simple file transfer program called `B333rncp`b making it easy to transfer files between systems
+• The identity management and encryption utility `B333rnid`b let's you manage Identities and encrypt/decrypt files
+• The `B333rnsh`b program allows you to establish fully interactive shell session with remote systems
+• The remote command execution program `B333rnx`b let's you run simple commands and programs and retrieve output from remote systems
+• The `B333rngit`b program provides a full multi-repository Git node for serving repositories over Reticulum
+• The included `B333git-remote-rns`b helper allows you to interact with Git repositories over Reticulum
+
+All tools, including `B333rnx`b and `B333rncp`b, work reliably and well even over very low-bandwidth links like LoRa or Packet Radio. For full-featured remote shells over Reticulum, also have a look at the [rnsh](https://github.com/acehoss/rnsh) program.
+
+>> Supported interface types and devices
+
+Reticulum implements a range of generalised interface types that covers most of the communications hardware that Reticulum can run over. If your hardware is not supported, it's [simple to implement a custom interface module](https://markqvist.github.io/Reticulum/manual/interfaces.html#custom-interfaces).
+
+Currently, the following built-in interfaces are supported:
+
+• Any Ethernet device
+• LoRa using [RNode](https://unsigned.io/rnode/)
+• Packet Radio TNCs (with or without AX.25)
+• KISS-compatible hardware and software modems
+• Any device with a serial port
+• TCP over IP networks
+• UDP over IP networks
+• External programs via stdio or pipes
+• Custom hardware via stdio or pipes
+
+>> Performance
+Reticulum targets a *very* wide usable performance envelope, but prioritises functionality and performance on low-bandwidth mediums. The goal is to provide a dynamic performance envelope from 250 bits per second, to 1 gigabit per second on normal hardware.
+
+Currently, the usable performance envelope is approximately 150 bits per second to 500 megabits per second, with physical mediums faster than that not being saturated. Performance beyond the current level is intended for future upgrades, but not highly prioritised at this point in time.
+
+>> Current Status
+All core protocol features are implemented and functioning, but additions will probably occur as real-world use is explored and understood. The API and wire-format can be considered stable.
+
+>> Dependencies
+The installation of the default `B333rns`b package requires only two external dependencies, listed below. Almost all systems and distributions have readily available packages for these dependencies, and when the `B333rns`b package is installed with `B333pip`b, they will be downloaded and installed as well.
+
+• [PyCA/cryptography](https://github.com/pyca/cryptography)
+• [pyserial](https://github.com/pyserial/pyserial)
+
+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 `B333rnspure`b package instead, which require no external dependencies for installation. Please note that the contents of the `B333rns`b and `B333rnspure`b packages are *identical*. The only difference is that the `B333rnspure`b 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](https://github.com/pyserial/pyserial), it is perfectly possible to do so using the `B333rnspure`b 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 `B333rnspure`b 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 [Cryptographic Primitives](#cryptographic-primitives) section of this document.
+
+>> Bootstrapping Connectivity
+
+Reticulum is not a service you subscribe to, nor is it a single global network you "join". Reticulum provides functionality for discovering available public interfaces over the network itself, and the broader community has provided various directories of publicly available entrypoints to bootstrap connectivity.
+
+To learn how to establish initial connectivity over Reticulum, read the [Bootstrapping Connectivity](https://reticulum.network/manual/gettingstartedfast.html#bootstrapping-connectivity) section of the manual.
+
+If you already have a general idea of how this works, you can use community-run sites such as [directory.rns.recipes](https://directory.rns.recipes/) and [rmap.world](https://rmap.world) to find interface definitions for initial connectivity to the global distributed Reticulum backbone.
+
+>> Public Testnet
+***Important!** Historically, a developer-targeted testnet was made available by the Reticulum project itself. As the amount of global Reticulum nodes and entrypoints have grown to a substantial quantity, this public testnet, including the Amsterdam Testnet entrypoint, has now been decommissioned. If your still have instances that relied on this entrypoint for connectivity, transition to using the distributed backbone instead. Reticulum now includes a full on-network interface discovery and connectivity bootstrapping system. Read the [Bootstrapping Connectivity](https://reticulum.network/manual/gettingstartedfast.html#bootstrapping-connectivity) section of the manual for pointers.*
+
+>> Support Reticulum
+For this to be possible, I need your help. Please support the continued development of open, free and private communications systems by donating via one of the following channels:
+
+• Monero:
+  84FpY1QbxHcgdseePYNmhTHcrgMX4nFfBYtz2GKYToqHVVhJp8Eaw1Z1EedRnKD19b3B8NiLCGVxzKV17UMmmeEsCrPyA5w
+
+• Bitcoin
+  bc1pgqgu8h8xvj4jtafslq396v7ju7hkgymyrzyqft4llfslz5vp99psqfk3a6
+
+• Ethereum
+  0x91C421DdfB8a30a49A71d63447ddb54cEBe3465E
+
+• Liberapay: https://liberapay.com/Reticulum/
+
+• Ko-Fi: https://ko-fi.com/markqvist
+
+>> Cryptographic Primitives
+Reticulum uses a simple suite of efficient, strong and well-tested cryptographic primitives, with widely available implementations that can be used both on general-purpose CPUs and on microcontrollers.
+
+One of the primary considerations for choosing this particular set of primitives is that they can be implemented *safely* with relatively few pitfalls, on practically all current computing platforms.
+
+The primitives listed here **are authoritative**. Anything claiming to be Reticulum, but not using these exact primitives **is not** Reticulum, and possibly an intentionally compromised or weakened clone. The utilised primitives are:
+
+• Reticulum Identity Keys are 512-bit Curve25519 keysets
+  • A 256-bit Ed25519 key for signatures
+  • A 256-bit X22519 key for ECDH key exchanges
+• HKDF for key derivation
+• Encrypted tokens are based on the [Fernet spec](https://github.com/fernet/spec/)
+  • Ephemeral keys derived from an ECDH key exchange on Curve25519
+  • HMAC using SHA256 for message authentication
+  • IVs must be generated through `B333os.urandom()`b or better
+  • AES-256 in CBC mode with PKCS7 padding
+  • No Fernet version and timestamp metadata fields
+• SHA-256
+• SHA-512
+
+In the default installation configuration, the `B333X25519`b, `B333Ed25519`b, and `B333AES-256-CBC`b primitives are provided by [OpenSSL](https://www.openssl.org/) (via the [PyCA/cryptography](https://github.com/pyca/cryptography) package). The hashing functions `B333SHA-256`b and `B333SHA-512`b are provided by the standard Python [hashlib](https://docs.python.org/3/library/hashlib.html). The `B333HKDF`b, `B333HMAC`b, `B333Token`b primitives, and the `B333PKCS7`b padding function are always provided by the following internal implementations:
+
+• [HKDF.py](RNS/Cryptography/HKDF.py)
+• [HMAC.py](RNS/Cryptography/HMAC.py)
+• [Token.py](RNS/Cryptography/Token.py)
+• [PKCS7.py](RNS/Cryptography/PKCS7.py)
+
+Reticulum also includes a complete implementation of all necessary primitives in pure Python. If OpenSSL and PyCA are not available on the system when Reticulum is started, Reticulum will instead use the internal pure-python primitives. A trivial consequence of this is performance, with the OpenSSL backend being *much* faster. The most important consequence however, is the potential loss of security by using primitives that has not seen the same amount of scrutiny, testing and review as those from OpenSSL.
+
+Please note that by default, installing Reticulum will **require** OpenSSL and PyCA to also be automatically installed if not already available. It is only possible to use the pure-python primitives if this requirement is specifically overridden by the user, for example by installing the `B333rnspure`b package instead of the normal `B333rns`b package, or by running directly from local source-code.
+
+If you want to use the internal pure-python primitives, it is **highly advisable** that you have a good understanding of the risks that this pose, and make an informed decision on whether those risks are acceptable to you.
+
+Reticulum is relatively young software, and should be considered as such. While it has been built with cryptography best-practices very foremost in mind, it _has not_ been externally security audited, and there could very well be privacy or security breaking bugs. If you want to help out, or help sponsor an audit, please do get in touch.
+
+>> Acknowledgements & Credits
+Reticulum can only exist because of the mountain of Open Source work it was built on top of, the contributions of everyone involved, and everyone that has supported the project through the years. To everyone who has helped, thank you so much.
+
+A number of other modules and projects are either part of, or used by Reticulum. Sincere thanks to the authors and contributors of the following projects:
+
+• [PyCA/cryptography](https://github.com/pyca/cryptography), *BSD License*
+• [Pure-25519](https://github.com/warner/python-pure25519) by [Brian Warner](https://github.com/warner), *MIT License*
+• [Pysha2](https://github.com/thomdixon/pysha2) by [Thom Dixon](https://github.com/thomdixon), *MIT License*
+• [Python AES-128](https://github.com/orgurar/python-aes) by [Or Gur Arie](https://github.com/orgurar), *MIT License*
+• [Python AES-256](https://github.com/boppreh/aes) by [BoppreH](https://github.com/boppreh), *MIT License*
+• [Curve25519.py](https://gist.github.com/nickovs/cc3c22d15f239a2640c185035c06f8a3#file-curve25519-py) by [Nicko van Someren](https://gist.github.com/nickovs), *Public Domain*
+• [I2Plib](https://github.com/l-n-s/i2plib) by [Viktor Villainov](https://github.com/l-n-s)
+• [PySerial](https://github.com/pyserial/pyserial) by Chris Liechti, *BSD License*
+• [Configobj](https://github.com/DiffSK/configobj) by Michael Foord, Nicola Larosa, Rob Dennis & Eli Courtwright, *BSD License*
+• [ifaddr](https://github.com/pydron/ifaddr) by Stefan C. Mueller, *MIT License*
+• [Umsgpack.py](https://github.com/vsergeev/u-msgpack-python) by [Ivan A. Sergeev](https://github.com/vsergeev)
+• [rnsh](https://github.com/acehoss/rnsh) by [Aaron Heise](https://github.com/acehoss)
+• [Python](https://www.python.org)

RNS/Buffer.py

@@ -92,7 +92,9 @@ class StreamDataMessage(MessageBase):
         self.data = raw[2:]
 
         if self.compressed:
-            self.data = bz2.decompress(self.data)
+            decompressor = bz2.BZ2Decompressor()
+            self.data = decompressor.decompress(self.data, max_length=RawChannelWriter.MAX_CHUNK_LEN)
+            if not decompressor.eof: raise IOError("Decompressed buffer chunk exceeds maximum legitimate size")
 
 
 class RawChannelReader(RawIOBase, AbstractContextManager):

RNS/Destination.py

@@ -295,33 +295,26 @@ class Destination:
                         app_data = returned_app_data
             
             signed_data = self.hash+self.identity.get_public_key()+self.name_hash+random_hash+ratchet
-            if app_data != None:
-                signed_data += app_data
+            if app_data != None: signed_data += app_data
 
             signature = self.identity.sign(signed_data)
             announce_data = self.identity.get_public_key()+self.name_hash+random_hash+ratchet+signature
 
-            if app_data != None:
-                announce_data += app_data
+            if app_data != None: announce_data += app_data
 
             self.path_responses[tag] = [time.time(), announce_data]
 
-        if path_response:
-            announce_context = RNS.Packet.PATH_RESPONSE
-        else:
-            announce_context = RNS.Packet.NONE
+        if path_response: announce_context = RNS.Packet.PATH_RESPONSE
+        else:             announce_context = RNS.Packet.NONE
 
-        if ratchet:
-            context_flag = RNS.Packet.FLAG_SET
-        else:
-            context_flag = RNS.Packet.FLAG_UNSET
+        if ratchet: context_flag = RNS.Packet.FLAG_SET
+        else:       context_flag = RNS.Packet.FLAG_UNSET
 
         announce_packet = RNS.Packet(self, announce_data, RNS.Packet.ANNOUNCE, context = announce_context,
                                      attached_interface = attached_interface, context_flag=context_flag)
-        if send:
-            announce_packet.send()
-        else:
-            return announce_packet
+        
+        if send: announce_packet.send()
+        else:    return announce_packet
 
     def accepts_links(self, accepts = None):
         """
@@ -330,13 +323,10 @@ class Destination:
         :param accepts: If ``True`` or ``False``, this method sets whether the destination accepts incoming link requests. If not provided or ``None``, the method returns whether the destination currently accepts link requests.
         :returns: ``True`` or ``False`` depending on whether the destination accepts incoming link requests, if the *accepts* parameter is not provided or ``None``.
         """
-        if accepts == None:
-            return self.accept_link_requests
+        if accepts == None: return self.accept_link_requests
 
-        if accepts:
-            self.accept_link_requests = True
-        else:
-            self.accept_link_requests = False
+        if accepts: self.accept_link_requests = True
+        else:       self.accept_link_requests = False
 
     def set_link_established_callback(self, callback):
         """
@@ -421,8 +411,7 @@ class Destination:
             else:
                 if packet.packet_type == RNS.Packet.DATA:
                     if self.callbacks.packet != None:
-                        try:
-                            self.callbacks.packet(plaintext, packet)
+                        try: self.callbacks.packet(plaintext, packet)
                         except Exception as e:
                             RNS.log("Error while executing receive callback from "+str(self)+". The contained exception was: "+str(e), RNS.LOG_ERROR)
 
@@ -462,6 +451,10 @@ class Destination:
                     self.ratchets = None
                     self.ratchets_path = None
                     RNS.trace_exception(e)
+                    RNS.log(f"The ratchet file located at {ratchets_path} could not be loaded. This could indicate that the ratchet file has become corrupt.", RNS.LOG_CRITICAL)
+                    RNS.log(f"You can attempt to manually recover the ratchet file, or simply remove it to have Reticulum recreate it on the next use.", RNS.LOG_CRITICAL)
+                    RNS.log(f"If re-initialize this ratchet file, make sure to send an announce for the relevant destination as soon as possible,", RNS.LOG_CRITICAL)
+                    RNS.log(f"so that the new ratchet information is synchronized to the network.", RNS.LOG_CRITICAL)
                     raise OSError("Could not read ratchet file contents for "+str(self)+". The contained exception was: "+str(e), RNS.LOG_ERROR)
 
         else:

RNS/Discovery.py

@@ -0,0 +1,742 @@
+import os
+import re
+import RNS
+import time
+import random
+import threading
+import ipaddress
+import subprocess
+from .vendor import umsgpack as msgpack
+
+NAME            = 0xFF
+TRANSPORT_ID    = 0xFE
+INTERFACE_TYPE  = 0x00
+TRANSPORT       = 0x01
+REACHABLE_ON    = 0x02
+LATITUDE        = 0x03
+LONGITUDE       = 0x04
+HEIGHT          = 0x05
+PORT            = 0x06
+IFAC_NETNAME    = 0x07
+IFAC_NETKEY     = 0x08
+FREQUENCY       = 0x09
+BANDWIDTH       = 0x0A
+SPREADINGFACTOR = 0x0B
+CODINGRATE      = 0x0C
+MODULATION      = 0x0D
+CHANNEL         = 0x0E
+
+APP_NAME = "rnstransport"
+
+class InterfaceAnnouncer():
+    JOB_INTERVAL = 60
+    DEFAULT_STAMP_VALUE = 14
+    WORKBLOCK_EXPAND_ROUNDS = 20
+
+    DISCOVERABLE_INTERFACE_TYPES = ["BackboneInterface", "TCPServerInterface", "TCPClientInterface",
+                                    "RNodeInterface", "WeaveInterface", "I2PInterface", "KISSInterface"]
+
+    def __init__(self, owner):
+        import importlib.util
+        if importlib.util.find_spec('LXMF') != None: from LXMF import LXStamper
+        else:
+            RNS.log("Using on-network interface discovery requires the LXMF module to be installed.", RNS.LOG_CRITICAL)
+            RNS.log("You can install it with the command: pip install lxmf", RNS.LOG_CRITICAL)
+            RNS.panic()
+
+        self.owner        = owner
+        self.should_run   = False
+        self.job_interval = self.JOB_INTERVAL
+        self.stamper      = LXStamper
+        self.stamp_cache  = {}
+
+        if self.owner.has_network_identity(): identity = self.owner.network_identity
+        else:                                 identity = self.owner.identity
+
+        self.discovery_destination = RNS.Destination(identity, RNS.Destination.IN, RNS.Destination.SINGLE,
+                                                     APP_NAME, "discovery", "interface")
+
+    def start(self):
+        if not self.should_run:
+            self.should_run = True
+            threading.Thread(target=self.job, daemon=True).start()
+
+    def stop(self): self.should_run = False
+
+    def job(self):
+        while self.should_run:
+            time.sleep(self.job_interval)
+            try:
+                now = time.time()
+                due_interfaces = [i for i in self.owner.interfaces if i.supports_discovery and i.discoverable and now > (i.last_discovery_announce+i.discovery_announce_interval)]
+                due_interfaces.sort(key=lambda i: now-i.last_discovery_announce, reverse=True)
+
+                if len(due_interfaces) > 0:
+                    selected_interface = due_interfaces[0]
+                    selected_interface.last_discovery_announce = time.time()
+                    RNS.log(f"Preparing interface discovery announce for {selected_interface.name}", RNS.LOG_DEBUG)
+                    app_data = self.get_interface_announce_data(selected_interface)
+                    if not app_data: RNS.log(f"Could not generate interface discovery announce data for {selected_interface.name}", RNS.LOG_ERROR)
+                    else:
+                        RNS.log(f"Sending interface discovery announce for {selected_interface.name} with {len(app_data)}B payload", RNS.LOG_DEBUG)
+                        self.discovery_destination.announce(app_data=app_data)
+
+            except Exception as e:
+                RNS.log(f"Error while preparing interface discovery announces: {e}", RNS.LOG_ERROR)
+                RNS.trace_exception(e)
+
+    def sanitize(self, in_str):
+        sanitized = in_str.replace("\n", "")
+        sanitized = sanitized.replace("\r", "")
+        sanitized = sanitized.strip()
+        return sanitized
+
+    def get_interface_announce_data(self, interface):
+        interface_type = type(interface).__name__
+        stamp_value    = interface.discovery_stamp_value if interface.discovery_stamp_value else self.DEFAULT_STAMP_VALUE
+
+        if not interface_type in self.DISCOVERABLE_INTERFACE_TYPES: return None
+        else:
+            flags = 0x00
+            info  = {INTERFACE_TYPE: interface_type,
+                     TRANSPORT:      RNS.Reticulum.transport_enabled(),
+                     TRANSPORT_ID:   RNS.Transport.identity.hash,
+                     NAME:           self.sanitize(interface.discovery_name),
+                     LATITUDE:       interface.discovery_latitude,
+                     LONGITUDE:      interface.discovery_longitude,
+                     HEIGHT:         interface.discovery_height}
+
+            if interface_type == "TCPClientInterface" and not interface.kiss_framing:
+                RNS.log(f"Invalid interface discovery configuration for {interface}, aborting discovery announce", RNS.LOG_ERROR)
+                return None
+
+            if interface_type in ["BackboneInterface", "TCPServerInterface"]:
+                reachable_on = self.sanitize(interface.reachable_on)
+
+                if not RNS.vendor.platformutils.is_windows():
+                    try:
+                        exec_path = os.path.expanduser(reachable_on)
+                        if os.path.isfile(exec_path) and os.access(exec_path, os.X_OK):
+                            RNS.log(f"Evaluating reachable_on from executable at {exec_path}", RNS.LOG_DEBUG)
+                            exec_result = subprocess.run([exec_path], stdout=subprocess.PIPE)
+                            exec_stdout = exec_result.stdout.decode("utf-8")
+                            if exec_result.returncode != 0: raise ValueError("Non-zero exit code from subprocess")
+                            reachable_on = self.sanitize(exec_stdout)
+                            if not (is_ip_address(reachable_on) or is_hostname(reachable_on)):
+                                raise ValueError(f"Valid IP address or hostname was not found in external script output \"{reachable_on}\"")
+
+                    except Exception as e:
+                        RNS.log(f"Error while getting reachable_on from executable at {interface.reachable_on}: {e}", RNS.LOG_ERROR)
+                        RNS.log(f"Aborting discovery announce", RNS.LOG_ERROR)
+                        return None
+
+                if not (is_ip_address(reachable_on) or is_hostname(reachable_on)):
+                    RNS.log(f"The configured reachable_on parameter \"{reachable_on}\" for {interface} is not a valid IP address or hostname", RNS.LOG_ERROR)
+                    RNS.log(f"Aborting discovery announce", RNS.LOG_ERROR)
+                    return None
+
+                info[REACHABLE_ON]    = reachable_on
+                info[PORT]            = interface.bind_port
+
+            if interface_type == "I2PInterface" and interface.connectable and interface.b32:
+                info[REACHABLE_ON]    = interface.b32
+
+            if interface_type == "RNodeInterface":
+                info[FREQUENCY]       = interface.frequency
+                info[BANDWIDTH]       = interface.bandwidth
+                info[SPREADINGFACTOR] = interface.sf
+                info[CODINGRATE]      = interface.cr
+
+            if interface_type == "WeaveInterface":
+                info[FREQUENCY]       = interface.discovery_frequency
+                info[BANDWIDTH]       = interface.discovery_bandwidth
+                info[CHANNEL]         = interface.discovery_channel
+                info[MODULATION]      = interface.discovery_modulation
+
+            if interface_type == "KISSInterface" or (interface_type == "TCPClientInterface" and interface.kiss_framing):
+                info[INTERFACE_TYPE]  = "KISSInterface"
+                info[FREQUENCY]       = interface.discovery_frequency
+                info[BANDWIDTH]       = interface.discovery_bandwidth
+                info[MODULATION]      = self.sanitize(interface.discovery_modulation)
+
+            if interface.discovery_publish_ifac == True:
+                info[IFAC_NETNAME]    = self.sanitize(interface.ifac_netname)
+                info[IFAC_NETKEY]     = self.sanitize(interface.ifac_netkey)
+
+            packed    = msgpack.packb(info)
+            infohash  = RNS.Identity.full_hash(packed)
+
+            if infohash in self.stamp_cache: stamp = self.stamp_cache[infohash]
+            else: stamp, v = self.stamper.generate_stamp(infohash, stamp_cost=stamp_value, expand_rounds=self.WORKBLOCK_EXPAND_ROUNDS)
+            if not stamp: return None
+            else: self.stamp_cache[infohash] = stamp
+
+            if interface.discovery_encrypt:
+                flags |= InterfaceAnnounceHandler.FLAG_ENCRYPTED
+                if not self.owner.has_network_identity():
+                    RNS.log(f"Discovery encryption requested for {interface}, but no network identity configured. Aborting discovery announce.", RNS.LOG_ERROR)
+                    return None
+                
+                else: payload = self.owner.network_identity.encrypt(packed+stamp)
+                    
+            else: payload = packed+stamp
+
+            return bytes([flags])+payload
+
+class InterfaceAnnounceHandler:
+    FLAG_SIGNED       = 0b00000001
+    FLAG_ENCRYPTED    = 0b00000010
+
+    def __init__(self, required_value=InterfaceAnnouncer.DEFAULT_STAMP_VALUE, callback=None):
+        import importlib.util
+        if importlib.util.find_spec('LXMF') != None: from LXMF import LXStamper
+        else:
+            RNS.log("Using on-network interface discovery requires the LXMF module to be installed.", RNS.LOG_CRITICAL)
+            RNS.log("You can install it with the command: pip install lxmf", RNS.LOG_CRITICAL)
+            RNS.panic()
+
+        self.aspect_filter  = APP_NAME+".discovery.interface"
+        self.required_value = required_value
+        self.callback       = callback
+        self.stamper        = LXStamper
+
+    def received_announce(self, destination_hash, announced_identity, app_data):
+        try:
+            discovery_sources = RNS.Reticulum.interface_discovery_sources()
+            if discovery_sources and not announced_identity.hash in discovery_sources:
+                RNS.log(f"Interface discovered from non-authorized network identity {RNS.prettyhexrep(announced_identity.hash)}, ignoring", RNS.LOG_DEBUG)
+                return
+
+            if app_data and len(app_data) > self.stamper.STAMP_SIZE+1:
+                flags     = app_data[0]
+                app_data  = app_data[1:]
+                signed    = flags & self.FLAG_SIGNED
+                encrypted = flags & self.FLAG_ENCRYPTED
+
+                if encrypted:
+                    if not RNS.Transport.has_network_identity(): return
+                    app_data = RNS.Transport.network_identity.decrypt(app_data)
+                    if not app_data: return
+
+                stamp     = app_data[-self.stamper.STAMP_SIZE:]
+                packed    = app_data[:-self.stamper.STAMP_SIZE]
+                infohash  = RNS.Identity.full_hash(packed)
+                workblock = self.stamper.stamp_workblock(infohash, expand_rounds=InterfaceAnnouncer.WORKBLOCK_EXPAND_ROUNDS)
+                value     = self.stamper.stamp_value(workblock, stamp)
+                valid     = self.stamper.stamp_valid(stamp, self.required_value, workblock)
+
+                if not valid:
+                    RNS.log(f"Ignored discovered interface with invalid stamp", RNS.LOG_DEBUG)
+                    return
+
+                if value < self.required_value: RNS.log(f"Ignored discovered interface with stamp value {value}", RNS.LOG_DEBUG)
+                else:
+                    info     = None
+                    unpacked = msgpack.unpackb(packed)
+                    if INTERFACE_TYPE in unpacked:
+                        interface_type        = unpacked[INTERFACE_TYPE]
+                        info = {"type":         interface_type,
+                                "transport":    unpacked[TRANSPORT],
+                                "name":         unpacked[NAME] or f"Discovered {interface_type}",
+                                "received":     time.time(),
+                                "stamp":        stamp,
+                                "value":        value,
+                                "transport_id": RNS.hexrep(unpacked[TRANSPORT_ID], delimit=False),
+                                "network_id":   RNS.hexrep(announced_identity.hash, delimit=False),
+                                "hops":         RNS.Transport.hops_to(destination_hash),
+                                "latitude":     unpacked[LATITUDE],
+                                "longitude":    unpacked[LONGITUDE],
+                                "height":       unpacked[HEIGHT]}
+
+                        if REACHABLE_ON in unpacked:
+                            if not (is_ip_address(unpacked[REACHABLE_ON]) or is_hostname(unpacked[REACHABLE_ON])):
+                                raise ValueError("Invalid data in reachable_on field of announce")
+
+                        if IFAC_NETNAME in unpacked: info["ifac_netname"] = unpacked[IFAC_NETNAME]
+                        if IFAC_NETKEY  in unpacked: info["ifac_netkey"]  = unpacked[IFAC_NETKEY]
+
+                        if interface_type in ["BackboneInterface", "TCPServerInterface"]:
+                            backbone_support     = not RNS.vendor.platformutils.is_windows()
+                            info["reachable_on"] = unpacked[REACHABLE_ON]
+                            info["port"]         = unpacked[PORT]
+                            connection_interface = "BackboneInterface" if backbone_support else "TCPClientInterface"
+                            remote_str           = "remote" if backbone_support else "target_host"
+                            cfg_name             = info["name"]
+                            cfg_remote           = info["reachable_on"]
+                            cfg_port             = info["port"]
+                            cfg_identity         = info["transport_id"]
+                            cfg_netname          = info["ifac_netname"] if "ifac_netname" in info else None
+                            cfg_netkey           = info["ifac_netkey"] if "ifac_netkey" in info else None
+                            cfg_netname_str      = f"\n  network_name = {cfg_netname}" if cfg_netname else ""
+                            cfg_netkey_str       = f"\n  passphrase = {cfg_netkey}" if cfg_netkey else ""
+                            cfg_identity_str     = f"\n  transport_identity = {cfg_identity}"
+                            info["config_entry"] = f"[[{cfg_name}]]\n  type = {connection_interface}\n  enabled = yes\n  {remote_str} = {cfg_remote}\n  target_port = {cfg_port}{cfg_identity_str}{cfg_netname_str}{cfg_netkey_str}"
+
+                        if interface_type == "I2PInterface":
+                            info["reachable_on"] = unpacked[REACHABLE_ON]
+                            cfg_name             = info["name"]
+                            cfg_remote           = info["reachable_on"]
+                            cfg_identity         = info["transport_id"]
+                            cfg_netname          = info["ifac_netname"] if "ifac_netname" in info else None
+                            cfg_netkey           = info["ifac_netkey"] if "ifac_netkey" in info else None
+                            cfg_netname_str      = f"\n  network_name = {cfg_netname}" if cfg_netname else ""
+                            cfg_netkey_str       = f"\n  passphrase = {cfg_netkey}" if cfg_netkey else ""
+                            cfg_identity_str     = f"\n  transport_identity = {cfg_identity}"
+                            info["config_entry"] = f"[[{cfg_name}]]\n  type = I2PInterface\n  enabled = yes\n  peers = {cfg_remote}{cfg_identity_str}{cfg_netname_str}{cfg_netkey_str}"
+
+                        if interface_type == "RNodeInterface":
+                            info["frequency"]    = unpacked[FREQUENCY]
+                            info["bandwidth"]    = unpacked[BANDWIDTH]
+                            info["sf"]           = unpacked[SPREADINGFACTOR]
+                            info["cr"]           = unpacked[CODINGRATE]
+                            cfg_name             = info["name"]
+                            cfg_frequency        = info["frequency"]
+                            cfg_bandwidth        = info["bandwidth"]
+                            cfg_sf               = info["sf"]
+                            cfg_cr               = info["cr"]
+                            cfg_identity         = info["transport_id"]
+                            cfg_netname          = info["ifac_netname"] if "ifac_netname" in info else None
+                            cfg_netkey           = info["ifac_netkey"] if "ifac_netkey" in info else None
+                            cfg_netname_str      = f"\n  network_name = {cfg_netname}" if cfg_netname else ""
+                            cfg_netkey_str       = f"\n  passphrase = {cfg_netkey}" if cfg_netkey else ""
+                            cfg_identity_str     = f"\n  transport_identity = {cfg_identity}"
+                            info["config_entry"] = f"[[{cfg_name}]]\n  type = RNodeInterface\n  enabled = yes\n  port = \n  frequency = {cfg_frequency}\n  bandwidth = {cfg_bandwidth}\n  spreadingfactor = {cfg_sf}\n  codingrate = {cfg_cr}\n  txpower = {cfg_netname_str}{cfg_netkey_str}"
+
+                        if interface_type == "WeaveInterface":
+                            info["frequency"]    = unpacked[FREQUENCY]
+                            info["bandwidth"]    = unpacked[BANDWIDTH]
+                            info["channel"]      = unpacked[CHANNEL]
+                            info["modulation"]   = unpacked[MODULATION]
+                            cfg_name             = info["name"]
+                            cfg_identity         = info["transport_id"]
+                            cfg_netname          = info["ifac_netname"] if "ifac_netname" in info else None
+                            cfg_netkey           = info["ifac_netkey"] if "ifac_netkey" in info else None
+                            cfg_netname_str      = f"\n  network_name = {cfg_netname}" if cfg_netname else ""
+                            cfg_netkey_str       = f"\n  passphrase = {cfg_netkey}" if cfg_netkey else ""
+                            cfg_identity_str     = f"\n  transport_identity = {cfg_identity}"
+                            info["config_entry"] = f"[[{cfg_name}]]\n  type = WeaveInterface\n  enabled = yes\n  port = {cfg_netname_str}{cfg_netkey_str}"
+
+                        if interface_type == "KISSInterface":
+                            info["frequency"]    = unpacked[FREQUENCY]
+                            info["bandwidth"]    = unpacked[BANDWIDTH]
+                            info["modulation"]   = unpacked[MODULATION]
+                            cfg_name             = info["name"]
+                            cfg_frequency        = info["frequency"]
+                            cfg_bandwidth        = info["bandwidth"]
+                            cfg_modulation       = info["modulation"]
+                            cfg_identity         = info["transport_id"]
+                            cfg_netname          = info["ifac_netname"] if "ifac_netname" in info else None
+                            cfg_netkey           = info["ifac_netkey"] if "ifac_netkey" in info else None
+                            cfg_netname_str      = f"\n  network_name = {cfg_netname}" if cfg_netname else ""
+                            cfg_netkey_str       = f"\n  passphrase = {cfg_netkey}" if cfg_netkey else ""
+                            cfg_identity_str     = f"\n  transport_identity = {cfg_identity}"
+                            info["config_entry"] = f"[[{cfg_name}]]\n  type = KISSInterface\n  enabled = yes\n  port = \n  # Frequency: {cfg_frequency}\n  # Bandwidth: {cfg_bandwidth}\n  # Modulation: {cfg_modulation}{cfg_identity_str}{cfg_netname_str}{cfg_netkey_str}"
+
+                        discovery_hash_material = info["transport_id"]+info["name"]
+                        info["discovery_hash"] = RNS.Identity.full_hash(discovery_hash_material.encode("utf-8"))
+
+                    if self.callback and callable(self.callback): self.callback(info)
+
+        except Exception as e:
+            RNS.log(f"An error occurred while trying to decode discovered interface. The contained exception was: {e}", RNS.LOG_DEBUG)
+
+class InterfaceDiscovery():
+    THRESHOLD_UNKNOWN  = 24*60*60
+    THRESHOLD_STALE    = 3*24*60*60
+    THRESHOLD_REMOVE   = 7*24*60*60
+
+    MONITOR_INTERVAL   = 5
+    DETACH_THRESHOLD   = 12
+
+    STATUS_STALE       = 0
+    STATUS_UNKNOWN     = 100
+    STATUS_AVAILABLE   = 1000
+    STATUS_CODE_MAP    = {"available": STATUS_AVAILABLE, "unknown": STATUS_UNKNOWN, "stale": STATUS_STALE}
+    AUTOCONNECT_TYPES  = ["BackboneInterface", "TCPServerInterface"]
+    DISCOVERABLE_TYPES = ["BackboneInterface", "TCPServerInterface", "I2PInterface", "RNodeInterface", "WeaveInterface", "KISSInterface"]
+
+    def __init__(self, required_value=InterfaceAnnouncer.DEFAULT_STAMP_VALUE, callback=None, discover_interfaces=True):
+        if not required_value: required_value = InterfaceAnnouncer.DEFAULT_STAMP_VALUE
+
+        self.required_value          = required_value
+        self.discovery_callback      = callback
+        self.rns_instance            = RNS.Reticulum.get_instance()
+        self.monitored_interfaces    = []
+        self.monitoring_autoconnects = False
+        self.monitor_interval        = self.MONITOR_INTERVAL
+        self.detach_threshold        = self.DETACH_THRESHOLD
+        self.initial_autoconnect_ran = False
+
+        if not self.rns_instance: raise SystemError("Attempt to start interface discovery listener without an active RNS instance")
+        self.storagepath = os.path.join(RNS.Reticulum.storagepath, "discovery", "interfaces")
+        if not os.path.isdir(self.storagepath): os.makedirs(self.storagepath)
+        
+        if discover_interfaces:
+            self.handler = InterfaceAnnounceHandler(callback=self.interface_discovered, required_value=self.required_value)
+            RNS.Transport.register_announce_handler(self.handler)
+            threading.Thread(target=self.connect_discovered, daemon=True).start()
+
+    def list_discovered_interfaces(self, only_available=False, only_transport=False):
+        now = time.time()
+        discovered_interfaces = []
+        discovery_sources = RNS.Reticulum.interface_discovery_sources()
+        for filename in os.listdir(self.storagepath):
+            try:
+                filepath = os.path.join(self.storagepath, filename)
+                with open(filepath, "rb") as f: info = msgpack.unpackb(f.read())
+                should_remove = False
+                heard_delta = now-info["last_heard"]
+                
+                if heard_delta > self.THRESHOLD_REMOVE: should_remove = True
+                elif discovery_sources and not "network_id" in info: should_remove = True
+                elif discovery_sources and not bytes.fromhex(info["network_id"]) in discovery_sources: should_remove = True
+                elif not "type" in info or ("type" in info and not info["type"] in self.DISCOVERABLE_TYPES): should_remove = True
+                elif "reachable_on" in info:
+                    if not (is_ip_address(info["reachable_on"]) or is_hostname(info["reachable_on"])): should_remove = True
+
+                if should_remove:
+                    os.unlink(filepath)
+                    continue
+                
+                else:
+                    if   heard_delta > self.THRESHOLD_STALE:   info["status"] = "stale"
+                    elif heard_delta > self.THRESHOLD_UNKNOWN: info["status"] = "unknown"
+                    else:                                      info["status"] = "available"
+
+                    info["status_code"] = self.STATUS_CODE_MAP[info["status"]]
+                    if not only_available and not only_transport: discovered_interfaces.append(info)
+                    else:
+                        should_append = True
+                        status = info["status"]
+                        transport = info["transport"]
+                        if only_available and status != "available": should_append = False
+                        if only_transport and not transport:         should_append = False
+                        if should_append: discovered_interfaces.append(info)
+
+            except Exception as e:
+                RNS.log(f"Error while loading discovered interface data: {e}", RNS.LOG_ERROR)
+                RNS.log(f"The interface data file {os.path.join(self.storagepath, filename)} may be corrupt", RNS.LOG_ERROR)
+                RNS.trace_exception(e)
+
+        discovered_interfaces.sort(key=lambda info: (info["status_code"], info["value"], info["last_heard"]), reverse=True)
+        return discovered_interfaces
+
+    def interface_discovered(self, info):
+        try:
+            name = info["name"]
+            value = info["value"]
+            interface_type = info["type"]
+            discovery_hash = info["discovery_hash"]
+            discovered_type = info["type"]
+            if not discovered_type in self.DISCOVERABLE_TYPES: return
+            hops = info["hops"]; ms = "" if hops == 1 else "s"
+            filename = RNS.hexrep(discovery_hash, delimit=False)
+            filepath = os.path.join(self.storagepath, filename)
+            RNS.log(f"Discovered {interface_type} {hops} hop{ms} away with stamp value {value}: {name}", RNS.LOG_DEBUG)
+            if not os.path.isfile(filepath):
+                try:
+                    with open(filepath, "wb") as f:
+                        info["discovered"]  = info["received"]
+                        info["last_heard"]  = info["received"]
+                        info["heard_count"] = 0
+                        f.write(msgpack.packb(info))
+                
+                except Exception as e:
+                    RNS.log(f"Error while persisting discovered interface data: {e}", RNS.LOG_ERROR)
+                    RNS.trace_exception(e)
+                    return
+
+            else:
+                discovered  = None
+                heard_count = None
+                try:
+                    with open(filepath, "rb") as f:
+                        last_info   = msgpack.unpackb(f.read())
+                        discovered  = last_info["discovered"]
+                        heard_count = last_info["heard_count"]
+
+                    if discovered  == None: discovered  = info["discovered"]
+                    if heard_count == None: heard_count = 0
+
+                    with open(filepath, "wb") as f:
+                        info["discovered"] = discovered
+                        info["last_heard"] = info["received"]
+                        info["heard_count"] = heard_count+1
+                        f.write(msgpack.packb(info))
+
+                except Exception as e:
+                    RNS.log(f"Error while persisting discovered interface data: {e}", RNS.LOG_ERROR)
+                    RNS.trace_exception(e)
+                    return
+
+        except Exception as e:
+            RNS.log(f"Error processing discovered interface data: {e}", RNS.LOG_ERROR)
+            RNS.trace_exception(e)
+            return
+
+        self.autoconnect(info)
+
+        try:
+            if self.discovery_callback and callable(self.discovery_callback): self.discovery_callback(info)
+        except Exception as e: RNS.log(f"Error while processing external interface discovery callback: {e}", RNS.LOG_ERROR)
+
+    def monitor_interface(self, interface):
+        if not interface in self.monitored_interfaces:
+            self.monitored_interfaces.append(interface)
+
+        if not self.monitoring_autoconnects:
+            self.monitoring_autoconnects = True
+            threading.Thread(target=self.__monitor_job, daemon=True).start()
+
+    def __monitor_job(self):
+        while self.monitoring_autoconnects:
+            time.sleep(self.monitor_interval)
+            detached_interfaces = []
+            online_interfaces = 0
+            autoconnected_interfaces = self.autoconnect_count()
+            for interface in self.monitored_interfaces:
+                try:
+                    if interface.online:
+                        online_interfaces += 1
+                        if hasattr(interface, "autoconnect_down") and interface.autoconnect_down != None:
+                            RNS.log(f"Auto-discovered interface {interface} reconnected")
+                            interface.autoconnect_down = None
+
+                    else:
+                        if not hasattr(interface, "autoconnect_down") or interface.autoconnect_down == None:
+                            RNS.log(f"Auto-discovered interface {interface} disconnected", RNS.LOG_DEBUG)
+                            interface.autoconnect_down = time.time()
+
+                        else:
+                            down_for = time.time()-interface.autoconnect_down
+                            if down_for >= self.detach_threshold:
+                                RNS.log(f"Auto-discovered interface {interface} has been down for {RNS.prettytime(down_for)}, detaching", RNS.LOG_DEBUG)
+                                detached_interfaces.append(interface)
+
+                except Exception as e:
+                    RNS.log(f"Error while checking auto-connected interface state for {interface}: {e}", RNS.LOG_ERROR)
+
+            max_autoconnected_interfaces = RNS.Reticulum.max_autoconnected_interfaces()
+            free_slots = max(0, max_autoconnected_interfaces - autoconnected_interfaces)
+            reserved_slots = max_autoconnected_interfaces//4
+
+            if online_interfaces >= max_autoconnected_interfaces:
+                for interface in RNS.Transport.interfaces:
+                    if hasattr(interface, "bootstrap_only") and interface.bootstrap_only == True:
+                        RNS.log(f"Tearing down bootstrap-only {interface} since target connected auto-discovered interface count has been reached", RNS.LOG_INFO)
+                        if not interface in detached_interfaces: detached_interfaces.append(interface)
+
+            if online_interfaces == 0:
+                if self.bootstrap_interface_count() == 0:
+                    RNS.log(f"No auto-discovered interfaces connected, re-enabling bootstrap interfaces", RNS.LOG_NOTICE)
+                    for config in RNS.Reticulum.get_instance().bootstrap_configs:
+                        RNS.Reticulum.get_instance()._synthesize_interface(config, config["name"])
+
+            if self.initial_autoconnect_ran and free_slots > reserved_slots:
+                candidate_interfaces = self.list_discovered_interfaces(only_available=True, only_transport=True)
+                if len(candidate_interfaces) > 0:
+                    random.shuffle(candidate_interfaces)
+                    selected_interface = candidate_interfaces[0]
+                    if not self.interface_exists(selected_interface): self.autoconnect(selected_interface)
+
+            for interface in detached_interfaces:
+                try: self.teardown_interface(interface)
+                except Exception as e:
+                    RNS.log(f"Error while de-registering auto-connected interface from transport: {e}", RNS.LOG_ERROR)
+
+    def teardown_interface(self, interface):
+        interface.detach()
+        if interface in RNS.Transport.interfaces:  RNS.Transport.interfaces.remove(interface)
+        if interface in self.monitored_interfaces: self.monitored_interfaces.remove(interface)
+
+    def autoconnect_count(self):
+        return len([i for i in RNS.Transport.interfaces if hasattr(i, "autoconnect_hash")])
+
+    def bootstrap_interface_count(self):
+        return len([i for i in RNS.Transport.interfaces if hasattr(i, "bootstrap_only") and i.bootstrap_only == True])
+        
+    def connect_discovered(self):
+        if RNS.Reticulum.should_autoconnect_discovered_interfaces():
+            try:
+                discovered_interfaces = self.list_discovered_interfaces(only_transport=True)
+                for info in discovered_interfaces:
+                    if self.autoconnect_count() >= RNS.Reticulum.max_autoconnected_interfaces(): break
+                    self.autoconnect(info)
+
+                self.initial_autoconnect_ran = True
+
+            except Exception as e:
+                RNS.log(f"Error while reconnecting discovered interfaces: {e}", RNS.LOG_ERROR)
+
+    def endpoint_hash(self, info):
+        endpoint_specifier = ""
+        if "reachable_on" in info: endpoint_specifier += str(info["reachable_on"])
+        if "port" in info:         endpoint_specifier += ":"+str(info["port"])
+        endpoint_hash = RNS.Identity.full_hash(endpoint_specifier.encode("utf-8"))
+        return endpoint_hash
+
+    def interface_exists(self, info):
+        exists = False
+        for interface in RNS.Transport.interfaces:
+            if hasattr(interface, "autoconnect_hash") and interface.autoconnect_hash == self.endpoint_hash(info):
+                exists = True
+                break
+            
+            else:
+                dest_match = "reachable_on" in info and hasattr(interface, "target_ip") and interface.target_ip == info["reachable_on"]
+                port_match = not "port" in info or (hasattr(interface, "target_port") and "port" in info and interface.target_port == info["port"])
+                b32d_match = "reachable_on" in info and hasattr(interface, "b32") and interface.b32 == info["reachable_on"]
+
+                if (dest_match and port_match) or b32d_match:
+                    exists = True
+                    break
+
+        return exists
+
+    def autoconnect(self, info):
+        try:
+            if RNS.Reticulum.should_autoconnect_discovered_interfaces():
+                autoconnected_count = self.autoconnect_count()
+                if autoconnected_count < RNS.Reticulum.max_autoconnected_interfaces():
+                    interface_type = info["type"]
+                    if interface_type in self.AUTOCONNECT_TYPES:
+                        endpoint_hash = self.endpoint_hash(info)
+                        exists = self.interface_exists(info)
+
+                        if exists: RNS.log(f"Discovered {interface_type} already exists, not auto-connecting", RNS.LOG_DEBUG)
+                        else:
+                            if interface_type == "TCPClientInterface":
+                                RNS.log(f"Your operating system does not support the Backbone interface type, and must degrade to using TCPClientInterface instead", RNS.LOG_WARNING)
+                                RNS.log(f"Auto-connecting discovered TCPClient interfaces is not yet implemented, aborting auto-connect", RNS.LOG_WARNING)
+                                RNS.log(f"You can obtain the configuration entry and add this interface manually instead using rnstatus -D", RNS.LOG_WARNING)
+                                return
+
+                            if interface_type == "I2PInterface":
+                                RNS.log(f"Auto-connecting discovered I2P interfaces is not yet implemented, aborting auto-connect", RNS.LOG_WARNING)
+                                RNS.log(f"You can obtain the configuration entry and add this interface manually instead using rnstatus -D", RNS.LOG_WARNING)
+                                return
+
+                            interface_name = info["name"]
+                            RNS.log(f"Auto-connecting discovered {interface_type} {interface_name}")
+                            config_entry = info["config_entry"]
+                            interface_config = {}
+                            interface_config["name"] = f"{interface_name}"
+                            ifac_netname = info["ifac_netname"] if "ifac_netname" in info else None
+                            ifac_netkey  = info["ifac_netkey"]  if "ifac_netkey"  in info else None
+                            interface    = None
+
+                            if interface_type == "BackboneInterface":
+                                from RNS.Interfaces import BackboneInterface
+                                interface_config["target_host"] = info["reachable_on"]
+                                interface_config["target_port"] = info["port"]
+                                interface = BackboneInterface.BackboneClientInterface(RNS.Transport, interface_config)
+
+                            if interface:
+                                interface.autoconnect_hash = endpoint_hash
+                                interface.autoconnect_source = info["network_id"]
+                                RNS.Reticulum.get_instance()._add_interface(interface, ifac_netname=ifac_netname, ifac_netkey=ifac_netkey, configured_bitrate=5E6)
+                                self.monitor_interface(interface)
+
+        except Exception as e:
+            RNS.log(f"Error while auto-connecting discovered interface: {e}", RNS.LOG_ERROR)
+            RNS.trace_exception(e)
+
+class BlackholeUpdater():
+    INITIAL_WAIT    = 20
+    JOB_INTERVAL    = 60
+    UPDATE_INTERVAL = 1*60*60
+    SOURCE_TIMEOUT  = 25
+
+    def __init__(self):
+        self.last_updates = {}
+        self.should_run   = False
+        self.job_interval = self.JOB_INTERVAL
+        self.update_lock  = threading.Lock()
+
+    def start(self):
+        if not self.should_run:
+            source_count = len(RNS.Reticulum.blackhole_sources())
+            ms = "" if source_count == 1 else "s"
+            RNS.log(f"Starting blackhole updater with {source_count} source{ms}", RNS.LOG_DEBUG)
+            self.should_run = True
+            threading.Thread(target=self.job, daemon=True).start()
+
+    def stop(self): self.should_run = False
+
+    def update_link_established(self, link):
+        remote_identity = link.get_remote_identity()
+        RNS.log(f"Link established for blackhole list update from {RNS.prettyhexrep(remote_identity.hash)}", RNS.LOG_DEBUG)
+        receipt = link.request("/list")
+        while not receipt.concluded(): time.sleep(0.2)
+        response = receipt.get_response()
+        link.teardown()
+        
+        if type(response) == dict: blackhole_list = response
+        else:                      blackhole_list = None
+
+        if blackhole_list:
+            added = 0
+            for identity_hash in blackhole_list:
+                entry = blackhole_list[identity_hash]
+                if not identity_hash in RNS.Transport.blackholed_identities:
+                    RNS.Transport.blackholed_identities[identity_hash] = entry
+                    added += 1
+
+            if added > 0:
+                spec = "identity" if added == 1 else "identities"
+                RNS.log(f"Added {added} blackholed {spec} from {RNS.prettyhexrep(remote_identity.hash)}", RNS.LOG_DEBUG)
+
+                try:
+                    sourcelistpath = os.path.join(RNS.Reticulum.blackholepath, RNS.hexrep(remote_identity.hash, delimit=False))
+                    tmppath = f"{sourcelistpath}.tmp"
+                    with open(tmppath, "wb") as f: f.write(msgpack.packb(blackhole_list))
+                    if os.path.isfile(sourcelistpath): os.unlink(sourcelistpath)
+                    os.rename(tmppath, sourcelistpath)
+                
+                except Exception as e:
+                    RNS.log(f"Error while persisting blackhole list from {RNS.prettyhexrep(remote_identity.hash)}: {e}", RNS.LOG_ERROR)
+
+        RNS.log(f"Blackhole list update from {RNS.prettyhexrep(remote_identity.hash)} completed", RNS.LOG_DEBUG)
+
+    def job(self):
+        time.sleep(self.INITIAL_WAIT)
+        while self.should_run:
+            try:
+                now = time.time()
+                for identity_hash in RNS.Reticulum.blackhole_sources():
+                    if identity_hash in self.last_updates: last_update = self.last_updates[identity_hash]
+                    else:                                  last_update = 0
+
+                    if now > last_update+self.UPDATE_INTERVAL:
+                        try:
+                            destination_hash = RNS.Destination.hash_from_name_and_identity("rnstransport.info.blackhole", identity_hash)
+                            RNS.log(f"Attempting blackhole list update from {RNS.prettyhexrep(identity_hash)}...", RNS.LOG_DEBUG)
+                            if not RNS.Transport.await_path(destination_hash): RNS.log(f"No path available for blackhole list update from {RNS.prettyhexrep(identity_hash)}, retrying later", RNS.LOG_VERBOSE)
+                            else:
+                                remote_identity = RNS.Identity.recall(destination_hash)
+                                destination = RNS.Destination(remote_identity, RNS.Destination.OUT, RNS.Destination.SINGLE, "rnstransport", "info", "blackhole")
+                                RNS.Link(destination, established_callback=self.update_link_established)
+                                self.last_updates[identity_hash] = time.time()
+
+                        except Exception as e:
+                            RNS.log(f"Error while establishing link for blackhole list update from {RNS.prettyhexrep(identity_hash)}: {e}", RNS.LOG_ERROR)
+
+            except Exception as e:
+                RNS.log(f"Error in blackhole list updater job: {e}", RNS.LOG_ERROR)
+                RNS.trace_exception(e)
+
+            time.sleep(self.job_interval)
+
+def is_ip_address(address_string):
+    try:
+        ipaddress.ip_address(address_string)
+        return True
+    except: return False
+
+def is_hostname(hostname):
+    if hostname[-1] == ".": hostname = hostname[:-1]
+    if len(hostname) > 253: return False
+    components = hostname.split(".")
+    if re.match(r"[0-9]+$", components[-1]): return False
+    allowed = re.compile(r"(?!-)[a-z0-9-]{1,63}(?<!-)$", re.IGNORECASE)
+    return all(allowed.match(label) for label in components)

RNS/Identity.py

@@ -94,17 +94,25 @@ class Identity:
     known_ratchets = {}
 
     ratchet_persist_lock = threading.Lock()
+    known_destinations_lock = threading.Lock()
 
     @staticmethod
     def remember(packet_hash, destination_hash, public_key, app_data = None):
         if len(public_key) != Identity.KEYSIZE//8:
             raise TypeError("Can't remember "+RNS.prettyhexrep(destination_hash)+", the public key size of "+str(len(public_key))+" is not valid.", RNS.LOG_ERROR)
         else:
-            Identity.known_destinations[destination_hash] = [time.time(), packet_hash, public_key, app_data]
-
+            with Identity.known_destinations_lock:
+                if not destination_hash in Identity.known_destinations:
+                    Identity.known_destinations[destination_hash] = [time.time(), packet_hash, public_key, app_data, 0]
+                else:
+                    entry = Identity.known_destinations[destination_hash]
+                    entry[0] = time.time()
+                    entry[1] = packet_hash
+                    entry[2] = public_key
+                    entry[3] = app_data
 
     @staticmethod
-    def recall(target_hash, from_identity_hash=False):
+    def recall(target_hash, from_identity_hash=False, _no_use=False):
         """
         Recall identity for a destination or identity hash. By default, this function
         will return the identity associated with a given *destination* hash. As an
@@ -120,6 +128,7 @@ class Identity:
         if from_identity_hash:
             for destination_hash in Identity.known_destinations:
                 if target_hash == Identity.truncated_hash(Identity.known_destinations[destination_hash][2]):
+                    if not _no_use: RNS.Reticulum.get_instance()._used_destination_data(destination_hash)
                     identity_data = Identity.known_destinations[destination_hash]
                     identity = Identity(create_keys=False)
                     identity.load_public_key(identity_data[2])
@@ -130,6 +139,7 @@ class Identity:
 
         else:
             if target_hash in Identity.known_destinations:
+                if not _no_use: RNS.Reticulum.get_instance()._used_destination_data(target_hash)
                 identity_data = Identity.known_destinations[target_hash]
                 identity = Identity(create_keys=False)
                 identity.load_public_key(identity_data[2])
@@ -146,7 +156,7 @@ class Identity:
                 return None
 
     @staticmethod
-    def recall_app_data(destination_hash):
+    def recall_app_data(destination_hash, _no_use=False):
         """
         Recall last heard app_data for a destination hash.
 
@@ -154,13 +164,14 @@ class Identity:
         :returns: *Bytes* containing app_data, or *None* if the destination is unknown.
         """
         if destination_hash in Identity.known_destinations:
+            if not _no_use: RNS.Reticulum.get_instance()._used_destination_data(destination_hash)
             app_data = Identity.known_destinations[destination_hash][3]
             return app_data
-        else:
-            return None
+        
+        else: return None
 
     @staticmethod
-    def save_known_destinations():
+    def save_known_destinations(background=False, recombine=True):
         # TODO: Improve the storage method so we don't have to
         # deserialize and serialize the entire table on every
         # save, but the only changes. It might be possible to
@@ -181,34 +192,33 @@ class Identity:
             Identity.saving_known_destinations = True
             save_start = time.time()
 
-            storage_known_destinations = {}
-            if os.path.isfile(RNS.Reticulum.storagepath+"/known_destinations"):
+            if recombine:
+                storage_known_destinations = {}
+                if os.path.isfile(RNS.Reticulum.storagepath+"/known_destinations"):
+                    try:
+                        with open(RNS.Reticulum.storagepath+"/known_destinations","rb") as file:
+                            storage_known_destinations = umsgpack.load(file)
+     
+                    except: pass
+
                 try:
-                    with open(RNS.Reticulum.storagepath+"/known_destinations","rb") as file:
-                        storage_known_destinations = umsgpack.load(file)
- 
-                except:
-                    pass
+                    for destination_hash in storage_known_destinations:
+                        if not destination_hash in Identity.known_destinations:
+                            with Identity.known_destinations_lock:
+                                Identity.known_destinations[destination_hash] = storage_known_destinations[destination_hash]
+                
+                except Exception as e:
+                    RNS.log("Skipped recombining known destinations from disk, since an error occurred: "+str(e), RNS.LOG_WARNING)
 
-            try:
-                for destination_hash in storage_known_destinations:
-                    if not destination_hash in Identity.known_destinations:
-                        Identity.known_destinations[destination_hash] = storage_known_destinations[destination_hash]
-            except Exception as e:
-                RNS.log("Skipped recombining known destinations from disk, since an error occurred: "+str(e), RNS.LOG_WARNING)
-
-            RNS.log("Saving "+str(len(Identity.known_destinations))+" known destinations to storage...", RNS.LOG_DEBUG)
+            RNS.log("Saving "+str(len(Identity.known_destinations))+" known destinations to storage...", RNS.LOG_VERBOSE)
             with open(RNS.Reticulum.storagepath+"/known_destinations","wb") as file:
-                umsgpack.dump(Identity.known_destinations, file)
-            
+                umsgpack.dump(Identity.known_destinations.copy(), file)
 
             save_time = time.time() - save_start
-            if save_time < 1:
-                time_str = str(round(save_time*1000,2))+"ms"
-            else:
-                time_str = str(round(save_time,2))+"s"
+            if save_time < 1: time_str = str(round(save_time*1000,2))+"ms"
+            else:             time_str = str(round(save_time,2))+"s"
 
-            RNS.log("Saved known destinations to storage in "+time_str, RNS.LOG_DEBUG)
+            RNS.log("Saved known destinations to storage in "+time_str, RNS.LOG_VERBOSE)
 
         except Exception as e:
             RNS.log("Error while saving known destinations to disk, the contained exception was: "+str(e), RNS.LOG_ERROR)
@@ -219,6 +229,7 @@ class Identity:
     @staticmethod
     def load_known_destinations():
         if os.path.isfile(RNS.Reticulum.storagepath+"/known_destinations"):
+            st = time.time()
             try:
                 with open(RNS.Reticulum.storagepath+"/known_destinations","rb") as file:
                     loaded_known_destinations = umsgpack.load(file)
@@ -226,15 +237,102 @@ class Identity:
                 Identity.known_destinations = {}
                 for known_destination in loaded_known_destinations:
                     if len(known_destination) == RNS.Reticulum.TRUNCATED_HASHLENGTH//8:
-                        Identity.known_destinations[known_destination] = loaded_known_destinations[known_destination]
+                        if len(loaded_known_destinations[known_destination]) < 5:
+                            e = loaded_known_destinations[known_destination]
+                            loaded_known_destinations[known_destination] = [e[0], e[1], e[2], e[3], 0]
 
-                RNS.log("Loaded "+str(len(Identity.known_destinations))+" known destination from storage", RNS.LOG_VERBOSE)
+                        with Identity.known_destinations_lock:
+                            Identity.known_destinations[known_destination] = loaded_known_destinations[known_destination]
+
+                RNS.log(f"Loaded {len(Identity.known_destinations)} known destination from storage in {RNS.prettyshorttime(time.time()-st)}", RNS.LOG_VERBOSE)
 
             except Exception as e:
                 RNS.log("Error loading known destinations from disk, file will be recreated on exit", RNS.LOG_ERROR)
+                RNS.trace_exception(e)
         else:
             RNS.log("Destinations file does not exist, no known destinations loaded", RNS.LOG_VERBOSE)
 
+    @staticmethod
+    def _used_destination_data(destination_hash):
+        with Identity.known_destinations_lock:
+            if destination_hash in Identity.known_destinations:
+                if not Identity.known_destinations[destination_hash][4] < 0:
+                    Identity.known_destinations[destination_hash][4] = time.time()
+                    return True
+
+        return False
+
+    @staticmethod
+    def _retain_destination_data(destination_hash):
+        with Identity.known_destinations_lock:
+            if destination_hash in Identity.known_destinations:
+                Identity.known_destinations[destination_hash][4] = -1
+                return True
+
+        return False
+
+    @staticmethod
+    def _unretain_destination_data(destination_hash):
+        with Identity.known_destinations_lock:
+            if destination_hash in Identity.known_destinations:
+                Identity.known_destinations[destination_hash][4] = time.time()
+                return True
+
+        return False
+    
+    @staticmethod
+    def clean_known_destinations():
+        now        = time.time()
+        st         = now
+        total      = len(Identity.known_destinations)
+        stale      = []
+        no_path    = 0
+        retained   = 0
+        never_used = 0
+        for destination_hash in Identity.known_destinations:
+            try:
+                if RNS.Transport.has_path(destination_hash): has_path = True
+                else:
+                    has_path = False
+                    no_path += 1
+
+                with Identity.known_destinations_lock:
+                    if destination_hash in Identity.known_destinations:
+                        last_announce =  Identity.known_destinations[destination_hash][0]
+                        last_use = 0
+                        was_used = False
+                        is_retained = False
+
+                        if Identity.known_destinations[destination_hash][4] > 0:
+                            was_used = True
+                            last_use = Identity.known_destinations[destination_hash][4]
+
+                        elif Identity.known_destinations[destination_hash][4] == 0:
+                            was_used = False
+                            never_used += 1
+
+                        elif Identity.known_destinations[destination_hash][4] == -1:
+                            is_retained = True
+                            retained += 1
+
+                        unused_for = time.time() - Identity.known_destinations[destination_hash][4]
+
+                        if not is_retained and not has_path:
+                            if not was_used and now - last_announce > RNS.Transport.UNUSED_DESTINATION_LINGER: stale.append(destination_hash)
+                            elif unused_for > RNS.Transport.DESTINATION_TIMEOUT*1.25:                          stale.append(destination_hash)
+
+            except Exception as e: RNS.log(f"Faulty entry for {RNS.prettyhexrep(destination_hash)} while cleaning known destinations: {e}", RNS.LOG_DEBUG)
+
+        removed = 0
+        for destination_hash in stale:
+            with Identity.known_destinations_lock:
+                if destination_hash in Identity.known_destinations:
+                    Identity.known_destinations.pop(destination_hash)
+                    removed += 1
+
+        # RNS.log(f"Total destinations: {total}, stale: {len(stale)}, removed: {removed}, no path: {no_path}, never used: {never_used}, with path: {total-no_path}, used: {total-never_used}, retained: {retained}. Completed in {RNS.prettyshorttime(time.time()-st)}", RNS.LOG_WARNING) # TODO: Remove
+        if not RNS.Transport.owner.is_connected_to_shared_instance: Identity.save_known_destinations(recombine=False)
+
     @staticmethod
     def full_hash(data):
         """
@@ -333,33 +431,40 @@ class Identity:
     def _clean_ratchets():
         RNS.log("Cleaning ratchets...", RNS.LOG_DEBUG)
         try:
+            count = 0
+            removed = 0
+            not_known = 0
             now = time.time()
             ratchetdir = RNS.Reticulum.storagepath+"/ratchets"
             if os.path.isdir(ratchetdir):
                 for filename in os.listdir(ratchetdir):
+                    count += 1
                     try:
                         expired = False
                         corrupted = False
                         with open(f"{ratchetdir}/{filename}", "rb") as rf:
-                            # TODO: Remove individual ratchet file if corrupt
                             try:
                                 ratchet_data = umsgpack.unpackb(rf.read())
-                                if now > ratchet_data["received"]+Identity.RATCHET_EXPIRY:
-                                    expired = True
+                                if now > ratchet_data["received"]+Identity.RATCHET_EXPIRY: expired = True
 
                             except Exception as e:
                                 RNS.log(f"Corrupted ratchet data while reading {ratchetdir}/{filename}, removing file", RNS.LOG_ERROR)
                                 corrupted = True
 
-                        if expired or corrupted:
+                        destination_hash = bytes.fromhex(filename)
+                        if not destination_hash in RNS.Identity.known_destinations: unknown = True; not_known += 1
+                        else:                                                       unknown = False
+
+                        if expired or corrupted or unknown:
                             os.unlink(f"{ratchetdir}/{filename}")
+                            removed += 1
 
                     except Exception as e:
                         RNS.log(f"An error occurred while cleaning ratchets, in the processing of {ratchetdir}/{filename}.", RNS.LOG_ERROR)
                         RNS.log(f"The contained exception was: {e}", RNS.LOG_ERROR)
 
-        except Exception as e:
-            RNS.log(f"An error occurred while cleaning ratchets. The contained exception was: {e}", RNS.LOG_ERROR)
+        except Exception as e: RNS.log(f"An error occurred while cleaning ratchets. The contained exception was: {e}", RNS.LOG_ERROR)
+        RNS.log(f"Processed {count} ratchets in {RNS.prettytime(time.time()-now)}, not in use {not_known}, removed {removed}", RNS.LOG_DEBUG)
 
     @staticmethod
     def get_ratchet(destination_hash):
@@ -430,6 +535,11 @@ class Identity:
                 announced_identity = Identity(create_keys=False)
                 announced_identity.load_public_key(public_key)
 
+                if len(RNS.Transport.blackholed_identities) > 0:
+                    if announced_identity.hash in RNS.Transport.blackholed_identities:
+                        RNS.log(f"Invalidated and dropped announce from blackholed identity {RNS.prettyhexrep(announced_identity.hash)}", RNS.LOG_EXTREME)
+                        return False
+
                 if announced_identity.pub != None and announced_identity.validate(signature, signed_data):
                     if only_validate_signature:
                         del announced_identity
@@ -488,9 +598,9 @@ class Identity:
             return False
 
     @staticmethod
-    def persist_data():
+    def persist_data(background=False):
         if not RNS.Transport.owner.is_connected_to_shared_instance:
-            Identity.save_known_destinations()
+            Identity.save_known_destinations(background=background)
 
     @staticmethod
     def exit_handler():

RNS/Interfaces/Android/RNodeInterface.py

@@ -500,6 +500,8 @@ class RNodeInterface(Interface):
         self.r_csma_cw_max        = None
         self.r_current_rssi       = None
         self.r_noise_floor        = None
+        self.r_interference       = None
+        self.r_interference_l     = None
         self.r_temperature        = None
 
         self.r_battery_state = RNodeInterface.BATTERY_STATE_UNKNOWN
@@ -1310,10 +1312,12 @@ class RNodeInterface(Interface):
                                     self.r_channel_load_long  = cul/100.0
                                     self.r_current_rssi       = crs-RNodeInterface.RSSI_OFFSET
                                     self.r_noise_floor        = nfl-RNodeInterface.RSSI_OFFSET
+                                    
                                     if ntf == 0xFF:
                                         self.r_interference   = None
                                     else:
                                         self.r_interference   = ntf-RNodeInterface.RSSI_OFFSET
+                                        self.r_interference_l = [time.time(), self.r_interference]
                                     
                                     if self.r_interference != None:
                                         RNS.log(f"{self} Radio detected interference at {self.r_interference} dBm", RNS.LOG_DEBUG)

RNS/Interfaces/AutoInterface.py

@@ -65,7 +65,7 @@ class AutoInterface(Interface):
 
     ALL_IGNORE_IFS     = ["lo0"]
     DARWIN_IGNORE_IFS  = ["awdl0", "llw0", "lo0", "en5"]
-    ANDROID_IGNORE_IFS = ["dummy0", "lo", "tun0"]
+    ANDROID_IGNORE_IFS = ["dummy0", "lo", "tun0", "rmnet0", "rmnet1", "rmnet2", "rmnet3", "rmnet4", "rmnet5", "rmnet6", "rmnet7"]
 
     BITRATE_GUESS      = 10*1000*1000
 
@@ -138,11 +138,12 @@ class AutoInterface(Interface):
 
         self.outbound_udp_socket = None
 
-        self.announce_rate_target = None
-        self.announce_interval = AutoInterface.ANNOUNCE_INTERVAL
-        self.peer_job_interval = AutoInterface.PEER_JOB_INTERVAL
-        self.peering_timeout   = AutoInterface.PEERING_TIMEOUT
-        self.multicast_echo_timeout = AutoInterface.MCAST_ECHO_TIMEOUT
+        self.announce_rate_target     = None
+        self.announce_interval        = AutoInterface.ANNOUNCE_INTERVAL
+        self.peer_job_interval        = AutoInterface.PEER_JOB_INTERVAL
+        self.peering_timeout          = AutoInterface.PEERING_TIMEOUT
+        self.multicast_echo_timeout   = AutoInterface.MCAST_ECHO_TIMEOUT
+        self.reverse_peering_interval = self.announce_interval*3.25
 
         # Increase peering timeout on Android, due to potential
         # low-power modes implemented on many chipsets.
@@ -169,6 +170,8 @@ class AutoInterface(Interface):
         else:
             self.discovery_port = discovery_port
 
+        self.unicast_discovery_port = self.discovery_port+1
+
         if multicast_address_type == None:
             self.multicast_address_type = AutoInterface.MULTICAST_TEMPORARY_ADDRESS_TYPE
         elif str(multicast_address_type).lower() == "temporary":
@@ -244,33 +247,48 @@ class AutoInterface(Interface):
                             if link_local_addr == None:
                                 RNS.log(str(self)+" No link-local IPv6 address configured for "+str(ifname)+", skipping interface", RNS.LOG_EXTREME)
                             else:
-                                mcast_addr = self.mcast_discovery_address
-                                RNS.log(str(self)+" Creating multicast discovery listener on "+str(ifname)+" with address "+str(mcast_addr), RNS.LOG_EXTREME)
+                                RNS.log(str(self)+" Creating unicast discovery listener on "+str(ifname)+" with address "+str(link_local_addr), RNS.LOG_EXTREME)
 
                                 # Struct with interface index
                                 if_struct = struct.pack("I", self.interface_name_to_index(ifname))
 
-                                # Set up multicast socket
+                                # Set up unicast discovery socket
+                                unicast_discovery_socket = socket.socket(socket.AF_INET6, socket.SOCK_DGRAM)
+                                unicast_discovery_socket.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+                                if hasattr(socket, "SO_REUSEPORT"): unicast_discovery_socket.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEPORT, 1)
+
+                                # Bind unicast discovery socket
+                                if RNS.vendor.platformutils.is_windows():
+                                    # Windows throws "[WinError 10049] The requested address is not valid in its context"
+                                    # when trying to use the multicast address as host, or when providing interface index
+                                    # passing an empty host appears to work, but probably not exactly how we want it to...
+                                    unicast_discovery_socket.bind(('', self.unicast_discovery_port))
+
+                                else:
+                                    addr_info = socket.getaddrinfo(link_local_addr+"%"+ifname, self.unicast_discovery_port, socket.AF_INET6, socket.SOCK_DGRAM)
+                                    unicast_discovery_socket.bind(addr_info[0][4])
+
+                                mcast_addr = self.mcast_discovery_address
+                                RNS.log(str(self)+" Creating multicast discovery listener on "+str(ifname)+" with address "+str(mcast_addr), RNS.LOG_EXTREME)
+
+                                # Set up multicast discovery socket
                                 discovery_socket = socket.socket(socket.AF_INET6, socket.SOCK_DGRAM)
                                 discovery_socket.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
-                                if hasattr(socket, "SO_REUSEPORT"):
-                                    discovery_socket.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEPORT, 1)
+                                if hasattr(socket, "SO_REUSEPORT"): discovery_socket.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEPORT, 1)
                                 discovery_socket.setsockopt(socket.IPPROTO_IPV6, socket.IPV6_MULTICAST_IF, if_struct)
 
                                 # Join multicast group
                                 mcast_group = socket.inet_pton(socket.AF_INET6, mcast_addr) + if_struct
                                 discovery_socket.setsockopt(socket.IPPROTO_IPV6, socket.IPV6_JOIN_GROUP, mcast_group)
 
-                                # Bind socket
+                                # Bind multicast socket
                                 if RNS.vendor.platformutils.is_windows():
-
-                                    # window throws "[WinError 10049] The requested address is not valid in its context"
+                                    # Windows throws "[WinError 10049] The requested address is not valid in its context"
                                     # when trying to use the multicast address as host, or when providing interface index
                                     # passing an empty host appears to work, but probably not exactly how we want it to...
                                     discovery_socket.bind(('', self.discovery_port))
 
                                 else:
-
                                     if self.discovery_scope == AutoInterface.SCOPE_LINK:
                                         addr_info = socket.getaddrinfo(mcast_addr+"%"+ifname, self.discovery_port, socket.AF_INET6, socket.SOCK_DGRAM)
                                     else:
@@ -278,12 +296,13 @@ class AutoInterface(Interface):
 
                                     discovery_socket.bind(addr_info[0][4])
 
-                                # Set up thread for discovery packets
+                                # Set up thread for multicast discovery packets
                                 def discovery_loop(): self.discovery_handler(discovery_socket, ifname)
-
-                                thread = threading.Thread(target=discovery_loop)
-                                thread.daemon = True
-                                thread.start()
+                                thread = threading.Thread(target=discovery_loop, daemon=True).start()
+                                
+                                # Set up thread for unicast discovery packets
+                                def unicast_discovery_loop(): self.discovery_handler(unicast_discovery_socket, ifname, announce=False)
+                                thread = threading.Thread(target=unicast_discovery_loop, daemon=True).start()
 
                                 suitable_interfaces += 1
 
@@ -331,13 +350,13 @@ class AutoInterface(Interface):
         self.online = True
         self.final_init_done = True
 
-    def discovery_handler(self, socket, ifname):
-        def announce_loop():
-            self.announce_handler(ifname)
-            
-        thread = threading.Thread(target=announce_loop)
-        thread.daemon = True
-        thread.start()
+    def discovery_handler(self, socket, ifname, announce=True):
+        def announce_loop(): self.announce_handler(ifname)
+        
+        if announce:
+            thread = threading.Thread(target=announce_loop)
+            thread.daemon = True
+            thread.start()
         
         while True:
             data, ipv6_src = socket.recvfrom(1024)
@@ -371,6 +390,18 @@ class AutoInterface(Interface):
                     spawned_interface.teardown()
                 RNS.log(str(self)+" removed peer "+str(peer_addr)+" on "+str(removed_peer[0]), RNS.LOG_DEBUG)
 
+            # Send reverse peering packets
+            for peer_addr in self.peers:
+                try:
+                    peer = self.peers[peer_addr]
+                    ifname = peer[0]
+                    last_outbound = peer[2]
+                    if now > last_outbound+self.reverse_peering_interval:
+                        self.reverse_announce(ifname, peer_addr)
+                        peer[2] = time.time()
+                except Exception as e:
+                    RNS.log(f"Error while sending reverse peering packet to {peer_addr}: {e}", RNS.LOG_ERROR)
+
             for ifname in self.adopted_interfaces:
                 # Check that the link-local address has not changed
                 try:
@@ -443,6 +474,20 @@ class AutoInterface(Interface):
             self.peer_announce(ifname)
             time.sleep(self.announce_interval)
             
+    def reverse_announce(self, ifname, peer_addr):
+        try:
+            link_local_address = self.adopted_interfaces[ifname]
+            discovery_token = RNS.Identity.full_hash(self.group_id+link_local_address.encode("utf-8"))
+            announce_socket = socket.socket(socket.AF_INET6, socket.SOCK_DGRAM)
+            addr_info = socket.getaddrinfo(f"{peer_addr}%{ifname}", self.unicast_discovery_port, socket.AF_INET6, socket.SOCK_DGRAM)
+
+            ifis = struct.pack("I", self.interface_name_to_index(ifname))
+            announce_socket.sendto(discovery_token, addr_info[0][4])
+            announce_socket.close()
+            
+        except Exception as e:
+            RNS.log(f"Could not send reverse peering packet to {peer_addr} on {ifname}: {e}", RNS.LOG_ERROR)
+
     def peer_announce(self, ifname):
         try:
             link_local_address = self.adopted_interfaces[ifname]
@@ -480,11 +525,21 @@ class AutoInterface(Interface):
 
         else:
             if not addr in self.peers:
-                self.peers[addr] = [ifname, time.time()]
+                self.peers[addr] = [ifname, time.time(), time.time()]
 
                 spawned_interface = AutoInterfacePeer(self, addr, ifname)
                 spawned_interface.OUT = self.OUT
                 spawned_interface.IN  = self.IN
+
+                spawned_interface.ingress_control = self.ingress_control
+                spawned_interface.ic_max_held_announces = self.ic_max_held_announces
+                spawned_interface.ic_burst_hold = self.ic_burst_hold
+                spawned_interface.ic_burst_freq = self.ic_burst_freq
+                spawned_interface.ic_burst_freq_new = self.ic_burst_freq_new
+                spawned_interface.ic_new_time = self.ic_new_time
+                spawned_interface.ic_burst_penalty = self.ic_burst_penalty
+                spawned_interface.ic_held_release_interval = self.ic_held_release_interval
+                
                 spawned_interface.parent_interface = self
                 spawned_interface.bitrate = self.bitrate
                 
@@ -518,7 +573,7 @@ class AutoInterface(Interface):
                 if addr in self.spawned_interfaces:
                     self.spawned_interfaces[addr].detach()
                     self.spawned_interfaces[addr].teardown()
-                    self.spawned_interfaces.pop(spawned_interface)
+                    if addr in self.spawned_interfaces: self.spawned_interfaces.pop(addr)
                 self.spawned_interfaces[addr] = spawned_interface
 
                 RNS.log(str(self)+" added peer "+str(addr)+" on "+str(ifname), RNS.LOG_DEBUG)
@@ -526,28 +581,18 @@ class AutoInterface(Interface):
                 self.refresh_peer(addr)
 
     def refresh_peer(self, addr):
-        try:
-            self.peers[addr][1] = time.time()
-        except Exception as e:
-            RNS.log(f"An error occurred while refreshing peer {addr} on {self}: {e}", RNS.LOG_ERROR)
+        try: self.peers[addr][1] = time.time()
+        except Exception as e: RNS.log(f"An error occurred while refreshing peer {addr} on {self}: {e}", RNS.LOG_ERROR)
 
     def process_incoming(self, data, addr=None):
         if self.online and addr in self.spawned_interfaces:
             self.spawned_interfaces[addr].process_incoming(data, addr)
 
-    def process_outgoing(self,data):
-        pass
+    def process_outgoing(self, data): pass
 
-    # Until per-device sub-interfacing is implemented,
-    # ingress limiting should be disabled on AutoInterface
-    def should_ingress_limit(self):
-        return False
+    def detach(self): self.online = False
 
-    def detach(self):
-        self.online = False
-
-    def __str__(self):
-        return "AutoInterface["+self.name+"]"
+    def __str__(self): return f"AutoInterface[{self.name}]"
 
 class AutoInterfacePeer(Interface):
 
@@ -602,12 +647,10 @@ class AutoInterfacePeer(Interface):
         
     def teardown(self):
         if not self.detached:
-            RNS.log("The interface "+str(self)+" experienced an unrecoverable error and is being torn down.", RNS.LOG_ERROR)
-            if RNS.Reticulum.panic_on_interface_error:
-                RNS.panic()
+            RNS.log(f"The interface {self} experienced an unrecoverable error and is being torn down.", RNS.LOG_ERROR)
+            if RNS.Reticulum.panic_on_interface_error: RNS.panic()
 
-        else:
-            RNS.log("The interface "+str(self)+" is being torn down.", RNS.LOG_VERBOSE)
+        else: RNS.log(f"The interface {self} is being torn down.", RNS.LOG_VERBOSE)
 
         self.online = False
         self.OUT = False
@@ -618,13 +661,7 @@ class AutoInterfacePeer(Interface):
             except Exception as e:
                 RNS.log(f"Could not remove {self} from parent interface on detach. The contained exception was: {e}", RNS.LOG_ERROR)
 
-        if self in RNS.Transport.interfaces:
-            RNS.Transport.interfaces.remove(self)
-
-    # Until per-device sub-interfacing is implemented,
-    # ingress limiting should be disabled on AutoInterface
-    def should_ingress_limit(self):
-        return False
+        if self in RNS.Transport.interfaces: RNS.Transport.interfaces.remove(self)
 
 class AutoInterfaceHandler(socketserver.BaseRequestHandler):
     def __init__(self, callback, *args, **keys):

RNS/Interfaces/BackboneInterface.py

@@ -127,6 +127,7 @@ class BackboneInterface(Interface):
         self.detached = False
         self.mode = RNS.Interfaces.Interface.Interface.MODE_FULL
         self.spawned_interfaces = []
+        self.supports_discovery = True
 
         if bindport == None:
             raise SystemError(f"No TCP port configured for interface \"{name}\"")
@@ -227,10 +228,10 @@ class BackboneInterface(Interface):
         if interface.socket:
             fileno = interface.socket.fileno()
             if fileno in BackboneInterface.spawned_interface_filenos:
-                try:
-                    BackboneInterface.epoll.modify(interface.socket.fileno(), select.EPOLLOUT)
+                try: BackboneInterface.epoll.modify(fileno, select.EPOLLOUT)
                 except Exception as e:
-                    RNS.trace_exception(e)
+                    RNS.log(f"Error occurred on {interface} while modifying socket EPOLL state: {e}", RNS.LOG_WARNING)
+                    raise e
 
     @staticmethod
     def __job():
@@ -269,8 +270,7 @@ class BackboneInterface(Interface):
                                         spawned_interface.receive(received_bytes)
                                 
                                 elif client_socket and fileno == client_socket.fileno() and (event & select.EPOLLOUT):
-                                    try:
-                                        written = client_socket.send(spawned_interface.transmit_buffer)
+                                    try: written = client_socket.send(spawned_interface.transmit_buffer)
                                     except Exception as e:
                                         written = 0
                                         if not spawned_interface.detached: RNS.log(f"Error while writing to {spawned_interface}: {e}", RNS.LOG_DEBUG)
@@ -292,7 +292,11 @@ class BackboneInterface(Interface):
                                         spawned_interface.receive(b"")
 
                                     spawned_interface.transmit_buffer = spawned_interface.transmit_buffer[written:]
-                                    if len(spawned_interface.transmit_buffer) == 0: BackboneInterface.epoll.modify(fileno, select.EPOLLIN)
+                                    try:
+                                        if len(spawned_interface.transmit_buffer) == 0: BackboneInterface.epoll.modify(fileno, select.EPOLLIN)
+                                    except Exception as e:
+                                        RNS.log(f"Error while setting EPOLLIN on {spawned_interface}: {e}", RNS.LOG_ERROR)
+
                                     spawned_interface.txb += written
                                     if spawned_interface.parent_interface: spawned_interface.parent_interface.txb += written
                                 
@@ -343,6 +347,16 @@ class BackboneInterface(Interface):
             spawned_interface = BackboneClientInterface(self.owner, spawned_configuration, connected_socket=socket)
             spawned_interface.OUT = self.OUT
             spawned_interface.IN  = self.IN
+
+            spawned_interface.ingress_control = self.ingress_control
+            spawned_interface.ic_max_held_announces = self.ic_max_held_announces
+            spawned_interface.ic_burst_hold = self.ic_burst_hold
+            spawned_interface.ic_burst_freq = self.ic_burst_freq
+            spawned_interface.ic_burst_freq_new = self.ic_burst_freq_new
+            spawned_interface.ic_new_time = self.ic_new_time
+            spawned_interface.ic_burst_penalty = self.ic_burst_penalty
+            spawned_interface.ic_held_release_interval = self.ic_held_release_interval
+            
             spawned_interface.socket = socket
             spawned_interface.target_ip = socket.getpeername()[0]
             spawned_interface.target_port = str(socket.getpeername()[1])
@@ -407,7 +421,9 @@ class BackboneInterface(Interface):
                 if hasattr(listener_socket, "shutdown"):
                     if callable(listener_socket.shutdown):
                         try: listener_socket.shutdown(socket.SHUT_RDWR)
-                        except Exception as e: RNS.log("Error while shutting down socket for "+str(self)+": "+str(e), RNS.LOG_ERROR)
+                        except Exception as e:
+                            if str(e).endswith("Transport endpoint is not connected"): pass
+                            else: RNS.log("Error while shutting down socket for "+str(self)+": "+str(e), RNS.LOG_ERROR)
 
     def __str__(self):
         if ":" in self.bind_ip:
@@ -522,7 +538,9 @@ class BackboneClientInterface(Interface):
                     
                     try:
                         if self.socket != None: self.socket.shutdown(socket.SHUT_RDWR)
-                    except Exception as e: RNS.log("Error while shutting down socket for "+str(self)+": "+str(e), RNS.LOG_ERROR)
+                    except Exception as e:
+                        if str(e).endswith("Transport endpoint is not connected"): pass
+                        else: RNS.log("Error while shutting down socket for "+str(self)+": "+str(e), RNS.LOG_ERROR)
 
                     try:
                         if self.socket != None: self.socket.close()
@@ -579,7 +597,7 @@ class BackboneClientInterface(Interface):
             if not self.reconnecting:
                 self.reconnecting = True
                 attempts = 0
-                while not self.online:
+                while not self.online and not self.detached:
                     time.sleep(BackboneClientInterface.RECONNECT_WAIT)
                     attempts += 1
 
@@ -592,6 +610,8 @@ class BackboneClientInterface(Interface):
                     except Exception as e:
                         RNS.log("Connection attempt for "+str(self)+" failed: "+str(e), RNS.LOG_DEBUG)
 
+                if not self.online: return
+
                 if not self.never_connected:
                     RNS.log("Reconnected socket for "+str(self)+".", RNS.LOG_INFO)
 

RNS/Interfaces/I2PInterface.py

@@ -880,6 +880,7 @@ class I2PInterface(Interface):
         self.ifac_size = ifac_size
         self.ifac_netname = ifac_netname
         self.ifac_netkey = ifac_netkey
+        self.supports_discovery = True
 
         self.online = False
 
@@ -947,6 +948,16 @@ class I2PInterface(Interface):
         spawned_interface = I2PInterfacePeer(self, self.owner, interface_name, connected_socket=handler.request)
         spawned_interface.OUT = True
         spawned_interface.IN  = True
+
+        spawned_interface.ingress_control = self.ingress_control
+        spawned_interface.ic_max_held_announces = self.ic_max_held_announces
+        spawned_interface.ic_burst_hold = self.ic_burst_hold
+        spawned_interface.ic_burst_freq = self.ic_burst_freq
+        spawned_interface.ic_burst_freq_new = self.ic_burst_freq_new
+        spawned_interface.ic_new_time = self.ic_new_time
+        spawned_interface.ic_burst_penalty = self.ic_burst_penalty
+        spawned_interface.ic_held_release_interval = self.ic_held_release_interval
+        
         spawned_interface.parent_interface = self
         spawned_interface.online = True
         spawned_interface.bitrate = self.bitrate

RNS/Interfaces/Interface.py

@@ -55,8 +55,8 @@ class Interface:
 
     # How many samples to use for announce
     # frequency calculations
-    IA_FREQ_SAMPLES     = 6
-    OA_FREQ_SAMPLES     = 6
+    IA_FREQ_SAMPLES     = 128
+    OA_FREQ_SAMPLES     = 128
 
     # Maximum amount of ingress limited announces
     # to hold at any given time.
@@ -66,11 +66,12 @@ class Interface:
     # considered to be newly created. Two
     # hours by default.
     IC_NEW_TIME              = 2*60*60
-    IC_BURST_FREQ_NEW        = 3.5
-    IC_BURST_FREQ            = 12
+    IC_BURST_FREQ_NEW        = 6
+    IC_BURST_FREQ            = 35
     IC_BURST_HOLD            = 1*60
-    IC_BURST_PENALTY         = 5*60
-    IC_HELD_RELEASE_INTERVAL = 30
+    IC_BURST_PENALTY         = 15
+    IC_HELD_RELEASE_INTERVAL = 2
+    IC_DEQUE_MIN_SAMPLE      = 32
 
     AUTOCONFIGURE_MTU = False
     FIXED_MTU         = False
@@ -84,10 +85,15 @@ class Interface:
         self.bitrate  = 62500
         self.HW_MTU   = None
 
+        self.supports_discovery = False
+        self.discoverable = False
+        self.last_discovery_announce = 0
+        self.bootstrap_only = False
         self.parent_interface = None
         self.spawned_interfaces = None
         self.tunnel_id = None
         self.ingress_control = True
+        self.phy_keepalive = False
         self.ic_max_held_announces = Interface.MAX_HELD_ANNOUNCES
         self.ic_burst_hold = Interface.IC_BURST_HOLD
         self.ic_burst_active = False
@@ -118,20 +124,19 @@ class Interface:
             if self.ic_burst_active:
                 if ia_freq < freq_threshold and time.time() > self.ic_burst_activated+self.ic_burst_hold:
                     self.ic_burst_active = False
-                    self.ic_held_release = time.time() + self.ic_burst_penalty
+
                 return True
 
             else:
                 if ia_freq > freq_threshold:
                     self.ic_burst_active = True
                     self.ic_burst_activated = time.time()
+                    self.ic_held_release = time.time() + self.ic_burst_penalty
                     return True
 
-                else:
-                    return False
+                else: return False
 
-        else:
-            return False
+        else: return False
 
     def optimise_mtu(self):
         if self.AUTOCONFIGURE_MTU:
@@ -171,7 +176,7 @@ class Interface:
 
     def process_held_announces(self):
         try:
-            if not self.should_ingress_limit() and len(self.held_announces) > 0 and time.time() > self.ic_held_release:
+            if len(self.held_announces) > 0 and time.time() > self.ic_held_release:
                 freq_threshold = self.ic_burst_freq_new if self.age() < self.ic_new_time else self.ic_burst_freq
                 ia_freq = self.incoming_announce_frequency()
                 if ia_freq < freq_threshold:
@@ -187,8 +192,7 @@ class Interface:
                         RNS.log("Releasing held announce packet "+str(selected_announce_packet)+" from "+str(self), RNS.LOG_EXTREME)
                         self.ic_held_release = time.time() + self.ic_held_release_interval
                         self.held_announces.pop(selected_announce_packet.destination_hash)
-                        def release():
-                            RNS.Transport.inbound(selected_announce_packet.raw, selected_announce_packet.receiving_interface)
+                        def release(): RNS.Transport.inbound(selected_announce_packet.raw, selected_announce_packet.receiving_interface)
                         threading.Thread(target=release, daemon=True).start()
         
         except Exception as e:
@@ -206,38 +210,24 @@ class Interface:
             self.parent_interface.sent_announce(from_spawned=True)
 
     def incoming_announce_frequency(self):
-        if not len(self.ia_freq_deque) > 1:
-            return 0
+        n = len(self.ia_freq_deque)
+        if not n > self.IC_DEQUE_MIN_SAMPLE: return 0
         else:
-            dq_len = len(self.ia_freq_deque)
-            delta_sum = 0
-            for i in range(1,dq_len):
-                delta_sum += self.ia_freq_deque[i]-self.ia_freq_deque[i-1]
-            delta_sum += time.time() - self.ia_freq_deque[dq_len-1]
-            
-            if delta_sum == 0:
-                avg = 0
-            else:
-                avg = 1/(delta_sum/(dq_len))
-
-            return avg
+            oldest = self.ia_freq_deque[0]
+            span = time.time() - oldest
+            if span <= 0: return 0
+            hz = n / span
+            return hz
 
     def outgoing_announce_frequency(self):
-        if not len(self.oa_freq_deque) > 1:
-            return 0
+        n = len(self.oa_freq_deque)
+        if not len(self.oa_freq_deque) > 1: return 0
         else:
-            dq_len = len(self.oa_freq_deque)
-            delta_sum = 0
-            for i in range(1,dq_len):
-                delta_sum += self.oa_freq_deque[i]-self.oa_freq_deque[i-1]
-            delta_sum += time.time() - self.oa_freq_deque[dq_len-1]
-            
-            if delta_sum == 0:
-                avg = 0
-            else:
-                avg = 1/(delta_sum/(dq_len))
-
-            return avg
+            oldest = self.oa_freq_deque[0]
+            span   = time.time() - oldest
+            if span <= 0: return 0
+            hz = n / span
+            return hz
 
     def process_announce_queue(self):
         if not hasattr(self, "announce_cap"):

RNS/Interfaces/LocalInterface.py

@@ -62,6 +62,7 @@ class ThreadingTCPServer(socketserver.ThreadingMixIn, socketserver.TCPServer):
 class LocalClientInterface(Interface):
     RECONNECT_WAIT = 8
     AUTOCONFIGURE_MTU = True
+    CLIENT_SLEEP_PAUSE_TIMEOUT = 12
 
     def __init__(self, owner, name, target_port = None, connected_socket=None, socket_path=None):
         super().__init__()
@@ -85,8 +86,9 @@ class LocalClientInterface(Interface):
         self.frame_buffer     = b""
         self.transmit_buffer  = b""
 
-        if RNS.vendor.platformutils.use_epoll():
-            self.epoll_backend = True
+        if RNS.vendor.platformutils.use_epoll(): self.epoll_backend = True
+
+        self.pause_on_client_sleep = False
 
         if connected_socket != None:
             self.receives    = True
@@ -99,6 +101,10 @@ class LocalClientInterface(Interface):
 
             self.is_connected_to_shared_instance = False
 
+            if RNS.vendor.platformutils.is_android():
+                self.pause_on_client_sleep = True
+                self.pause_timeout = time.time() + self.CLIENT_SLEEP_PAUSE_TIMEOUT
+
         elif self.socket_path != None:
             self.receives    = True
             self.target_ip   = None
@@ -145,6 +151,7 @@ class LocalClientInterface(Interface):
         self.is_connected_to_shared_instance = True
         self.never_connected = False
 
+        if RNS.vendor.platformutils.is_android(): self.phy_keepalive = True
         if self.epoll_backend: BackboneInterface.add_client_socket(self.socket, self)
 
         return True
@@ -185,17 +192,36 @@ class LocalClientInterface(Interface):
             raise IOError("Attempt to reconnect on a non-initiator local interface")
 
 
+    def send_keepalive(self):
+        if self.online:
+            RNS.log(f"Sending keepalive on {self}", RNS.LOG_DEBUG) # TODO: Remove
+            try:
+                if self.epoll_backend:
+                    self.transmit_buffer += bytes([HDLC.FLAG])+bytes([HDLC.FLAG])
+                    BackboneInterface.tx_ready(self)
+
+                else:
+                    self.writing = True
+                    data = bytes([HDLC.FLAG])+HDLC.escape(data)+bytes([HDLC.FLAG])
+                    self.socket.sendall(data)
+                    self.writing = False
+
+            except Exception as e: RNS.log(f"Exception occurred while sending keepalive on {self}: {e}", RNS.LOG_ERROR)
+
     def process_incoming(self, data):
         self.rxb += len(data)
         if self.parent_interface != None: self.parent_interface.rxb += len(data)
         
-        try:
-            self.owner.inbound(data, self)
+        try: self.owner.inbound(data, self)
         except Exception as e:
-            RNS.log(f"An error in the processing of an incoming frame for {self}: {e}", RNS.LOG_ERROR)
+            RNS.log(f"An error occurred in the processing of an incoming frame for {self}: {e}", RNS.LOG_ERROR)
             RNS.trace_exception(e)
 
     def process_outgoing(self, data):
+        if self.pause_on_client_sleep and time.time() > self.pause_timeout:
+            RNS.log(f"TX paused for LocalInterface client, dropping outbound packet", RNS.LOG_DEBUG) # TODO: Remove
+            return
+
         if self.online:
             try:
                 if self.epoll_backend:
@@ -238,13 +264,12 @@ class LocalClientInterface(Interface):
                     frame = self.frame_buffer[frame_start+1:frame_end]
                     frame = frame.replace(bytes([HDLC.ESC, HDLC.FLAG ^ HDLC.ESC_MASK]), bytes([HDLC.FLAG]))
                     frame = frame.replace(bytes([HDLC.ESC, HDLC.ESC  ^ HDLC.ESC_MASK]), bytes([HDLC.ESC]))
-                    if len(frame) > RNS.Reticulum.HEADER_MINSIZE:
-                        self.process_incoming(frame)
+                    if len(frame) > RNS.Reticulum.HEADER_MINSIZE: self.process_incoming(frame)
                     self.frame_buffer = self.frame_buffer[frame_end:]
-                else:
-                    flags_remaining = False
-            else:
-                flags_remaining = False
+                
+                else: flags_remaining = False
+            
+            else: flags_remaining = False
 
     def receive(self, data_in):
         try:
@@ -267,6 +292,8 @@ class LocalClientInterface(Interface):
             RNS.log("Tearing down "+str(self), RNS.LOG_ERROR)
             self.teardown()
 
+        if self.pause_on_client_sleep: self.pause_timeout = time.time() + self.CLIENT_SLEEP_PAUSE_TIMEOUT
+
     def read_loop(self):
         try:
             self.frame_buffer = b""
@@ -328,7 +355,8 @@ class LocalClientInterface(Interface):
             if hasattr(self, "parent_interface") and self.parent_interface != None:
                 self.parent_interface.clients -= 1
                 if hasattr(RNS.Transport, "owner") and RNS.Transport.owner != None:
-                    RNS.Transport.owner._should_persist_data()
+                    background = not self.detached
+                    RNS.Transport.owner._should_persist_data(background=background)
 
         if nowarning == False:
             RNS.log("The interface "+str(self)+" experienced an unrecoverable error and is being torn down. Restart Reticulum to attempt to open this interface again.", RNS.LOG_ERROR)

RNS/Interfaces/RNodeInterface.py

@@ -185,7 +185,7 @@ class RNodeInterface(Interface):
                 else:
                     ble_name = ble_string
 
-            if port.lower().startswith(tcp_uri_scheme):
+            elif port.lower().startswith(tcp_uri_scheme):
                 force_tcp = True
                 tcp_string = port[len(tcp_uri_scheme):]
                 port = None
@@ -276,6 +276,8 @@ class RNodeInterface(Interface):
         self.r_csma_cw_max        = None
         self.r_current_rssi       = None
         self.r_noise_floor        = None
+        self.r_interference       = None
+        self.r_interference_l     = None
 
         self.r_battery_state = RNodeInterface.BATTERY_STATE_UNKNOWN
         self.r_battery_percent = 0
@@ -294,6 +296,7 @@ class RNodeInterface(Interface):
         self.flow_control    = flow_control
         self.interface_ready = False
         self.announce_rate_target = None
+        self.supports_discovery = True
 
         if force_ble or self.ble_addr != None or self.ble_name != None: self.use_ble = True
         if force_tcp or self.tcp_host != None:                          self.use_tcp = True
@@ -943,16 +946,35 @@ class RNodeInterface(Interface):
                                     self.r_channel_load_long  = cul/100.0
                                     self.r_current_rssi       = crs-RNodeInterface.RSSI_OFFSET
                                     self.r_noise_floor        = nfl-RNodeInterface.RSSI_OFFSET
+
+                                    # TODO: Remove debug
+                                    # interference_log_threshold = 10
+                                    # if ntf == 0xFF:
+                                    #     self.r_interference   = None
+                                    #     if self.r_noise_floor != None:
+                                    #         # Filter potential false interference events due to LNA recalibration
+                                    #         if self.r_interference_l != None:
+                                    #             if self.r_interference_l[1] < self.r_noise_floor+interference_log_threshold:
+                                    #                 self.r_interference_l = None
+                                    # else:
+                                    #     if self.r_noise_floor != None:
+                                    #         interference   = ntf-RNodeInterface.RSSI_OFFSET
+                                    #         # Filter potential false interference events due to LNA recalibration
+                                    #         if interference > self.r_noise_floor+interference_log_threshold:
+                                    #             self.r_interference   = ntf-RNodeInterface.RSSI_OFFSET
+                                    #             self.r_interference_l = [time.time(), self.r_interference]
+
                                     if ntf == 0xFF:
                                         self.r_interference   = None
                                     else:
                                         self.r_interference   = ntf-RNodeInterface.RSSI_OFFSET
+                                        self.r_interference_l = [time.time(), self.r_interference]
                                     
                                     if self.r_interference != None:
                                         RNS.log(f"{self} Radio detected interference at {self.r_interference} dBm", RNS.LOG_DEBUG)
 
                                     # TODO: Remove debug
-                                    # RNS.log(f"RSSI: {self.r_current_rssi}, Noise floor: {self.r_noise_floor}, Interference: {self.r_interference}", RNS.LOG_EXTREME)
+                                    # RNS.log(f"RSSI: {self.r_current_rssi}, Noise floor: {self.r_noise_floor}, Interference: {self.r_interference}", RNS.LOG_DEBUG)
                         elif (command == KISS.CMD_STAT_PHYPRM):
                             if (byte == KISS.FESC):
                                 escape = True

RNS/Interfaces/TCPInterface.py

@@ -107,8 +107,13 @@ class TCPClientInterface(Interface):
         i2p_tunneled = c.as_bool("i2p_tunneled") if "i2p_tunneled" in c else False
         connect_timeout = c.as_int("connect_timeout") if "connect_timeout" in c else None
         max_reconnect_tries = c.as_int("max_reconnect_tries") if "max_reconnect_tries" in c else None
+        fixed_mtu = c.as_int("fixed_mtu") if "fixed_mtu" in c else None
+        if fixed_mtu:
+            if fixed_mtu < RNS.Reticulum.MTU: raise ValueError(f"Configured MTU of {fixed_mtu} bytes is too small")
+            self.AUTOCONFIGURE_MTU = False
+            self.FIXED_MTU = True
         
-        self.HW_MTU           = TCPInterface.HW_MTU
+        self.HW_MTU           = TCPInterface.HW_MTU if not fixed_mtu else fixed_mtu
         self.IN               = True
         self.OUT              = False
         self.socket           = None
@@ -126,10 +131,9 @@ class TCPClientInterface(Interface):
         self.mode             = RNS.Interfaces.Interface.Interface.MODE_FULL
         self.bitrate          = TCPClientInterface.BITRATE_GUESS
         
-        if max_reconnect_tries == None:
-            self.max_reconnect_tries = TCPClientInterface.RECONNECT_MAX_TRIES
-        else:
-            self.max_reconnect_tries = max_reconnect_tries
+        self.supports_discovery = True
+        if max_reconnect_tries == None: self.max_reconnect_tries = TCPClientInterface.RECONNECT_MAX_TRIES
+        else: self.max_reconnect_tries = max_reconnect_tries
 
         if connected_socket != None:
             self.receives    = True
@@ -508,6 +512,7 @@ class TCPServerInterface(Interface):
         if port != None:
             bindport = port
 
+        self.supports_discovery = True
         self.HW_MTU = TCPInterface.HW_MTU
 
         self.online = False
@@ -574,6 +579,16 @@ class TCPServerInterface(Interface):
         spawned_interface = TCPClientInterface(self.owner, spawned_configuration, connected_socket=handler.request)
         spawned_interface.OUT = self.OUT
         spawned_interface.IN  = self.IN
+        
+        spawned_interface.ingress_control = self.ingress_control
+        spawned_interface.ic_max_held_announces = self.ic_max_held_announces
+        spawned_interface.ic_burst_hold = self.ic_burst_hold
+        spawned_interface.ic_burst_freq = self.ic_burst_freq
+        spawned_interface.ic_burst_freq_new = self.ic_burst_freq_new
+        spawned_interface.ic_new_time = self.ic_new_time
+        spawned_interface.ic_burst_penalty = self.ic_burst_penalty
+        spawned_interface.ic_held_release_interval = self.ic_held_release_interval
+
         spawned_interface.target_ip = handler.client_address[0]
         spawned_interface.target_port = str(handler.client_address[1])
         spawned_interface.parent_interface = self

RNS/Interfaces/WeaveInterface.py

@@ -99,6 +99,12 @@ class WDCL():
         if not RNS.vendor.platformutils.is_android():
             if port == None: raise ValueError("No port specified")
         
+        self.supports_discovery   = True
+        self.discovery_frequency  = None
+        self.discovery_bandwidth  = None
+        self.discovery_channel    = None
+        self.discovery_modulation = None
+
         self.switch_identity = owner.switch_identity
         self.switch_id = self.switch_identity.sig_pub_bytes[-4:]
         self.switch_pub_bytes = self.switch_identity.sig_pub_bytes
@@ -936,6 +942,16 @@ class WeaveInterface(Interface):
             spawned_interface = WeaveInterfacePeer(self, endpoint_addr)
             spawned_interface.OUT = self.OUT
             spawned_interface.IN  = self.IN
+
+            spawned_interface.ingress_control = self.ingress_control
+            spawned_interface.ic_max_held_announces = self.ic_max_held_announces
+            spawned_interface.ic_burst_hold = self.ic_burst_hold
+            spawned_interface.ic_burst_freq = self.ic_burst_freq
+            spawned_interface.ic_burst_freq_new = self.ic_burst_freq_new
+            spawned_interface.ic_new_time = self.ic_new_time
+            spawned_interface.ic_burst_penalty = self.ic_burst_penalty
+            spawned_interface.ic_held_release_interval = self.ic_held_release_interval
+            
             spawned_interface.parent_interface = self
             spawned_interface.bitrate = self.bitrate
             
@@ -991,9 +1007,6 @@ class WeaveInterface(Interface):
     def process_outgoing(self,data):
         pass
 
-    def should_ingress_limit(self):
-        return False
-
     def detach(self):
         self._online = False
 
@@ -1086,6 +1099,3 @@ class WeaveInterfacePeer(Interface):
 
         if self in RNS.Transport.interfaces:
             RNS.Transport.interfaces.remove(self)
-
-    def should_ingress_limit(self):
-        return False

RNS/Link.py

@@ -722,12 +722,9 @@ class Link:
             pass
 
     def link_closed(self):
-        for resource in self.incoming_resources:
-            resource.cancel()
-        for resource in self.outgoing_resources:
-            resource.cancel()
-        if self._channel:
-            self._channel._shutdown()
+        for resource in self.incoming_resources: resource.cancel()
+        for resource in self.outgoing_resources: resource.cancel()
+        if self._channel: self._channel._shutdown()
             
         self.prv = None
         self.pub = None
@@ -741,8 +738,7 @@ class Link:
                     self.destination.links.remove(self)
 
         if self.callbacks.link_closed != None:
-            try:
-                self.callbacks.link_closed(self)
+            try: self.callbacks.link_closed(self)
             except Exception as e:
                 RNS.log("Error while executing link closed callback from "+str(self)+". The contained exception was: "+str(e), RNS.LOG_ERROR)
 
@@ -935,7 +931,8 @@ class Link:
             request_id        = RNS.Identity.truncated_hash(packed_request)
             request_data      = unpacked_request
 
-            self.handle_request(request_id, request_data)
+            def job(): self.handle_request(request_id, request_data)
+            threading.Thread(target=job, daemon=True).start()
         else:
             RNS.log("Incoming request resource failed with status: "+RNS.hexrep([resource.status]), RNS.LOG_DEBUG)
 
@@ -1036,7 +1033,8 @@ class Link:
                             packed_request = self.decrypt(packet.data)
                             if packed_request != None:
                                 unpacked_request = umsgpack.unpackb(packed_request)
-                                self.handle_request(request_id, unpacked_request)
+                                def job(): self.handle_request(request_id, unpacked_request)
+                                threading.Thread(target=job, daemon=True).start()
                                 self.__update_phy_stats(packet, query_shared=True)
                         except Exception as e:
                             RNS.log("Error occurred while handling request. The contained exception was: "+str(e), RNS.LOG_ERROR)
@@ -1049,7 +1047,8 @@ class Link:
                                 request_id = unpacked_response[0]
                                 response_data = unpacked_response[1]
                                 transfer_size = len(umsgpack.packb(response_data))-2
-                                self.handle_response(request_id, response_data, transfer_size, transfer_size)
+                                def job(): self.handle_response(request_id, response_data, transfer_size, transfer_size)
+                                threading.Thread(target=job, daemon=True).start()
                                 self.__update_phy_stats(packet, query_shared=True)
                         except Exception as e:
                             RNS.log("Error occurred while handling response. The contained exception was: "+str(e), RNS.LOG_ERROR)
@@ -1085,17 +1084,14 @@ class Link:
                                                 pending_request.started_at = time.time()
                                             pending_request.response_resource_progress(response_resource)
 
-                            elif self.resource_strategy == Link.ACCEPT_NONE:
-                                pass
+                            elif self.resource_strategy == Link.ACCEPT_NONE: pass
                             elif self.resource_strategy == Link.ACCEPT_APP:
                                 if self.callbacks.resource != None:
                                     try:
                                         resource_advertisement = RNS.ResourceAdvertisement.unpack(packet.plaintext)
                                         resource_advertisement.link = self
-                                        if self.callbacks.resource(resource_advertisement):
-                                            RNS.Resource.accept(packet, self.callbacks.resource_concluded)
-                                        else:
-                                            RNS.Resource.reject(packet)
+                                        if self.callbacks.resource(resource_advertisement): RNS.Resource.accept(packet, self.callbacks.resource_concluded)
+                                        else:                                               RNS.Resource.reject(packet)
                                     except Exception as e:
                                         RNS.log("Error while executing resource accept callback from "+str(self)+". The contained exception was: "+str(e), RNS.LOG_ERROR)
                             elif self.resource_strategy == Link.ACCEPT_ALL:
@@ -1181,7 +1177,8 @@ class Link:
                         resource_hash = packet.data[0:RNS.Identity.HASHLENGTH//8]
                         for resource in self.outgoing_resources:
                             if resource_hash == resource.hash:
-                                resource.validate_proof(packet.data)
+                                def job(resource=resource): resource.validate_proof(packet.data)
+                                threading.Thread(target=job, daemon=True).start()
                                 self.__update_phy_stats(packet, query_shared=True)
 
         self.watchdog_lock = False
@@ -1299,10 +1296,8 @@ class Link:
         :param resource_strategy: One of ``RNS.Link.ACCEPT_NONE``, ``RNS.Link.ACCEPT_ALL`` or ``RNS.Link.ACCEPT_APP``. If ``RNS.Link.ACCEPT_APP`` is set, the `resource_callback` will be called to determine whether the resource should be accepted or not.
         :raises: *TypeError* if the resource strategy is unsupported.
         """
-        if not resource_strategy in Link.resource_strategies:
-            raise TypeError("Unsupported resource strategy")
-        else:
-            self.resource_strategy = resource_strategy
+        if not resource_strategy in Link.resource_strategies: raise TypeError("Unsupported resource strategy")
+        else: self.resource_strategy = resource_strategy
 
     def register_outgoing_resource(self, resource):
         self.outgoing_resources.append(resource)
@@ -1312,8 +1307,7 @@ class Link:
 
     def has_incoming_resource(self, resource):
         for incoming_resource in self.incoming_resources:
-            if incoming_resource.hash == resource.hash:
-                return True
+            if incoming_resource.hash == resource.hash: return True
 
         return False
 
@@ -1324,25 +1318,18 @@ class Link:
         return self.last_resource_eifr
 
     def cancel_outgoing_resource(self, resource):
-        if resource in self.outgoing_resources:
-            self.outgoing_resources.remove(resource)
-        else:
-            RNS.log("Attempt to cancel a non-existing outgoing resource", RNS.LOG_ERROR)
+        if resource in self.outgoing_resources: self.outgoing_resources.remove(resource)
+        else: RNS.log("Attempt to cancel a non-existing outgoing resource", RNS.LOG_WARNING)
 
     def cancel_incoming_resource(self, resource):
-        if resource in self.incoming_resources:
-            self.incoming_resources.remove(resource)
-        else:
-            RNS.log("Attempt to cancel a non-existing incoming resource", RNS.LOG_ERROR)
+        if resource in self.incoming_resources: self.incoming_resources.remove(resource)
+        else: RNS.log("Attempt to cancel a non-existing incoming resource", RNS.LOG_WARNING)
 
     def ready_for_new_resource(self):
-        if len(self.outgoing_resources) > 0:
-            return False
-        else:
-            return True
+        if len(self.outgoing_resources) > 0: return False
+        else:                                return True
 
-    def __str__(self):
-        return RNS.prettyhexrep(self.link_id)
+    def __str__(self): return RNS.prettyhexrep(self.link_id)
 
 
 class RequestReceipt():
@@ -1427,20 +1414,21 @@ class RequestReceipt():
             now = time.time()
             if now > self.__resource_response_timeout:
                 self.request_timed_out(None)
+                break
 
             time.sleep(0.1)
 
 
     def request_timed_out(self, packet_receipt):
-        self.status = RequestReceipt.FAILED
-        self.concluded_at = time.time()
-        self.link.pending_requests.remove(self)
+        if self in self.link.pending_requests and self.status == RequestReceipt.DELIVERED:
+            self.status = RequestReceipt.FAILED
+            self.concluded_at = time.time()
+            self.link.pending_requests.remove(self)
 
-        if self.callbacks.failed != None:
-            try:
-                self.callbacks.failed(self)
-            except Exception as e:
-                RNS.log("Error while executing request timed out callback from "+str(self)+". The contained exception was: "+str(e), RNS.LOG_ERROR)
+            if self.callbacks.failed != None:
+                try: self.callbacks.failed(self)
+                except Exception as e:
+                    RNS.log("Error while executing request timed out callback from "+str(self)+". The contained exception was: "+str(e), RNS.LOG_ERROR)
 
 
     def response_resource_progress(self, resource):
@@ -1482,14 +1470,12 @@ class RequestReceipt():
                     self.packet_receipt.callbacks.delivery(self.packet_receipt)
 
             if self.callbacks.progress != None:
-                try:
-                    self.callbacks.progress(self)
+                try: self.callbacks.progress(self)
                 except Exception as e:
                     RNS.log("Error while executing response progress callback from "+str(self)+". The contained exception was: "+str(e), RNS.LOG_ERROR)
 
             if self.callbacks.response != None:
-                try:
-                    self.callbacks.response(self)
+                try: self.callbacks.response(self)
                 except Exception as e:
                     RNS.log("Error while executing response received callback from "+str(self)+". The contained exception was: "+str(e), RNS.LOG_ERROR)
 

RNS/Packet.py

@@ -289,13 +289,11 @@ class Packet:
                     self.destination.tx += 1
                     self.destination.txbytes += len(self.data)
 
-            if not self.packed:
-                self.pack()
+            if not self.packed: self.pack()
 
-            if RNS.Transport.outbound(self):
-                return self.receipt
+            if RNS.Transport.outbound(self): return self.receipt
             else:
-                RNS.log("No interfaces could process the outbound packet", RNS.LOG_ERROR)
+                RNS.log("No interfaces could process the outbound packet", RNS.LOG_DEBUG)
                 self.sent = False
                 self.receipt = None
                 return False
@@ -317,7 +315,7 @@ class Packet:
             if RNS.Transport.outbound(self):
                 return self.receipt
             else:
-                RNS.log("No interfaces could process the outbound packet", RNS.LOG_ERROR)
+                RNS.log("Re-send failed. No interfaces could process the outbound packet", RNS.LOG_WARNING)
                 self.sent = False
                 self.receipt = None
                 return False

RNS/Resource.py

@@ -126,6 +126,7 @@ class Resource:
     PART_TIMEOUT_FACTOR           = 4
     PART_TIMEOUT_FACTOR_AFTER_RTT = 2
     PROOF_TIMEOUT_FACTOR          = 3
+    HMU_WAIT_FACTOR               = 3.5
     MAX_RETRIES                   = 16
     MAX_ADV_RETRIES               = 4
     SENDER_GRACE_TIME             = 10.0
@@ -193,6 +194,7 @@ class Resource:
             resource.window_flexibility   = Resource.WINDOW_FLEXIBILITY
             resource.last_activity        = time.time()
             resource.started_transferring = resource.last_activity
+            resource.advertisement_packet = advertisement_packet
 
             resource.storagepath          = RNS.Reticulum.resourcepath+"/"+resource.original_hash.hex()
             resource.meta_storagepath     = resource.storagepath+".meta"
@@ -359,6 +361,7 @@ class Resource:
         self.request_id = request_id
         self.started_transferring = None
         self.is_response = is_response
+        self.max_decompressed_size = Resource.AUTO_COMPRESS_MAX_SIZE
         self.auto_compress_limit = Resource.AUTO_COMPRESS_MAX_SIZE
         self.auto_compress_option = auto_compress
 
@@ -594,15 +597,16 @@ class Resource:
                     extra_wait = retries_used * Resource.PER_RETRY_DELAY
 
                     self.update_eifr()
+                    expected_hmu_wait_remaining = (self.sdu*8*self.HMU_WAIT_FACTOR)/self.eifr if self.waiting_for_hmu or self.outstanding_parts == 0 else 0
                     expected_tof_remaining = (self.outstanding_parts*self.sdu*8)/self.eifr
 
                     if self.req_resp_rtt_rate != 0:
-                        sleep_time = self.last_activity + self.part_timeout_factor*expected_tof_remaining + Resource.RETRY_GRACE_TIME + extra_wait - time.time()
+                        sleep_time = self.last_activity + self.part_timeout_factor*expected_tof_remaining + expected_hmu_wait_remaining + Resource.RETRY_GRACE_TIME + extra_wait - time.time()
                     else:
                         sleep_time = self.last_activity + self.part_timeout_factor*((3*self.sdu)/self.eifr) + Resource.RETRY_GRACE_TIME + extra_wait - time.time()
                     
                     # TODO: Remove debug at some point
-                    # RNS.log(f"EIFR {RNS.prettyspeed(self.eifr)}, ETOF {RNS.prettyshorttime(expected_tof_remaining)} ", RNS.LOG_DEBUG, pt=True)
+                    # RNS.log(f"EIFR {RNS.prettyspeed(self.eifr)}, ETOF {RNS.prettyshorttime(expected_tof_remaining)}, EHWR {RNS.prettyshorttime(expected_hmu_wait_remaining)}", RNS.LOG_DEBUG, pt=True)
                     # RNS.log(f"Resource ST {RNS.prettyshorttime(sleep_time)}, RTT {RNS.prettyshorttime(self.rtt or self.link.rtt)}, {self.outstanding_parts} left", RNS.LOG_DEBUG, pt=True)
                     
                     if sleep_time < 0:
@@ -677,8 +681,15 @@ class Resource:
                 # Strip off random hash
                 data = data[Resource.RANDOM_HASH_SIZE:]
 
-                if self.compressed: self.data = bz2.decompress(data)
-                else: self.data = data
+                if not self.compressed: self.data = data
+                else:
+                    decompressor = bz2.BZ2Decompressor()
+                    self.data = decompressor.decompress(data, max_length=self.max_decompressed_size)
+                    if not decompressor.eof:
+                        self.status = Resource.CORRUPT
+                        self.cancel()
+                        RNS.log(f"Decompressed resource exceeded maximum decompressed size. The resource was rejected.", RNS.LOG_ERROR)
+                        return
 
                 calculated_hash = RNS.Identity.full_hash(self.data+self.random_hash)
                 if calculated_hash == self.hash:
@@ -755,18 +766,18 @@ class Resource:
         # Prepare the next segment for advertisement
         RNS.log(f"Preparing segment {self.segment_index+1} of {self.total_segments} for resource {self}", RNS.LOG_DEBUG)
         self.preparing_next_segment = True
-        self.next_segment = Resource(
-            self.input_file, self.link,
-            callback = self.callback,
-            segment_index = self.segment_index+1,
-            original_hash=self.original_hash,
-            progress_callback = self.__progress_callback,
-            request_id = self.request_id,
-            is_response = self.is_response,
-            advertise = False,
-            auto_compress = self.auto_compress_option,
-            sent_metadata_size = self.metadata_size,
-        )
+        self.next_segment = Resource(self.input_file, self.link,
+                                     callback = self.callback,
+                                     segment_index = self.segment_index+1,
+                                     original_hash=self.original_hash,
+                                     progress_callback = self.__progress_callback,
+                                     request_id = self.request_id,
+                                     is_response = self.is_response,
+                                     advertise = False,
+                                     auto_compress = self.auto_compress_option,
+                                     sent_metadata_size = self.metadata_size)
+        if self.__progress_callback:
+            self.next_segment.progress_callback(self.__progress_callback)
 
     def validate_proof(self, proof_data):
         if not self.status == Resource.FAILED:
@@ -882,7 +893,7 @@ class Resource:
 
                 if self.received_count == self.total_parts and not self.assembly_lock:
                     self.assembly_lock = True
-                    self.assemble()
+                    threading.Thread(target=self.assemble, daemon=True).start()
                 elif self.outstanding_parts == 0:
                     # TODO: Figure out if there is a mathematically
                     # optimal way to adjust windows
@@ -959,6 +970,7 @@ class Resource:
                     self.last_activity = time.time()
                     self.req_sent = self.last_activity
                     self.req_sent_bytes = len(request_packet.raw)
+                    self.rtt_rxd_bytes_at_part_req = self.rtt_rxd_bytes
                     self.req_resp = None
 
                 except Exception as e:
@@ -1056,8 +1068,7 @@ class Resource:
                 self.retries_left = 3
 
             if self.__progress_callback != None:
-                try:
-                    self.__progress_callback(self)
+                try: self.__progress_callback(self)
                 except Exception as e:
                     RNS.log("Error while executing progress callback from "+str(self)+". The contained exception was: "+str(e), RNS.LOG_ERROR)
 
@@ -1065,7 +1076,14 @@ class Resource:
         """
         Cancels transferring the resource.
         """
-        if self.status < Resource.COMPLETE:
+        if self.next_segment: self.next_segment.cancel()
+
+        if self.status == Resource.CORRUPT:
+            self.link.cancel_incoming_resource(self)
+            self.reject(self.advertisement_packet)
+            self.link.teardown()
+
+        elif self.status < Resource.COMPLETE:
             self.status = Resource.FAILED
             if self.initiator:
                 if self.link.status == RNS.Link.ACTIVE:
@@ -1093,7 +1111,8 @@ class Resource:
                 if self.callback != None:
                     try:
                         self.link.resource_concluded(self)
-                        self.callback(self)
+                        def job(): self.callback(self)
+                        threading.Thread(target=job, daemon=True).start()
                     except Exception as e:
                         RNS.log("Error while executing callbacks on resource reject from "+str(self)+". The contained exception was: "+str(e), RNS.LOG_ERROR)
 
@@ -1102,6 +1121,7 @@ class Resource:
 
     def progress_callback(self, callback):
         self.__progress_callback = callback
+        if self.next_segment: self.next_segment.progress_callback(callback)
 
     def get_progress(self):
         """

RNS/Utilities/rncp.py

@@ -49,17 +49,34 @@ fetch_jail = None
 save_path = None
 show_phy_rates = False
 allowed_identity_hashes = []
+identity = None
+
+def prepare_identity(identity_path):
+    global identity
+    if identity_path == None:
+        identity_path = RNS.Reticulum.identitypath+"/"+APP_NAME
+
+    if os.path.isfile(identity_path):
+        identity = RNS.Identity.from_file(identity_path)
+        if identity == None:
+            RNS.log(f"Could not load identity for rncp. The identity file at \"{identity_path}\" may be corrupt or unreadable.", RNS.LOG_ERROR)
+            RNS.exit(2)
+
+    if identity == None:
+        RNS.log("No valid saved identity found, creating new...", RNS.LOG_INFO)
+        identity = RNS.Identity()
+        identity.to_file(identity_path)
 
 REQ_FETCH_NOT_ALLOWED = 0xF0
 
 es = " "
 erase_str = "\33[2K\r"
 
-def listen(configdir, verbosity = 0, quietness = 0, allowed = [], display_identity = False,
+def listen(configdir, identitypath = None, verbosity = 0, quietness = 0, allowed = [], display_identity = False,
            limit = None, disable_auth = None, fetch_allowed = False, no_compress=False,
            jail = None, save = None, announce = False, allow_overwrite=False):
 
-    global allow_all, allow_fetch, allowed_identity_hashes, fetch_jail, save_path
+    global allow_all, allow_fetch, allowed_identity_hashes, fetch_jail, save_path, identity
     global fetch_auto_compress, allow_overwrite_on_receive
 
     allow_fetch = fetch_allowed
@@ -90,14 +107,7 @@ def listen(configdir, verbosity = 0, quietness = 0, allowed = [], display_identi
 
         RNS.log("Saving received files in \""+save_path+"\"", RNS.LOG_VERBOSE)
 
-    identity_path = RNS.Reticulum.identitypath+"/"+APP_NAME
-    if os.path.isfile(identity_path):
-        identity = RNS.Identity.from_file(identity_path)                
-
-    if identity == None:
-        RNS.log("No valid saved identity found, creating new...", RNS.LOG_INFO)
-        identity = RNS.Identity()
-        identity.to_file(identity_path)
+    prepare_identity(identitypath)
 
     destination = RNS.Destination(identity, RNS.Destination.IN, RNS.Destination.SINGLE, APP_NAME, "receive")
 
@@ -345,8 +355,8 @@ def sender_progress(resource):
         resource_done = True
 
 link = None
-def fetch(configdir, verbosity = 0, quietness = 0, destination = None, file = None, timeout = RNS.Transport.PATH_REQUEST_TIMEOUT, silent=False, phy_rates=False, save=None, allow_overwrite=False):
-    global current_resource, resource_done, link, speed, show_phy_rates, save_path, allow_overwrite_on_receive
+def fetch(configdir, identitypath = None, verbosity = 0, quietness = 0, destination = None, file = None, timeout = RNS.Transport.PATH_REQUEST_TIMEOUT, silent=False, phy_rates=False, save=None, allow_overwrite=False):
+    global current_resource, resource_done, link, speed, show_phy_rates, save_path, allow_overwrite_on_receive, identity
     targetloglevel = 3+verbosity-quietness
     show_phy_rates = phy_rates
     allow_overwrite_on_receive = allow_overwrite
@@ -377,19 +387,8 @@ def fetch(configdir, verbosity = 0, quietness = 0, destination = None, file = No
 
     reticulum = RNS.Reticulum(configdir=configdir, loglevel=targetloglevel)
 
-    identity_path = RNS.Reticulum.identitypath+"/"+APP_NAME
-    if os.path.isfile(identity_path):
-        identity = RNS.Identity.from_file(identity_path)
-        if identity == None:
-            RNS.log("Could not load identity for rncp. The identity file at \""+str(identity_path)+"\" may be corrupt or unreadable.", RNS.LOG_ERROR)
-            RNS.exit(2)
-    else:
-        identity = None
-
     if identity == None:
-        RNS.log("No valid saved identity found, creating new...", RNS.LOG_INFO)
-        identity = RNS.Identity()
-        identity.to_file(identity_path)
+        prepare_identity(identitypath)
 
     if not RNS.Transport.has_path(destination_hash):
         RNS.Transport.request_path(destination_hash)
@@ -614,8 +613,8 @@ def fetch(configdir, verbosity = 0, quietness = 0, destination = None, file = No
     RNS.exit(0)
 
 
-def send(configdir, verbosity = 0, quietness = 0, destination = None, file = None, timeout = RNS.Transport.PATH_REQUEST_TIMEOUT, silent=False, phy_rates=False, no_compress=False):
-    global current_resource, resource_done, link, speed, show_phy_rates, phy_got_total, phy_speed
+def send(configdir, identitypath = None, verbosity = 0, quietness = 0, destination = None, file = None, timeout = RNS.Transport.PATH_REQUEST_TIMEOUT, silent=False, phy_rates=False, no_compress=False):
+    global current_resource, resource_done, link, speed, show_phy_rates, phy_got_total, phy_speed, identity
     targetloglevel = 3+verbosity-quietness
     show_phy_rates = phy_rates
 
@@ -643,19 +642,8 @@ def send(configdir, verbosity = 0, quietness = 0, destination = None, file = Non
 
     reticulum = RNS.Reticulum(configdir=configdir, loglevel=targetloglevel)
 
-    identity_path = RNS.Reticulum.identitypath+"/"+APP_NAME
-    if os.path.isfile(identity_path):
-        identity = RNS.Identity.from_file(identity_path)
-        if identity == None:
-            RNS.log("Could not load identity for rncp. The identity file at \""+str(identity_path)+"\" may be corrupt or unreadable.", RNS.LOG_ERROR)
-            RNS.exit(2)
-    else:
-        identity = None
-
     if identity == None:
-        RNS.log("No valid saved identity found, creating new...", RNS.LOG_INFO)
-        identity = RNS.Identity()
-        identity.to_file(identity_path)
+        prepare_identity(identitypath)
 
     if not RNS.Transport.has_path(destination_hash):
         RNS.Transport.request_path(destination_hash)
@@ -822,6 +810,7 @@ def main():
         parser.add_argument('-a', metavar="allowed_hash", dest="allowed", action='append', help="allow this identity (or add in ~/.rncp/allowed_identities)", type=str)
         parser.add_argument('-n', '--no-auth', action='store_true', default=False, help="accept requests from anyone")
         parser.add_argument('-p', '--print-identity', action='store_true', default=False, help="print identity and destination info and exit")
+        parser.add_argument('-i', metavar="identity", action='store', dest="identity", default=None, help="path to identity to use", type=str)
         parser.add_argument("-w", action="store", metavar="seconds", type=float, help="sender timeout before giving up", default=RNS.Transport.PATH_REQUEST_TIMEOUT)
         parser.add_argument('-P', '--phy-rates', action='store_true', default=False, help="display physical layer transfer rates")
         # parser.add_argument("--limit", action="store", metavar="files", type=float, help="maximum number of files to accept", default=None)
@@ -832,6 +821,7 @@ def main():
         if args.listen or args.print_identity:
             listen(
                 configdir = args.config,
+                identitypath = args.identity,
                 verbosity=args.verbose,
                 quietness=args.quiet,
                 allowed = args.allowed,
@@ -850,6 +840,7 @@ def main():
             if args.destination != None and args.file != None:
                 fetch(
                     configdir = args.config,
+                    identitypath = args.identity,
                     verbosity = args.verbose,
                     quietness = args.quiet,
                     destination = args.destination,
@@ -868,6 +859,7 @@ def main():
         elif args.destination != None and args.file != None:
             send(
                 configdir = args.config,
+                identitypath = args.identity,
                 verbosity = args.verbose,
                 quietness = args.quiet,
                 destination = args.destination,

RNS/Utilities/rngit/__init__.py

@@ -0,0 +1,39 @@
+# Reticulum License
+#
+# Copyright (c) 2016-2026 Mark Qvist
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# - The Software shall not be used in any kind of system which includes amongst
+#   its functions the ability to purposefully do harm to human beings.
+#
+# - The Software shall not be used, directly or indirectly, in the creation of
+#   an artificial intelligence, machine learning or language model training
+#   dataset, including but not limited to any use that contributes to the
+#   training or development of such a model or algorithm.
+#
+# - The above copyright notice and this permission notice shall be included in
+#   all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+APP_NAME = "git"
+
+import os
+import glob
+
+py_modules  = glob.glob(os.path.dirname(__file__)+"/*.py")
+pyc_modules = glob.glob(os.path.dirname(__file__)+"/*.pyc")
+modules     = py_modules+pyc_modules
+__all__ = list(set([os.path.basename(f).replace(".pyc", "").replace(".py", "") for f in modules if not (f.endswith("__init__.py") or f.endswith("__init__.pyc"))]))

RNS/Utilities/rngit/client.py

@@ -0,0 +1,674 @@
+#!/usr/bin/env python3
+
+# Reticulum License
+#
+# Copyright (c) 2016-2026 Mark Qvist
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# - The Software shall not be used in any kind of system which includes amongst
+#   its functions the ability to purposefully do harm to human beings.
+#
+# - The Software shall not be used, directly or indirectly, in the creation of
+#   an artificial intelligence, machine learning or language model training
+#   dataset, including but not limited to any use that contributes to the
+#   training or development of such a model or algorithm.
+#
+# - The above copyright notice and this permission notice shall be included in
+#   all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+import RNS
+import os
+import sys
+import time
+import shutil
+import threading
+import subprocess
+
+from RNS._version import __version__
+from RNS.Utilities.rngit import APP_NAME
+
+from RNS.vendor.configobj import ConfigObj
+from tempfile import TemporaryDirectory
+
+def program_setup(configdir, rnsconfigdir, destination_hexhash, group_name, repo_name):
+    git_client = ReticulumGitClient(configdir=configdir, rnsconfigdir=rnsconfigdir, destination_hexhash=destination_hexhash,
+                                    group_name=group_name, repo_name=repo_name)
+
+    if not git_client.ready: sys.exit(1)
+    else:                    git_client.run()
+
+def main():
+    if len(sys.argv) < 3:
+        print("Usage: git-remote-rns <remote-name> <url>", file=sys.stderr)
+        sys.exit(1)
+    
+    url = sys.argv[2]
+    if not url.startswith("rns://"):
+        print("Invalid URL scheme. Must be rns://", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        parts = url[6:].split("/", 2)
+        destination_hexhash = parts[0]
+        group_name = parts[1]
+        repo_name = parts[2]
+    
+    except IndexError: print("Invalid URL format. Use rns://<hash>/<group>/<repo>", file=sys.stderr); sys.exit(1)
+
+    configdir    = os.environ.get("RNGIT_CONFIG", None)
+    rnsconfigdir = os.environ.get("RNS_CONFIG", None)
+
+    program_setup(configdir, rnsconfigdir, destination_hexhash, group_name, repo_name)
+    exit(0)
+
+
+class ReticulumGitClient():
+    PATH_LIST       = "/git/list"
+    PATH_FETCH      = "/git/fetch"
+    PATH_PUSH       = "/git/push"
+    PATH_DELETE     = "/git/delete"
+
+    RES_DISALLOWED  = 0x01
+    RES_INVALID_REQ = 0x02
+    RES_NOT_FOUND   = 0x03
+    RES_REMOTE_FAIL = 0xFF
+
+    IDX_REPOSITORY  = 0x00
+    IDX_RESULT_CODE = 0x01
+
+    REF_BATCH_SIZE  = 25
+    PATH_TIMEOUT    = 15
+    LINK_TIMEOUT    = 15
+
+    def __init__(self, configdir, rnsconfigdir, destination_hexhash, group_name, repo_name):
+        # Client state and configuration
+        self.identity            = None
+        self.userdir             = os.path.expanduser("~")
+        self.config              = None
+        self.ready               = False
+        
+        self.remote_identity     = None
+        self.destination         = None
+        self.link                = None
+        self.link_ready          = False
+        self.link_failed         = False
+        self.link_timeout        = self.LINK_TIMEOUT
+        self.path_timeout        = self.PATH_TIMEOUT
+
+        self.destination_hexhash = destination_hexhash
+        self.group_name          = group_name
+        self.repo_name           = repo_name
+        self.repo_path           = f"{group_name}/{repo_name}"
+
+        self.tmp_dir             = TemporaryDirectory()
+        self.request_event       = threading.Event()
+        self.request_response    = None
+        self.response_metadata   = None
+
+        self.ref_batch_size      = self.REF_BATCH_SIZE
+        self.remote_refs         = {}
+
+        self.response_progress      = 0
+        self.previous_progress      = 0
+        self.response_size          = None
+        self.response_transfer_size = None
+        self.progress_updated_at    = None
+        self.progress_enabled       = False
+
+        if configdir != None: self.configdir = configdir
+        else:
+            if os.path.isdir(self.userdir+"/.config/rngit") and os.path.isfile(self.userdir+"/.config/rngit/config"): self.configdir = self.userdir+"/.rngit/reticulum"
+            else: self.configdir = self.userdir+"/.rngit"
+        
+        self.logfile = self.configdir+"/client_log"
+        self.configpath = self.configdir+"/client_config"
+        self.identitypath = self.configdir+"/client_identity"
+
+        RNS.logfile = self.logfile
+        try: self.reticulum = RNS.Reticulum(configdir=rnsconfigdir, logdest=RNS.LOG_FILE)
+        except Exception as e:
+            print(f"Failed to initialize Reticulum: {e}", file=sys.stderr)
+            return
+
+        if os.path.isfile(self.configpath):
+            try: self.config = ConfigObj(self.configpath)
+            except Exception as e:
+                RNS.log("Could not parse the configuration at "+self.configpath, RNS.LOG_ERROR)
+                return
+        
+        else: self.__create_default_config()
+
+        self.__apply_config()
+        self.ready = True
+
+    def __create_default_config(self):
+        self.config = ConfigObj(__default_rngit_config__)
+        self.config.filename = self.configpath
+        if not os.path.isdir(self.configdir): os.makedirs(self.configdir)
+        self.config.write()
+
+    def __apply_config(self):
+        if "logging" in self.config:
+            section = self.config["logging"]
+            if "loglevel" in section: RNS.loglevel = max(RNS.LOG_NONE, min(RNS.LOG_EXTREME, section.as_int("loglevel")))
+        
+        if "client" in self.config:
+            section = self.config["client"]
+            if "ref_batch_size" in section: self.ref_batch_size = max(0, min(1024, section.as_int("ref_batch_size")))
+
+        if not os.path.isfile(self.identitypath):
+            identity = RNS.Identity()
+            identity.to_file(self.identitypath)
+            RNS.log(f"Client identity generated and persisted to {self.identitypath}", RNS.LOG_VERBOSE)
+        
+        else:
+            identity = RNS.Identity.from_file(self.identitypath)
+            RNS.log(f"Client identity loaded from {self.identitypath}", RNS.LOG_VERBOSE)
+
+        if not identity:
+            RNS.log("Could not initialize client identity.", RNS.LOG_ERROR)
+            self.ready = False
+        
+        else: self.identity = identity
+
+    def abort(self, reason=None, code=255):
+        if not reason: reason = "Unknown reason"
+        print(f"git-remote-rns failed: {reason}", file=sys.stderr)
+        if self.link: self.link.teardown()
+        sys.exit(code)
+
+    def connect_server(self):
+        try: destination_hash = bytes.fromhex(self.destination_hexhash)
+        except Exception as e: self.abort(f"Invalid destination hash: {e}")
+
+        RNS.log(f"Requesting path to {RNS.prettyhexrep(destination_hash)}", RNS.LOG_DEBUG)
+        sys.stderr.write(f"Requesting path..."); sys.stderr.flush()
+        if not RNS.Transport.await_path(destination_hash, timeout=self.path_timeout):
+            sys.stderr.write(f"\n"); sys.stderr.flush()
+            self.abort(f"Could not resolve path to {RNS.prettyhexrep(destination_hash)}")
+        
+        else:
+            RNS.log(f"Path to {RNS.prettyhexrep(destination_hash)} resolved", RNS.LOG_DEBUG);
+            sys.stderr.write(f"\rPath resolved     "); sys.stderr.flush()
+
+        self.remote_identity = RNS.Identity.recall(destination_hash)
+        if not self.remote_identity: self.abort("Could not recall remote identity. Is the server announcing?")
+
+        sys.stderr.write(f"\rEstablishing link..."); sys.stderr.flush()
+        self.destination = RNS.Destination(self.remote_identity, RNS.Destination.OUT, RNS.Destination.SINGLE, APP_NAME, "repositories")
+        self.link = RNS.Link(self.destination)
+        self.link.set_link_established_callback(self.link_established)
+        self.link.set_link_closed_callback(self.link_closed)
+
+    def link_established(self, link):
+        RNS.log(f"Link established, identifying...", RNS.LOG_DEBUG)
+        sys.stderr.write(f"\rLink established with remote\n"); sys.stderr.flush()
+        link.identify(self.identity)
+        self.link_ready = True
+
+    def link_closed(self, link):
+        RNS.log(f"Link was closed", RNS.LOG_DEBUG)
+        if not self.link_ready: self.link_failed = True
+
+    def _on_progress(self, transfer_instance):
+        if hasattr(transfer_instance, "progress"):
+            self.response_progress      = transfer_instance.progress
+            self.response_size          = transfer_instance.response_size
+            self.response_transfer_size = transfer_instance.response_transfer_size
+        
+        elif hasattr(transfer_instance, "get_progress") and callable(transfer_instance.get_progress):
+            self.response_progress      = transfer_instance.get_progress()
+            self.response_size          = transfer_instance.total_size
+            self.response_transfer_size = transfer_instance.size
+        
+        now = time.time()
+        if self.progress_updated_at == None: self.progress_updated_at = now
+
+        if now > self.progress_updated_at+1:
+            td = now - self.progress_updated_at
+            pd = self.response_progress - self.previous_progress
+            bd = pd*self.response_size if self.response_size else 0
+            self.response_speed = (bd/td)*8 if td > 0 else 0
+            self.previous_progress = self.response_progress
+            self.progress_updated_at = now
+            
+            # Report progress to git via stderr
+            if self.progress_enabled and self.response_size:
+                percent = round(self.response_progress * 100, 1)
+                size = self.response_size
+                rxd = size*self.response_progress
+                speed_kbps = (self.response_speed / 1000) if hasattr(self, 'response_speed') else 0
+                sys.stderr.write(f"Transferring: {percent}% ({RNS.prettysize(rxd)}/{RNS.prettysize(size)}) {RNS.prettyspeed(self.response_speed)}          \r")
+                sys.stderr.flush()
+
+    ################################
+    # Synchronous Request Wrappers #
+    ################################
+
+    def _response_ready(self, request_receipt):
+        self.request_response = request_receipt.response
+        self.response_metadata = request_receipt.metadata
+
+        if hasattr(self.request_response, "read") and callable(self.request_response.read):
+            response_path = self.request_response.name
+            base_name = os.path.basename(response_path)
+            retained_path = os.path.join(self.tmp_dir.name, base_name)
+            shutil.move(response_path, retained_path)
+            self.request_response = open(retained_path, "rb")
+
+        self.request_event.set()
+
+    def _response_failed(self, request_receipt=None):
+        self.request_response = None
+        self.request_event.set()
+
+    def send_request(self, path, data, timeout=7200):
+        if not self.link_ready: self.abort("Link not ready for request")
+        
+        self.request_event.clear()
+        self.request_response  = None
+        self.response_metadata = None
+        self.previous_progress = 0
+        self.progress_updated_at = None
+        
+        RNS.log(f"Sending request: {path}", RNS.LOG_DEBUG)
+        request_receipt = self.link.request(path, data, progress_callback=self._on_progress, response_callback=self._response_ready, failed_callback=self._response_failed, timeout=timeout)
+        if request_receipt.resource: request_receipt.resource.progress_callback(self._on_progress)
+        self.request_event.wait(timeout=timeout)
+        
+        if self.request_response is None: self.abort("Request failed or timed out")
+        RNS.log(f"Got response for: {path}", RNS.LOG_DEBUG)
+        
+        return self.request_response, self.response_metadata
+
+    #############################
+    # Git Helper Protocol Logic #
+    #############################
+
+    def _detach_stdout(self):
+        sys.stdout = open(os.devnull, "w")
+        sys.stderr = open(os.devnull, "w")
+
+    def run(self):
+        try: self.connect_server()
+        except Exception as e: self.abort(str(e))
+
+        timeout = self.link_timeout
+        while not self.link_ready and not self.link_failed and timeout > 0:
+            time.sleep(0.5)
+            timeout -= 1
+
+        if not self.link_ready: self.abort("Failed to establish link")
+
+        self.progress_enabled = False
+
+        git_stdin  = sys.stdin
+        git_stdout = sys.stdout
+        git_stderr = sys.stderr
+
+        fetch_queue = []
+        push_queue  = []
+
+        while True:
+            line = git_stdin.readline()
+            if not line: break
+
+            line = line.strip()
+            if line == "capabilities":
+                git_stdout.write("list\n")
+                git_stdout.write("fetch\n")
+                git_stdout.write("push\n")
+                git_stdout.write("option\n")
+                git_stdout.write("\n")
+                git_stdout.flush()
+
+            elif line == "list": self.handle_git_list(git_stdout)
+
+            elif line.startswith("list "): self.handle_git_list(git_stdout, for_push=True) # List for push
+
+            elif line.startswith("option"):
+                # Line format: option <name> <value>
+                parts = line.split(maxsplit=2)
+                opt_name = parts[1] if len(parts) > 1 else ""
+                opt_value = parts[2] if len(parts) > 2 else ""
+                
+                if opt_name == "progress": self.progress_enabled = opt_value.lower() in ("true", "1", "yes"); git_stdout.write("ok\n")
+                else: git_stdout.write("unsupported\n")
+                
+                git_stdout.flush()
+
+            elif line.startswith("fetch"):
+                # Line format: fetch <sha> <ref>
+                parts = line.split()
+                sha = parts[1]
+                ref = parts[2]
+                # Avoid duplicates in the same batch - TODO: Re-evaluate this
+                if (sha, ref) not in fetch_queue: fetch_queue.append((sha, ref))
+                push_queue = []
+
+            elif line.startswith("push"):
+                # Line format: push <local_ref>:<remote_ref>
+                parts = line.split()
+                refspec = parts[1]
+                local_ref, remote_ref = refspec.split(":", 1)
+                push_queue.append((local_ref, remote_ref))
+                fetch_queue = []
+
+            elif line == "": # End of batch
+                try:
+                    self.process_fetch_queue(fetch_queue, git_stdout, self.progress_enabled, self.ref_batch_size)
+                    self.process_push_queue(push_queue, git_stdout, git_stderr, self.progress_enabled)
+                    fetch_queue = []
+                    push_queue = []
+                    git_stdout.write("\n")
+                    git_stdout.flush()
+                
+                except BrokenPipeError:
+                    self._detach_stdout()
+                    RNS.log("Git closed connection, exiting", RNS.LOG_DEBUG)
+                    break
+
+            else: self.abort(f"Unknown Git command: {line}")
+
+        try: sys.stdout.flush()
+        except BrokenPipeError: pass
+
+        if self.link: self.link.teardown()
+
+    def handle_git_list(self, git_stdout, for_push=False):
+        RNS.log("Handle git list" + (" for-push" if for_push else ""), RNS.LOG_DEBUG)
+        request_data = {self.IDX_REPOSITORY: self.repo_path, "for_push": for_push}
+        response, metadata = self.send_request(self.PATH_LIST, request_data)
+
+        if not response or not isinstance(response, bytes): self.abort("Invalid list response from server")
+
+        status_byte = response[0]
+        payload = response[1:]
+
+        if status_byte != 0: self.abort(f"Server refused list: {payload.decode('utf-8', errors='ignore')}")
+
+        response_text = payload.decode("utf-8")
+
+        self.remote_refs = {}
+        for line in response_text.split("\n"):
+            line = line.strip()
+            if not line: continue
+            parts = line.split(" ", 1)
+            if len(parts) == 2:
+                sha, ref_name = parts
+                if ref_name == "HEAD": continue
+                self.remote_refs[ref_name] = sha
+
+        git_stdout.write(response_text)
+        git_stdout.write("\n") # Required to terminate list
+        git_stdout.flush()
+
+    def escape_for_stdout(self, value):
+        if isinstance(value, bytes): value = value.decode('utf-8', errors='replace')
+
+        escaped = '"'
+        for char in value:
+            if   char == '\\': escaped += '\\\\'
+            elif char == '"': escaped += '\\"'
+            elif char == '\n': escaped += '\\n'
+            elif char == '\t': escaped += '\\t'
+            elif char == '\r': escaped += '\\r'
+            elif ord(char) < 32 or ord(char) > 126: escaped += f'\\x{ord(char):02x}'
+            else: escaped += char
+        
+        return escaped + '"'
+
+    def process_fetch_queue(self, fetch_queue, git_stdout, progress_enabled=False, ref_batch_size=REF_BATCH_SIZE):
+        import tempfile
+        import subprocess
+
+        if not fetch_queue: return
+
+        # Build a global have list from all remote refs that the client already has objects for
+        have_shas = []
+        for sha in self.remote_refs.values():
+            try:
+                result = subprocess.run(["git", "cat-file", "-t", sha], capture_output=True, check=False)
+                if result.returncode == 0: have_shas.append(sha)
+            
+            except Exception as e: RNS.log(f"Could not verify remote SHA {sha} locally: {e}", RNS.LOG_WARNING)
+
+        while fetch_queue:
+            batch = fetch_queue[:ref_batch_size]
+            fetch_queue = fetch_queue[ref_batch_size:]
+
+            refs_list = []
+            for sha, ref in batch:
+                ref_entry = {"sha": sha, "ref": ref}
+                try:
+                    # Attempt to get local ref SHA for incremental bundle generation on remote
+                    result = subprocess.run(["git", "rev-parse", ref], capture_output=True, text=True, check=False)
+                    if result.returncode == 0:
+                        local_sha = result.stdout.strip()
+                        if local_sha != sha: ref_entry["have"] = local_sha
+
+                except Exception as e:
+                    RNS.log(f"Could not resolve local SHA for {ref} during fetch enumeration, getting full history for this ref: {e}", RNS.LOG_WARNING)
+
+                refs_list.append(ref_entry)
+
+            ref_names = [ref for _, ref in batch]
+            RNS.log(f"Fetching batch of {len(refs_list)} refs: {ref_names} (have {len(have_shas)} common objects)", RNS.LOG_DEBUG)
+
+            request_data = { self.IDX_REPOSITORY: self.repo_path, "refs": refs_list }
+            if have_shas: request_data["have"] = have_shas
+
+            response, metadata = self.send_request(self.PATH_FETCH, request_data)
+
+            if not response: self.abort(f"No data in fetch response for batch")
+            if not metadata:
+                if not isinstance(response, bytes): self.abort(f"Invalid fetch response for batch")
+                status_byte = response[0]
+
+                if status_byte == 0:
+                    RNS.log(f"Server returned empty bundle, all objects already exist locally", RNS.LOG_DEBUG)
+                    continue
+
+                else:
+                    error_msg = response[1:].decode('utf-8', errors='ignore')
+                    self.abort(f"Fetch failed for batch: {error_msg}")
+
+            else:
+                if not self.IDX_RESULT_CODE in metadata: self.abort(f"No result metadata on bundle response")
+                status_byte = metadata[self.IDX_RESULT_CODE]
+                if status_byte == 0: bundle_path = response.name
+                else: self.abort(f"Unknown remote state for batch ref fetch")
+
+                if progress_enabled:
+                    size = os.stat(bundle_path).st_size
+                    sys.stderr.write(f"Transferring: 100% ({RNS.prettysize(size)}).                       \n")
+                    sys.stderr.flush()
+
+                stderr_arg = sys.stderr if progress_enabled else subprocess.DEVNULL
+
+                verify_cmd = ["git", "bundle", "verify", "-q", bundle_path]
+                verify_result = subprocess.run(verify_cmd, stderr=subprocess.DEVNULL, stdout=subprocess.DEVNULL)
+
+                if verify_result.returncode != 0: self.abort(f"Bundle verification failed for batch")
+
+                unbundle_cmd = ["git", "bundle", "unbundle"]
+                if progress_enabled: unbundle_cmd.append("--progress")
+                unbundle_cmd.append(bundle_path)
+
+                unbundle_result = subprocess.run(unbundle_cmd, stderr=stderr_arg, stdout=subprocess.DEVNULL)
+
+                if unbundle_result.returncode != 0: self.abort(f"Bundle unbundle failed for batch: Non-zero return code")
+
+    def process_push_queue(self, push_queue, git_stdout, git_stderr, progress_enabled=False):
+        import tempfile
+        import subprocess
+
+        for local_ref, remote_ref in push_queue:
+            RNS.log(f"Pushing {local_ref} to {remote_ref}", RNS.LOG_DEBUG)
+
+            # Handle potential deletions
+            if not local_ref or local_ref == "":
+                request_data = { self.IDX_REPOSITORY: self.repo_path, "ref": remote_ref }
+                response, metadata = self.send_request(self.PATH_DELETE, request_data)
+
+                if not response or not isinstance(response, bytes):
+                    git_stdout.write(f"error {remote_ref} {self.escape_for_stdout('No response from server')}\n")
+                    git_stdout.flush()
+                    continue
+
+                status_byte = response[0]
+                if status_byte != 0:
+                    error_msg = response[1:].decode("utf-8", errors="ignore")
+                    git_stdout.write(f"error {remote_ref} {self.escape_for_stdout(error_msg)}\n")
+                    git_stdout.flush()
+                    continue
+
+                git_stdout.write(f"ok {remote_ref}\n")
+                git_stdout.flush()
+                continue
+
+            force = local_ref.startswith("+")
+            if force: local_ref = local_ref[1:]
+
+            stderr_arg = sys.stderr if progress_enabled else subprocess.DEVNULL
+
+            # Resolve the SHA that local_ref points to
+            sha_result = subprocess.run(["git", "rev-parse", local_ref], capture_output=True, text=True, check=False)
+            if sha_result.returncode != 0:
+                error_msg = f"Could not resolve local ref {local_ref}"
+                git_stdout.write(f"error {remote_ref} {self.escape_for_stdout(error_msg)}\n")
+                git_stdout.flush()
+                continue
+
+            local_sha = sha_result.stdout.strip()
+
+            bundle_empty = False
+            with tempfile.TemporaryDirectory() as tmpdir:
+                bundle_path = tmpdir + "/push.bundle"
+
+                create_cmd = ["git", "bundle", "create", bundle_path, local_ref]
+
+                # Exclude all remote ref SHAs that exist locally, so the
+                # bundle only contains objects the remote doesn't already have
+                exclude_count = 0
+                for sha in self.remote_refs.values():
+                    try:
+                        # We need to verify each SHA actually exists locally, since git
+                        # bundle create will fail if a ^<sha> argument references an object
+                        # not present in the local repository.
+                        result = subprocess.run(["git", "cat-file", "-t", sha], capture_output=True, check=False)
+                        if result.returncode == 0:
+                            create_cmd.append(f"^{sha}")
+                            exclude_count += 1
+                    
+                    except Exception as e: RNS.log(f"Could not verify remote SHA {sha} locally: {e}", RNS.LOG_WARNING)
+
+                RNS.log(f"Excluding {exclude_count}/{len(self.remote_refs)} remote refs for {local_ref}", RNS.LOG_DEBUG)
+
+                if progress_enabled: create_cmd.insert(3, "--progress")
+
+                create_result = subprocess.run(create_cmd, capture_output=True, text=True, check=False)
+
+                if create_result.returncode == 0:
+                    if create_result.stderr:
+                        # git_stderr.write(create_result.stderr)
+                        pass
+                else:
+                    if "empty bundle" in create_result.stderr.lower():
+                        # All objects reachable from local_ref already exist on
+                        # the remote. In this case, no bundle is needed and we can
+                        # update the ref directly via the operations path instead.
+                        bundle_empty = True
+                        RNS.log(f"Empty bundle for {local_ref}, all objects already on remote", RNS.LOG_DEBUG)
+
+                    else:
+                        if progress_enabled and create_result.stderr: git_stderr.write(create_result.stderr)
+                        error_msg = "Bundle creation failed"
+                        git_stdout.write(f"error {remote_ref} {self.escape_for_stdout(error_msg)}\n")
+                        git_stdout.flush()
+                        continue
+
+                if not bundle_empty:
+                    with open(bundle_path, "rb") as f: bundle_data = f.read()
+
+                    request_data = { self.IDX_REPOSITORY: self.repo_path, "local_ref": local_ref, "remote_ref": remote_ref,
+                                     "force": force, "bundle": bundle_data }
+                    
+                    response, metadata = self.send_request(self.PATH_PUSH, request_data)
+
+                    if not response or not isinstance(response, bytes):
+                        git_stdout.write(f"error {remote_ref} {self.escape_for_stdout('No response from server')}\n")
+                        git_stdout.flush()
+                        continue
+
+                    status_byte = response[0]
+                    if status_byte != 0:
+                        error_msg = response[1:].decode('utf-8', errors='ignore')
+                        git_stdout.write(f"error {remote_ref} {self.escape_for_stdout(error_msg)}\n")
+                        git_stdout.flush()
+                        continue
+
+            # When all reachable objects already exist on the remote, send a
+            # direct ref update operation instead of a bundle.
+            if bundle_empty:
+                operation    = {"action": "update_ref", "ref": remote_ref, "sha": local_sha, "force": force}
+                request_data = { self.IDX_REPOSITORY: self.repo_path,
+                                 "operations": [operation] }
+
+                response, metadata = self.send_request(self.PATH_PUSH, request_data)
+
+                if not response or not isinstance(response, bytes):
+                    git_stdout.write(f"error {remote_ref} {self.escape_for_stdout('No response from server')}\n")
+                    git_stdout.flush()
+                    continue
+
+                status_byte = response[0]
+                if status_byte != 0:
+                    error_msg = response[1:].decode('utf-8', errors='ignore')
+                    git_stdout.write(f"error {remote_ref} {self.escape_for_stdout(error_msg)}\n")
+                    git_stdout.flush()
+                    continue
+
+            git_stdout.write(f"ok {remote_ref}\n")
+            git_stdout.flush()
+
+
+__default_rngit_config__ = '''# This is the default rngit client config file.
+
+[client]
+
+# You can control the batch size of ref transfers
+# using the ref_batch_size directive:
+
+ref_batch_size = 25
+
+[logging]
+# Valid log levels are 0 through 7:
+#   0: Log only critical information
+#   1: Log errors and lower log levels
+#   2: Log warnings and lower log levels
+#   3: Log notices and lower log levels
+#   4: Log info and lower (this is the default)
+#   5: Verbose logging
+#   6: Debug logging
+#   7: Extreme logging
+
+loglevel = 4
+
+'''.splitlines()
+
+if __name__ == "__main__": main()

RNS/Utilities/rngit/highlight.py

@@ -0,0 +1,389 @@
+# Reticulum License
+#
+# Copyright (c) 2016-2026 Mark Qvist
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# - The Software shall not be used in any kind of system which includes amongst
+#   its functions the ability to purposefully do harm to human beings.
+#
+# - The Software shall not be used, directly or indirectly, in the creation of
+#   an artificial intelligence, machine learning or language model training
+#   dataset, including but not limited to any use that contributes to the
+#   training or development of such a model or algorithm.
+#
+# - The above copyright notice and this permission notice shall be included in
+#   all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+import os
+import io
+import RNS
+
+class SyntaxHighlighter:
+    
+    def __init__(self, theme=None):
+        self.pygments_available = False
+        self.pygments = None
+        self._lexer_cache = {}
+        self._check_pygments()
+        self.theme = theme or self._get_default_theme()
+    
+    def _get_default_theme(self):
+        return {
+            # Control flow - warm coral-red
+            "keyword": "ff7b72",
+            "keyword_constant": "ff7b72",
+            "keyword_control": "ff7b72",
+            "keyword_declaration": "ff7b72",
+            
+            # Function definitions - bright sky blue
+            "function_def": "79c0ff",
+            "function_magic": "ff7b72",
+            
+            # Function calls - soft lavender
+            "function_call": "d2a8ff",
+            "function_builtin": "ffa657",    # amber
+            
+            # Class definitions - fresh mint green
+            "class_def": "7ee787",
+            "class_ref": "56d364",           # muted when referenced
+            
+            # Instance context - soft pink
+            "self": "ff9bce",
+            "cls": "ff9bce",
+            
+            # Data literals - cool, calm ice blue
+            "string": "a5d6ff",
+            "string_quoted": "a5d6ff",
+            "string_doc": "8b949e",          # docstrings - like comments
+            "string_interpol": "ffd700",     # f-string braces - gold
+            "string_escape": "ffea00",       # escape sequences - bright yellow
+            
+            # Numbers - same as function def
+            "number": "79c0ff",
+            "number_float": "79c0ff",
+            "number_integer": "79c0ff",
+            "number_hex": "79c0ff",
+            
+            # Comments - muted gray
+            "comment": "8b949e",
+            "comment_doc": "8b949e",
+            "comment_preproc": "ff7b72",     # preprocessor directives
+            
+            # Operators - distinct pink/red for visibility
+            "operator": "ff7b72",            # General operators - coral
+            "operator_arithmetic": "ff7b72", # +, -, *, /, etc.
+            "operator_comparison": "ff7b72", # ==, !=, <, >, etc.
+            "operator_assignment": "ff7b72", # =, +=, -=, etc.
+            "operator_word": "ff7b72",       # and, or, not, in, is
+            "operator_dot": "c9d1d9",        # . - subtle for attribute access
+            
+            # Punctuation - neutral
+            "punctuation": "b4b4b4",
+            "punctuation_brace": "b4b4b4",   # [, ], {, }
+            "punctuation_paren": "b4b4b4",   # (, )
+            "punctuation_colon": "b4b4b4",   # :, ;
+            "punctuation_comma": "8b949e",   # , - slightly dimmed
+            
+            # Decorators - burnt orange
+            "decorator": "f0883e",
+            
+            # Constants - same as keywords
+            "constant": "ff7b72",
+            "constant_builtin": "ff7b72",    # True, False, None
+            
+            # Type hints and annotations - amber
+            "type_hint": "ffa657",
+            "type_builtin": "ffa657",
+            
+            # Exception handling - alert red
+            "exception": "f85149",
+            "exception_builtin": "f85149",
+            
+            # Names and attributes - near-white for readability
+            "name": "e6edf3",
+            "attribute": "e6edf3",
+            "attribute_call": "d2a8ff",       # Function/method calls after dot - lavender
+            "variable": "e6edf3",
+            "parameter": "e6edf3",
+            
+            # Namespaces and modules
+            "namespace": "7ee787",
+            "module": "a5d6ff",
+            
+            # Generic tokens
+            "generic_heading": "c9d1d9",
+            "generic_subheading": "c9d1d9",
+            "generic_prompt": "8b949e",
+            "generic_error": "f85149",
+            "generic_deleted": "f85149",
+            "generic_inserted": "7ee787",
+            "generic_output": "e6edf3",
+            
+            # Text and whitespace - no color (None means no color tag)
+            "text": None,
+            "whitespace": None,
+        }
+    
+    def _check_pygments(self):
+        try:
+            import pygments
+            from pygments.lexers import get_lexer_for_filename, guess_lexer, get_lexer_by_name
+            from pygments.formatter import Formatter
+            from pygments.token import Token
+            
+            self.pygments = pygments
+            self.pygments_available = True
+            RNS.log("Pygments syntax highlighting available", RNS.LOG_DEBUG)
+            
+        except ImportError:
+            self.pygments_available = False
+            RNS.log("Pygments not available, using plain text rendering", RNS.LOG_DEBUG)
+    
+    def highlight(self, content, filename=None, language=None):
+        if not content: return self._plain_text(content)
+        
+        if self.pygments_available:
+            try:
+                highlighted = self._highlight_pygments(content, filename, language)
+                # Fix pygments insisting on trailing newlines
+                if highlighted.endswith("\n") and not content.endswith("\n"): highlighted = highlighted[:-1]
+                return highlighted
+            
+            except Exception as e:
+                RNS.log(f"Pygments highlighting failed, falling back: {e}", RNS.LOG_WARNING)
+                return self._plain_text(content)
+        
+        # TODO: Implement Python tokenize fallback for .py files.
+        # For now, route to plain text
+        if filename and filename.endswith(".py"):
+            return self._plain_text(content)
+        
+        # Universal fallback
+        return self._plain_text(content)
+    
+    def _highlight_pygments(self, content, filename=None, language=None):
+        from pygments.lexers import get_lexer_for_filename, guess_lexer, get_lexer_by_name
+        from pygments.util import ClassNotFound
+        
+        lexer = None        
+        if language:
+            if language == "env":         language = "bash"
+            if language == "environment": language = "bash"
+            try: lexer = get_lexer_by_name(language)
+            except ClassNotFound: pass
+        
+        if lexer is None and filename:
+            try: lexer = get_lexer_for_filename(filename)
+            except ClassNotFound: pass
+        
+        if lexer is None:
+            try:
+                if len(content) > 20: lexer = guess_lexer(content)
+            except ClassNotFound: pass
+        
+        if lexer is None: return self._plain_text(content)
+
+        formatter = MicronFormatter(theme=self.theme)
+        result = self.pygments.highlight(content, lexer, formatter)
+        return result
+    
+    def _plain_text(self, content):
+        escaped = self._escape_micron(content)
+        return f"`=\n{escaped}\n`="
+    
+    @staticmethod
+    def _escape_micron(text): return text.replace("`", "\\`")
+
+
+class MicronFormatter:
+    def __init__(self, theme, **options):
+        self.theme = theme
+        self.options = options
+    
+    def format(self, tokensource, outfile):
+        output_parts = []
+        prev_was_dot = False
+        
+        for ttype, value in tokensource:
+            is_dot = (str(ttype) == "Token.Operator" and value == ".")
+            
+            # If previous token was a dot and this is a Name, treat as attribute/function call
+            # TODO: Improve this if we can check next token as parantheses or something.
+            if prev_was_dot and str(ttype).startswith("Token.Name") and value:
+                color = self._get_color_from_key("attribute_call")
+                if color:
+                    escaped = self._escape_value(value)
+                    output_parts.append(f"`FT{color}{escaped}`f")
+                else:
+                    output_parts.append(self._escape_value(value))
+            
+            else:
+                color_key = self._get_color_key_for_token(ttype)
+                color = self._get_color_from_key(color_key)
+                
+                if color and value:
+                    escaped = self._escape_value(value)
+                    if escaped.startswith("\n"): ilb = "\n"; escaped = escaped[1:]
+                    else:                        ilb = ""
+                    if escaped.endswith("\n"):   tlb = "\n"; escaped = escaped[:-1]
+                    else:                        tlb = ""
+                    output_parts.append(f"{ilb}`FT{color}{escaped}`f{tlb}")
+                
+                else: output_parts.append(self._escape_value(value))
+            
+            prev_was_dot = is_dot
+        
+        output = "".join(output_parts)
+        final_output = ""
+        for line in output.splitlines():
+            if line.startswith(">"): line = f"`>{line}"
+            final_output += f"{line}\n"
+
+        outfile.write(final_output)
+    
+    def _get_color_key_for_token(self, ttype):
+        token_parts = []
+        current = ttype
+        while current:
+            token_parts.insert(0, current[0] if isinstance(current, tuple) else str(current).split(".")[-1])
+            current = current.parent if hasattr(current, "parent") else None
+        
+        token_str = ".".join(["Token"] + token_parts[1:] if len(token_parts) > 1 else token_parts)
+
+        current_type = ttype
+        while current_type:
+            token_key = str(current_type)
+            if token_key in granular_token_map: return granular_token_map[token_key]
+            
+            # Move to parent
+            current_type = current_type.parent if hasattr(current_type, "parent") else None
+        
+        return None
+    
+    def _get_color_from_key(self, color_key):
+        if color_key and color_key in self.theme: return self.theme[color_key]
+        return None
+    
+    @staticmethod
+    def _escape_value(value: str) -> str: return value.replace("`", "\\`")
+    
+    # Required by Pygments formatter API, returns None for Micron
+    def get_style_defs(self, arg=None): return None
+
+
+# Convenience function for direct use
+def highlight_code(content: str, filename: str = None, language: str = None, theme=None) -> str:
+    highlighter = SyntaxHighlighter(theme=theme)
+    return highlighter.highlight(content, filename, language)
+
+granular_token_map = {
+    # Keywords with semantic distinction
+    "Token.Keyword": "keyword",
+    "Token.Keyword.Constant": "keyword_constant",
+    "Token.Keyword.Declaration": "keyword_declaration",
+    "Token.Keyword.Namespace": "keyword_control",
+    "Token.Keyword.Pseudo": "keyword_control",
+    "Token.Keyword.Reserved": "keyword_control",
+    "Token.Keyword.Type": "type_builtin",
+    
+    # Names - functions with definition vs call distinction
+    "Token.Name.Function": "function_call",
+    "Token.Name.Function.Magic": "function_magic",
+    "Token.Name.Class": "class_ref",
+    "Token.Name.Builtin": "function_builtin",
+    "Token.Name.Builtin.Pseudo": "constant_builtin",
+    "Token.Name.Exception": "exception_builtin",
+    "Token.Name.Decorator": "decorator",
+    "Token.Name.Namespace": "namespace",
+    "Token.Name.Attribute": "attribute",
+    "Token.Name.Variable": "variable",
+    "Token.Name.Variable.Magic": "function_magic",
+    "Token.Name.Other": "name",
+    "Token.Name": "name",
+    "Token.Name.Tag": "keyword",  # HTML/XML tags
+    "Token.Name.Constant": "constant",
+    "Token.Name.Label": "name",
+    "Token.Name.Entity": "name",
+    
+    # Literals - strings with detailed handling
+    "Token.Literal.String": "string",
+    "Token.Literal.String.Affix": "string",  # f, r, b prefixes
+    "Token.Literal.String.Backtick": "string",
+    "Token.Literal.String.Char": "string",
+    "Token.Literal.String.Delimiter": "string",
+    "Token.Literal.String.Doc": "string_doc",
+    "Token.Literal.String.Double": "string_quoted",
+    "Token.Literal.String.Escape": "string_escape",
+    "Token.Literal.String.Heredoc": "string",
+    "Token.Literal.String.Interpol": "string_interpol",
+    "Token.Literal.String.Other": "string",
+    "Token.Literal.String.Regex": "string",
+    "Token.Literal.String.Single": "string_quoted",
+    "Token.Literal.String.Symbol": "string",
+    
+    # Numbers
+    "Token.Literal.Number": "number",
+    "Token.Literal.Number.Bin": "number",
+    "Token.Literal.Number.Float": "number_float",
+    "Token.Literal.Number.Hex": "number_hex",
+    "Token.Literal.Number.Integer": "number_integer",
+    "Token.Literal.Number.Integer.Long": "number_integer",
+    "Token.Literal.Number.Oct": "number",
+    "Token.Literal": "string",
+    "Token.Literal.Date": "string",
+    
+    # Operators - all operators get distinct coloring
+    "Token.Operator": "operator",
+    "Token.Operator.Word": "operator_word",
+    "Token.Operator.Comparison": "operator_comparison",
+    "Token.Operator.Assignment": "operator_assignment",
+    "Token.Operator.Arithmetic": "operator_arithmetic",
+    
+    # Punctuation - braces, parens, colons, commas
+    "Token.Punctuation": "punctuation",
+    "Token.Punctuation.Marker": "punctuation",
+    "Token.Punctuation.Brace": "punctuation_brace",
+    "Token.Punctuation.Bracket": "punctuation_brace",
+    "Token.Punctuation.Parenthesis": "punctuation_paren",
+    "Token.Punctuation.Colon": "punctuation_colon",
+    "Token.Punctuation.Comma": "punctuation_comma",
+    
+    # Comments
+    "Token.Comment": "comment",
+    "Token.Comment.Hashbang": "comment",
+    "Token.Comment.Multiline": "comment_doc",
+    "Token.Comment.Preproc": "comment_preproc",
+    "Token.Comment.Single": "comment",
+    "Token.Comment.Special": "comment",
+    
+    # Generic tokens
+    "Token.Generic.Deleted": "generic_deleted",
+    "Token.Generic.Emph": "text",
+    "Token.Generic.Error": "generic_error",
+    "Token.Generic.Heading": "generic_heading",
+    "Token.Generic.Inserted": "generic_inserted",
+    "Token.Generic.Output": "generic_output",
+    "Token.Generic.Prompt": "generic_prompt",
+    "Token.Generic.Strong": "text",
+    "Token.Generic.Subheading": "generic_subheading",
+    "Token.Generic.Traceback": "generic_error",
+    "Token.Generic": "text",
+    
+    # Text and whitespace
+    "Token.Text": "text",
+    "Token.Text.Whitespace": "whitespace",
+}

RNS/Utilities/rngit/main.py

@@ -0,0 +1,40 @@
+# Reticulum License
+#
+# Copyright (c) 2016-2026 Mark Qvist
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# - The Software shall not be used in any kind of system which includes amongst
+#   its functions the ability to purposefully do harm to human beings.
+#
+# - The Software shall not be used, directly or indirectly, in the creation of
+#   an artificial intelligence, machine learning or language model training
+#   dataset, including but not limited to any use that contributes to the
+#   training or development of such a model or algorithm.
+#
+# - The above copyright notice and this permission notice shall be included in
+#   all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+import sys
+from RNS.Utilities.rngit import client, server
+
+if __name__ == "__main__":
+    cmd = sys.argv[0]
+    if   cmd == "rngit":          ec = server.main()
+    elif cmd == "git-remote-rns": ec = client.main()
+    else: raise NotImplementedError(f"The {cmd} executable entrypoint is not yet implemented in rngit")
+
+    sys.exit(ec)

RNS/Utilities/rngit/util.py

@@ -0,0 +1,699 @@
+# Reticulum License
+#
+# Copyright (c) 2016-2026 Mark Qvist
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# - The Software shall not be used in any kind of system which includes amongst
+#   its functions the ability to purposefully do harm to human beings.
+#
+# - The Software shall not be used, directly or indirectly, in the creation of
+#   an artificial intelligence, machine learning or language model training
+#   dataset, including but not limited to any use that contributes to the
+#   training or development of such a model or algorithm.
+#
+# - The above copyright notice and this permission notice shall be included in
+#   all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+import re
+import RNS
+
+class MarkdownToMicron:    
+    BOLD = "`!"
+    BOLD_END = "`!"
+    ITALIC = "`*"
+    ITALIC_END = "`*"
+    UNDERLINE = "`_"
+    UNDERLINE_END = "`_"
+    
+    CODE_BG = "`BT282828"
+    CODE_BG_INLINE = "`BT383838"
+    CODE_FG = "`Fddd"
+    CODE_RESET = "`f`b"
+    
+    LITERAL_START = "`="
+    LITERAL_END = "`="
+    
+    BULLET = "•"
+    
+    # Regex patterns for markdown elements
+    HEADER_RE = re.compile(r'^(#{1,6})\s+(.+)$')
+    CODE_FENCE_RE = re.compile(r'^(\s*)```(.*)$')
+    HORIZONTAL_RULE_RE = re.compile(r'^(\s*)(---+|===+|\*\*\*+|___+)\s*$')
+    UNORDERED_LIST_RE = re.compile(r'^(\s*)([-*+])\s+(.+)$')
+    
+    # Table patterns
+    TABLE_ROW_RE = re.compile(r'^\s*\|?(.+?)\|?\s*$')
+    TABLE_SEP_RE = re.compile(r'^\s*\|?(?:\s*:?-+:?\s*\|)+\s*$')
+    
+    # Quote pattern
+    QUOTE_RE = re.compile(r'^>\s?(.*)$')
+    
+    # Inline patterns (processed in order of specificity)
+    LINK_RE = re.compile(r'\[([^\]]+)\]\(([^)]+)\)')
+    INLINE_CODE_RE = re.compile(r'`([^`]+)`')
+    BOLD_RE = re.compile(r'\*\*(.+?)\*\*|__(.+?)__')
+    ITALIC_RE = re.compile(r'\*(.+?)\*|_(.+?)_')
+
+    TABLE_H = "─"
+    TABLE_V = "│"
+    TABLE_TL = "┌"
+    TABLE_TR = "┐"
+    TABLE_BL = "└"
+    TABLE_BR = "┘"
+    TABLE_ML = "├"
+    TABLE_MR = "┤"
+    TABLE_TM = "┬"
+    TABLE_BM = "┴"
+    TABLE_MM = "┼"
+    
+    TABLE_MIN_COL_WIDTH = 3
+
+    def __init__(self, max_width=100, syntax_highlighter=None):
+        self.max_width = max_width
+        self.syntax_highlighter = syntax_highlighter
+        self.wcwidth = None
+        
+        try:
+            import wcwidth
+            self.wcwidth = wcwidth
+
+        except: RNS.log(f"The wcwidth module is unavailable, display width calculations for some glyphs will be incorrect", RNS.LOG_WARNING)
+
+    def display_width(self, text):
+        if not self.wcwidth: return len(text)
+        else:
+            # wcswidth returns -1 for non-printable strings,
+            # fallback to len in this case
+            w = self.wcwidth.wcswidth(text)
+            return w if w is not None and w >= 0 else len(text)
+    
+    def format_block(self, text):
+        lines = text.split('\n')
+        result_lines = []
+        in_code_block = False
+        code_block_lang = None
+        code_buffer = []
+        in_table = False
+        table_buffer = []
+        in_quote = False
+        quote_buffer = []
+        
+        def flush_quote_buffer():
+            nonlocal result_lines, quote_buffer, in_quote
+            if not quote_buffer:
+                in_quote = False
+                return
+            
+            para = " ".join(quote_buffer)
+            formatted = self._format_inline(para)
+            
+            effective_width = self.max_width - 3
+            if effective_width < 1: effective_width = 1
+            wrapped_lines = self._wrap_text(formatted, effective_width)
+            for wrapped_line in wrapped_lines: result_lines.append(f" │ {wrapped_line}")
+            
+            quote_buffer = []
+            in_quote = False
+        
+        def flush_table_buffer():
+            nonlocal result_lines, table_buffer, in_table
+            if not table_buffer:
+                in_table = False
+                return
+            
+            if len(table_buffer) >= 2 and self._is_table_separator(table_buffer[1]):
+                formatted_lines = self.format_table(table_buffer)
+                result_lines.extend(formatted_lines)
+            
+            else:
+                for line in table_buffer: result_lines.append(self.format_line(line))
+            
+            table_buffer = []
+            in_table = False
+        
+        def flush_code_block():
+            nonlocal result_lines, code_buffer, code_block_lang
+            if not code_buffer:
+                return
+            
+            code_content = '\n'.join(code_buffer)
+            
+            if self.syntax_highlighter and code_block_lang:
+                try:
+                    highlighted = self.syntax_highlighter.highlight(code_content, language=code_block_lang)
+                    result_lines.append(f"{self.CODE_BG}{self.CODE_FG}")
+                    result_lines.append(highlighted)
+                    result_lines.append(self.CODE_RESET)
+
+                except Exception:
+                    # Fallback to plain literal block on any error
+                    result_lines.append(f"{self.CODE_BG}{self.CODE_FG}")
+                    result_lines.append(self.LITERAL_START)
+                    result_lines.append(self._escape_literals(code_content))
+                    result_lines.append(self.LITERAL_END)
+                    result_lines.append(self.CODE_RESET)
+            else:
+                result_lines.append(f"{self.CODE_BG}{self.CODE_FG}")
+                result_lines.append(self.LITERAL_START)
+                result_lines.append(self._escape_literals(code_content))
+                result_lines.append(self.LITERAL_END)
+                result_lines.append(self.CODE_RESET)
+            
+            code_buffer = []
+        
+        for line in lines:
+            is_fence, lang_hint = self._detect_code_fence(line)
+            
+            if is_fence:
+                # Flush any pending structures before code fence
+                flush_quote_buffer()
+                flush_table_buffer()
+                
+                if not in_code_block:
+                    # Opening fence, start buffering
+                    in_code_block = True
+                    code_block_lang = lang_hint.strip() if lang_hint else None
+                    code_buffer = []
+                
+                else:
+                    # Closing fence, flush highlighted code
+                    flush_code_block()
+                    in_code_block = False
+                    code_block_lang = None
+            
+            else:
+                # Buffer code lines for later highlighting
+                if in_code_block: code_buffer.append(line)
+                else:
+                    quote_match = self.QUOTE_RE.match(line)
+                    if quote_match:
+                        if not in_quote:
+                            flush_table_buffer()
+                            in_quote = True
+                            quote_buffer = []
+                        
+                        quote_buffer.append(quote_match.group(1))
+                    
+                    else:
+                        if in_quote:
+                            flush_quote_buffer()
+                            if line.strip() != "":
+                                if self._is_table_row(line):
+                                    in_table = True
+                                    table_buffer = [line]
+                                
+                                else:
+                                    formatted = self.format_line(line)
+                                    result_lines.append(formatted)
+                            
+                            # Pass through blank line as separator
+                            else: result_lines.append("")
+                        
+                        else:
+                            if self._is_table_row(line):
+                                if not in_table:
+                                    in_table = True
+                                    table_buffer = [line]
+                                
+                                else: table_buffer.append(line)
+                            
+                            else:
+                                # Line breaks table, flush buffer
+                                if in_table: flush_table_buffer()
+                                formatted = self.format_line(line)
+                                result_lines.append(formatted)
+        
+        # Handle unclosed structures
+        if in_quote: flush_quote_buffer()
+        if in_table: flush_table_buffer()
+        if in_code_block: flush_code_block()
+        
+        return '\n'.join(result_lines)
+    
+    def format_line(self, line, mode="normal"):
+        if mode == "codeblock": return self._escape_literals(line)
+        
+        if self.HORIZONTAL_RULE_RE.match(line): return self._format_horizontal_rule()
+        
+        header_match = self.HEADER_RE.match(line)
+        if header_match: return self._format_header(header_match)
+        
+        list_match = self.UNORDERED_LIST_RE.match(line)
+        if list_match: return self._format_list_item(list_match)
+        
+        line = self._format_inline(line)
+        
+        return line
+    
+    def _format_inline(self, text):
+        code_blocks = []
+        def extract_code(match):
+            code_blocks.append(match.group(1))
+            return f"\x00CODE{len(code_blocks)-1}\x00"
+
+        links = []
+        def extract_link(match):
+            links.append((match.group(1), match.group(2)))
+            return f"\x00LINK{len(links)-1}\x00"
+        
+        text = self.INLINE_CODE_RE.sub(extract_code, text)
+        text = self.LINK_RE.sub(extract_link, text)
+        text = self.BOLD_RE.sub(self._bold_sub, text)
+        text = self.ITALIC_RE.sub(self._italic_sub, text)
+        
+        def restore_link(match):
+            idx = int(match.group(1))
+            text, url = links[idx]
+            text = text.replace('`', '')
+            return f"`!`[{text}`{url}]`!"
+        
+        text = re.sub(r'\x00LINK(\d+)\x00', restore_link, text)
+        
+        def restore_code(match):
+            idx = int(match.group(1))
+            content = code_blocks[idx]
+            
+            # Disabled for now
+            # highlighted = self._highlight_inline_code(content)
+            # if highlighted: return highlighted
+            
+            # Use plain inline code formatting
+            content = content.replace('`', '\\`')
+            return f"{self.CODE_BG_INLINE}{self.CODE_FG}{content}{self.CODE_RESET}"
+        
+        text = re.sub(r'\x00CODE(\d+)\x00', restore_code, text)
+        return text
+    
+    def _highlight_inline_code(self, content):
+        if not self.syntax_highlighter: return None
+        return self.syntax_highlighter.highlight(content, language=None)
+    
+    def _bold_sub(self, match):
+        content = match.group(1) or match.group(2)
+        return f"{self.BOLD}{content}{self.BOLD_END}"
+    
+    def _italic_sub(self, match):
+        content = match.group(1) or match.group(2)
+        return f"{self.ITALIC}{content}{self.ITALIC_END}"
+    
+    def _format_header(self, match):
+        hashes = match.group(1)
+        content = match.group(2)
+        level = len(hashes)
+        prefix = ">" * min(level, 6)
+        return f"{prefix}{self._format_inline(content)}"
+    
+    def _format_list_item(self, match):
+        indent = match.group(1)
+        content = match.group(3)
+        content = self._format_inline(content)
+        return f"{indent} {self.BULLET} {content}"
+    
+    def _format_horizontal_rule(self):
+        return "-"
+    
+    def _detect_code_fence(self, line):
+        match = self.CODE_FENCE_RE.match(line)
+        if match:
+            # match.group(2) contains everything after the backticks (language hint)
+            return True, match.group(2)
+        return False, ""
+    
+    def _is_table_row(self, line):
+        if '|' not in line: return False
+        match = self.TABLE_ROW_RE.match(line)
+        if match is None: return False
+        content = match.group(1)
+        return '|' in content or line.strip().startswith('|')
+    
+    def _is_table_separator(self, line):
+        if '|' not in line: return False
+        match = self.TABLE_SEP_RE.match(line)
+        return match is not None
+    
+    def _escape_literals(self, text):
+        return text.replace('`', '\\`')
+
+    def format_table(self, rows, align="c"):
+        if len(rows) < 2: return rows
+        
+        # Parse header and separator
+        header_cells = self._parse_table_row(rows[0])
+        alignments = self._parse_table_alignments(rows[1])
+        
+        # Ensure alignment count matches header cells
+        while len(alignments) < len(header_cells): alignments.append('left')
+        alignments = alignments[:len(header_cells)]
+        
+        # Parse data rows
+        data_rows = []
+        for i in range(2, len(rows)):
+            cells = self._parse_table_row(rows[i])
+            while len(cells) < len(header_cells): cells.append("")
+            cells = cells[:len(header_cells)]
+            data_rows.append(cells)
+        
+        # Calculate column widths based on content
+        num_cols = len(header_cells)
+        col_widths = [0] * num_cols
+        
+        all_rows = [header_cells] + data_rows
+        for row in all_rows:
+            for i, cell in enumerate(row):
+                formatted = self._format_inline(cell)
+                width = self._visible_width(formatted)
+                col_widths[i] = max(col_widths[i], width)
+        
+        # Apply minimum width and calculate total
+        col_widths = [max(w, self.TABLE_MIN_COL_WIDTH) for w in col_widths]
+        
+        # Check max_width constraint
+        # Total = sum of columns + 3 chars per column (space + 2 borders) + 1 for final border
+        total_width = sum(col_widths) + (num_cols * 3) + 1
+        
+        if total_width > self.max_width:
+            # Reduce widest columns proportionally
+            excess = total_width - self.max_width
+            indexed_widths = [(i, w) for i, w in enumerate(col_widths)]
+            indexed_widths.sort(key=lambda x: -x[1])
+            
+            for i, w in indexed_widths:
+                if excess <= 0: break
+                reduction = min(excess, w - self.TABLE_MIN_COL_WIDTH)
+                col_widths[i] -= reduction
+                excess -= reduction
+        
+        # Build formatted table
+        result = []
+        
+        # Alignment start
+        if align: result.append(f"`{align}")
+        
+        # Top border
+        border = self.TABLE_TL
+        for i, w in enumerate(col_widths):
+            border += self.TABLE_H * (w + 2)
+            if i < len(col_widths) - 1: border += self.TABLE_TM
+            else:                       border += self.TABLE_TR
+        
+        result.append(self._escape_literals(border))
+        
+        # Header row
+        header_line = self.TABLE_V
+        for i, cell in enumerate(header_cells):
+            formatted = self._format_inline(cell)
+            padded = self._pad_cell(formatted, col_widths[i], 'left')
+            header_line += f" {padded} {self.TABLE_V}"
+        result.append(self._escape_literals(header_line))
+        
+        # Separator row
+        sep_line = self.TABLE_ML
+        for i, w in enumerate(col_widths):
+            cell_width = w + 2
+            sep_line += self.TABLE_H * cell_width
+            
+            if i < len(col_widths) - 1: sep_line += self.TABLE_MM
+            else:                       sep_line += self.TABLE_MR
+
+        result.append(self._escape_literals(sep_line))
+        
+        # Data rows
+        for row in data_rows:
+            row_line = self.TABLE_V
+            for i, cell in enumerate(row):
+                formatted = self._format_inline(cell)
+                padded = self._pad_cell(formatted, col_widths[i], alignments[i])
+                row_line += f" {padded} {self.TABLE_V}"
+            
+            result.append(row_line)
+        
+        # Bottom border
+        border = self.TABLE_BL
+        for i, w in enumerate(col_widths):
+            border += self.TABLE_H * (w + 2)
+            if i < len(col_widths) - 1: border += self.TABLE_BM
+            else:                       border += self.TABLE_BR
+        
+        result.append(self._escape_literals(border))
+        
+        # End alignment
+        if align: result.append("`a")
+        
+        return result
+
+    def format_table_raw(self, rows, align="c"):
+        if len(rows) < 2: return rows
+        
+        # Parse header and separator
+        header_cells = self._parse_table_row(rows[0])
+        alignments = self._parse_table_alignments(rows[1])
+        
+        # Ensure alignment count matches header cells
+        while len(alignments) < len(header_cells): alignments.append('left')
+        alignments = alignments[:len(header_cells)]
+        
+        # Parse data rows
+        data_rows = []
+        for i in range(2, len(rows)):
+            cells = self._parse_table_row(rows[i])
+            while len(cells) < len(header_cells): cells.append("")
+            cells = cells[:len(header_cells)]
+            data_rows.append(cells)
+        
+        # Calculate column widths based on raw content
+        num_cols = len(header_cells)
+        col_widths = [0] * num_cols
+        
+        all_rows = [header_cells] + data_rows
+        for row in all_rows:
+            for i, cell in enumerate(row):
+                width = self._visible_width(cell)
+                col_widths[i] = max(col_widths[i], width)
+        
+        # Apply minimum width and calculate total
+        col_widths = [max(w, self.TABLE_MIN_COL_WIDTH) for w in col_widths]
+        
+        # Check max_width constraint
+        total_width = sum(col_widths) + (num_cols * 3) + 1
+        
+        if total_width > self.max_width:
+            # Reduce widest columns proportionally
+            excess = total_width - self.max_width
+            indexed_widths = [(i, w) for i, w in enumerate(col_widths)]
+            indexed_widths.sort(key=lambda x: -x[1])
+            
+            for i, w in indexed_widths:
+                if excess <= 0: break
+                reduction = min(excess, w - self.TABLE_MIN_COL_WIDTH)
+                col_widths[i] -= reduction
+                excess -= reduction
+        
+        # Build formatted table
+        result = []
+        
+        # Alignment start
+        if align: result.append(f"`{align}")
+        
+        # Top border
+        border = self.TABLE_TL
+        for i, w in enumerate(col_widths):
+            border += self.TABLE_H * (w + 2)
+            if i < len(col_widths) - 1: border += self.TABLE_TM
+            else:                       border += self.TABLE_TR
+        
+        result.append(self._escape_literals(border))
+        
+        # Header row
+        header_line = self.TABLE_V
+        for i, cell in enumerate(header_cells):
+            padded = self._pad_cell(cell, col_widths[i], 'left')
+            header_line += f" {padded} {self.TABLE_V}"
+        result.append(header_line)
+        
+        # Separator row - clean horizontal lines without alignment markers
+        sep_line = self.TABLE_ML
+        for i, w in enumerate(col_widths):
+            cell_width = w + 2
+            sep_line += self.TABLE_H * cell_width
+            
+            if i < len(col_widths) - 1: sep_line += self.TABLE_MM
+            else:                       sep_line += self.TABLE_MR
+        
+        result.append(self._escape_literals(sep_line))
+        
+        # Data rows (with alignment)
+        for row in data_rows:
+            row_line = self.TABLE_V
+            for i, cell in enumerate(row):
+                padded = self._pad_cell(cell, col_widths[i], alignments[i])
+                row_line += f" {padded} {self.TABLE_V}"
+            
+            result.append(row_line)
+        
+        # Bottom border
+        border = self.TABLE_BL
+        for i, w in enumerate(col_widths):
+            border += self.TABLE_H * (w + 2)
+            if i < len(col_widths) - 1: border += self.TABLE_BM
+            else:                       border += self.TABLE_BR
+        
+        result.append(self._escape_literals(border))
+        
+        # End alignment
+        if align: result.append("`a")
+        
+        return result
+    
+    def _parse_table_row(self, line):
+        line = line.strip()
+        if line.startswith('|'): line = line[1:]
+        if line.endswith('|'):   line = line[:-1]
+        
+        cells = []
+        current = ""
+        escaped = False
+        for char in line:
+            if escaped:
+                current += char
+                escaped = False
+            elif char == '\\':
+                escaped = True
+            elif char == '|':
+                cells.append(current.strip())
+                current = ""
+            else:
+                current += char
+        
+        cells.append(current.strip())
+        return cells
+    
+    def _parse_table_alignments(self, line):
+        cells = self._parse_table_row(line)
+        alignments = []
+        for cell in cells:
+            cell = cell.strip()
+            if cell.startswith(':') and cell.endswith(':'): alignments.append('center')
+            elif cell.endswith(':'):                        alignments.append('right')
+            else:                                           alignments.append('left')
+        
+        return alignments
+    
+    def _visible_width(self, text):
+        text = re.sub(r'`[FB][0-9a-fA-F]{3}', '', text)
+        text = re.sub(r'`[FB]T[0-9a-fA-F]{6}', '', text)
+        text = re.sub(r'`[!*_=]', '', text)
+        text = re.sub(r'`f`b', '', text)
+        text = re.sub(r'`f', '', text)
+        text = re.sub(r'`b', '', text)
+        return self.display_width(text)
+    
+    def _pad_cell(self, text, width, align):
+        text = self._truncate_cell(text, width)
+        text_width = self._visible_width(text)
+        padding = width - text_width
+        
+        if align == 'right':
+            return " " * padding + text
+        elif align == 'center':
+            left = padding // 2
+            right = padding - left
+            return " " * left + text + " " * right
+        else:
+            return text + " " * padding
+    
+    def _truncate_cell(self, text, width):
+        if self._visible_width(text) <= width: return text
+        
+        stripped = text
+        stripped = re.sub(r'`[FB][0-9a-fA-F]{3}', '', stripped)
+        stripped = re.sub(r'`[!*_]', '', stripped)
+        stripped = re.sub(r'`f`b', '', stripped)
+        
+        if len(stripped) <= width - 1: return text
+        
+        truncated = stripped[:width - 1] + "…"
+        return truncated
+    
+    def _wrap_text(self, text, width):
+        if not text: return [""]
+        
+        words = text.split(' ')
+        lines = []
+        current_line = ""
+        current_width = 0
+        
+        for word in words:
+            if not word: continue
+            
+            word_width = self._visible_width(word)
+            
+            # Check if word alone exceeds width to force break it
+            if word_width > width:
+                if current_line:
+                    lines.append(current_line)
+                    current_line = ""
+                    current_width = 0
+                
+                # Force break the long word character by character
+                remaining = word
+                while remaining:
+                    # Binary search for how many characters fit
+                    low, high = 1, len(remaining)
+                    fit_chars = 0
+                    
+                    while low <= high:
+                        mid = (low + high) // 2
+                        test_substr = remaining[:mid]
+                        test_width = self._visible_width(test_substr)
+                        
+                        if test_width <= width:
+                            fit_chars = mid
+                            low = mid + 1
+                        else:
+                            high = mid - 1
+                    
+                    if fit_chars == 0: fit_chars = 1 # Need to force progress
+                    
+                    lines.append(remaining[:fit_chars])
+                    remaining = remaining[fit_chars:]
+                
+                continue
+            
+            # Check if word fits on current line
+            space_width = 1 if current_line else 0
+            if current_width + space_width + word_width <= width:
+                if current_line:
+                    current_line += " " + word
+                    current_width += space_width + word_width
+                else:
+                    current_line = word
+                    current_width = word_width
+            else:
+                # Flush current line and start new one
+                lines.append(current_line)
+                current_line = word
+                current_width = word_width
+        
+        # Don't forget the last line
+        if current_line: lines.append(current_line)
+        
+        return lines if lines else [""]
+
+
+def convert_markdown_to_micron(text):
+    converter = MarkdownToMicron()
+    return converter.format_block(text)

RNS/Utilities/rnir.py

@@ -56,7 +56,7 @@ def main():
         parser.add_argument('-v', '--verbose', action='count', default=0)
         parser.add_argument('-q', '--quiet', action='count', default=0)
         parser.add_argument("--exampleconfig", action='store_true', default=False, help="print verbose configuration example to stdout and exit")
-        parser.add_argument("--version", action="version", version="ir {version}".format(version=__version__))
+        parser.add_argument("--version", action="version", version="rnir {version}".format(version=__version__))
         
         args = parser.parse_args()
 
@@ -75,8 +75,5 @@ def main():
         print("")
         exit()
 
-__example_rns_config__ = '''# This is an example Identity Resolver file.
-'''
-
 if __name__ == "__main__":
     main()

RNS/Utilities/rnodeconf.py

@@ -49,9 +49,9 @@ import RNS
 RNS.logtimefmt      = "%H:%M:%S"
 RNS.compact_log_fmt = True
 
-program_version = "2.4.0"
-eth_addr = "0xFDabC71AC4c0C78C95aDDDe3B4FA19d6273c5E73"
-btc_addr = "35G9uWVzrpJJibzUwpNUQGQNFzLirhrYAH"
+program_version = "2.5.0"
+eth_addr = "0x91C421DdfB8a30a49A71d63447ddb54cEBe3465E"
+btc_addr = "bc1pgqgu8h8xvj4jtafslq396v7ju7hkgymyrzyqft4llfslz5vp99psqfk3a6"
 xmr_addr = "87HcDx6jRSkMQ9nPRd5K9hGGpZLn2s7vWETjMaVM5KfV4TD36NcYa8J8WSxhTSvBzzFpqDwp2fg5GX2moZ7VAP9QMZCZGET"
 
 rnode = None
@@ -1185,8 +1185,8 @@ class RNode():
                             print("     Always use a firmware downloaded as binaries or compiled from source")
                             print("     from one of the following locations:")
                             print("     ")
-                            print("        https://unsigned.io/rnode")
                             print("        https://github.com/markqvist/rnode_firmware")
+                            print("        https://github.com/liberatedsystems/RNode_Firmware_CE")
                             print("     ")
                             print("     You can reflash and bootstrap this device to a verifiable state")
                             print("     by using this utility. It is recommended to do so NOW!")
@@ -1228,7 +1228,7 @@ class RNode():
 
 selected_version = None
 selected_hash = None
-firmware_version_url = "https://unsigned.io/firmware/latest/?v="+program_version+"&variant="
+firmware_version_url          = "https://github.com/markqvist/rnode_firmware/releases/latest/download/release.json"
 fallback_firmware_version_url = "https://github.com/markqvist/rnode_firmware/releases/latest/download/release.json"
 def ensure_firmware_file(fw_filename):
     global selected_version, selected_hash, upd_nocheck
@@ -1269,9 +1269,15 @@ def ensure_firmware_file(fw_filename):
                 try:
                     # if custom firmware url, download latest release
                     if selected_version == None and fw_url == None:
-                        version_url = firmware_version_url+fw_filename
-                        RNS.log("Retrieving latest version info from "+version_url)
-                        urlretrieve(firmware_version_url+fw_filename, UPD_DIR+"/"+fw_filename+".version.latest")
+                        urlretrieve(firmware_version_url, UPD_DIR+"/release_info.json")
+                        import json
+                        with open(UPD_DIR+"/release_info.json", "rb") as rif:
+                            rdat = json.loads(rif.read())
+                            variant = rdat[fw_filename]
+                            with open(UPD_DIR+"/"+fw_filename+".version.latest", "wb") as verf:
+                                inf_str = str(variant["version"])+" "+str(variant["hash"])
+                                verf.write(inf_str.encode("utf-8"))
+
                     else:
                         if fw_url != None:
                             if selected_version == None:
@@ -1542,13 +1548,14 @@ def main():
         args = parser.parse_args()
 
         def print_donation_block():
-            print("  Ethereum : "+eth_addr)
-            print("  Bitcoin  : "+btc_addr)
-            print("  Monero   : "+xmr_addr)
-            print("  Ko-Fi    : https://ko-fi.com/markqvist")
+            print("  Ethereum  : "+eth_addr)
+            print("  Bitcoin   : "+btc_addr)
+            print("  Monero    : "+xmr_addr)
+            print("  Ko-Fi     : https://ko-fi.com/markqvist")
+            print("  LiberaPay : https://liberapay.com/reticulum")
             print("")
-            print("  Info     : https://unsigned.io/")
-            print("  Code     : https://github.com/markqvist")
+            print("  Info      : https://reticulum.network")
+            print("  Code      : https://github.com/markqvist")
 
         if args.version:
             print("rnodeconf "+program_version)

RNS/Utilities/rnpath.py

@@ -39,7 +39,8 @@ import argparse
 from RNS._version import __version__
 
 remote_link = None
-def connect_remote(destination_hash, auth_identity, timeout, no_output = False):
+output_rst_str = "\r                                                          \r"
+def connect_remote(destination_hash, auth_identity, timeout, no_output = False, purpose="management"):
     global remote_link, reticulum
     if not RNS.Transport.has_path(destination_hash):
         if not no_output:
@@ -51,7 +52,7 @@ def connect_remote(destination_hash, auth_identity, timeout, no_output = False):
             time.sleep(0.1)
             if time.time() - pr_time > timeout:
                 if not no_output:
-                    print("\r                                                          \r", end="")
+                    print(output_rst_str, end="")
                     print("Path request timed out")
                     exit(12)
 
@@ -60,98 +61,210 @@ def connect_remote(destination_hash, auth_identity, timeout, no_output = False):
     def remote_link_closed(link):
         if link.teardown_reason == RNS.Link.TIMEOUT:
             if not no_output:
-                print("\r                                                          \r", end="")
+                print(output_rst_str, end="")
                 print("The link timed out, exiting now")
         elif link.teardown_reason == RNS.Link.DESTINATION_CLOSED:
             if not no_output:
-                print("\r                                                          \r", end="")
+                print(output_rst_str, end="")
                 print("The link was closed by the server, exiting now")
         else:
             if not no_output:
-                print("\r                                                          \r", end="")
+                print(output_rst_str, end="")
                 print("Link closed unexpectedly, exiting now")
         exit(10)
 
     def remote_link_established(link):
         global remote_link
-        link.identify(auth_identity)
+        if purpose == "management": link.identify(auth_identity)
         remote_link = link
 
     if not no_output:
-        print("\r                                                          \r", end="")
+        print(output_rst_str, end="")
         print("Establishing link with remote transport instance...", end=" ")
         sys.stdout.flush()
 
-    remote_destination = RNS.Destination(remote_identity, RNS.Destination.OUT, RNS.Destination.SINGLE, "rnstransport", "remote", "management")
+    if purpose == "management": remote_destination = RNS.Destination(remote_identity, RNS.Destination.OUT, RNS.Destination.SINGLE, "rnstransport", "remote", "management")
+    elif purpose == "blackhole": remote_destination = RNS.Destination(remote_identity, RNS.Destination.OUT, RNS.Destination.SINGLE, "rnstransport", "info", "blackhole")
     link = RNS.Link(remote_destination)
     link.set_link_established_callback(remote_link_established)
     link.set_link_closed_callback(remote_link_closed)
 
+def parse_hash(input_str):
+    dest_len = (RNS.Reticulum.TRUNCATED_HASHLENGTH//8)*2
+    if len(input_str) != dest_len: raise ValueError("Hash length is invalid, must be {hex} hexadecimal characters ({byte} bytes).".format(hex=dest_len, byte=dest_len//2))
+    try:
+        hash_bytes = bytes.fromhex(input_str)
+        return hash_bytes
+    except Exception as e: raise ValueError("Invalid hash entered. Check your input.")
+
 def program_setup(configdir, table, rates, drop, destination_hexhash, verbosity, timeout, drop_queues,
                   drop_via, max_hops, remote=None, management_identity=None, remote_timeout=RNS.Transport.PATH_REQUEST_TIMEOUT,
-                  no_output=False, json=False):
+                  blackholed=False, blackhole=False, unblackhole=False, blackhole_duration=None, blackhole_reason=None,
+                  remote_blackhole_list=False, remote_blackhole_list_filter=None, no_output=False, json=False):
+
     global remote_link, reticulum
     reticulum = RNS.Reticulum(configdir = configdir, loglevel = 3+verbosity)
     if remote:
         try:
             dest_len = (RNS.Reticulum.TRUNCATED_HASHLENGTH//8)*2
-            if len(remote) != dest_len:
-                raise ValueError("Destination length is invalid, must be {hex} hexadecimal characters ({byte} bytes).".format(hex=dest_len, byte=dest_len//2))
+            if len(remote) != dest_len: raise ValueError("Destination length is invalid, must be {hex} hexadecimal characters ({byte} bytes).".format(hex=dest_len, byte=dest_len//2))
             try:
                 identity_hash = bytes.fromhex(remote)
                 remote_hash = RNS.Destination.hash_from_name_and_identity("rnstransport.remote.management", identity_hash)
-            except Exception as e:
-                raise ValueError("Invalid destination entered. Check your input.")
+            except Exception as e: raise ValueError("Invalid destination entered. Check your input.")
 
             identity = RNS.Identity.from_file(os.path.expanduser(management_identity))
-            if identity == None:
-                raise ValueError("Could not load management identity from "+str(management_identity))
+            if identity == None: raise ValueError("Could not load management identity from "+str(management_identity))
 
-            try:
-                connect_remote(remote_hash, identity, remote_timeout, no_output)
-            except Exception as e:
-                raise e
+            try: connect_remote(remote_hash, identity, remote_timeout, no_output)
+            except Exception as e: raise e
 
         except Exception as e:
             print(str(e))
             exit(20)
 
-        while remote_link == None:
-            time.sleep(0.1)
+        while remote_link == None: time.sleep(0.1)
 
+    if blackholed or remote_blackhole_list:
+        blackholed_list = None
+        if blackholed:
+            if remote_link:
+                if not no_output:
+                    print(output_rst_str, end="")
+                    print("Listing blackholed identities on remote instances not yet implemented")
+                exit(255)
 
-    if table:
+            try: blackholed_list = reticulum.get_blackholed_identities()
+            except Exception as e:
+                print(f"Could not get blackholed identities from RNS instance: {e}")
+                exit(20)
+
+        elif remote_blackhole_list:
+            try: identity_hash = parse_hash(destination_hexhash)
+            except Exception as e:
+                print(f"{e}")
+                exit(20)
+
+            remote_hash = RNS.Destination.hash_from_name_and_identity("rnstransport.info.blackhole", identity_hash)
+            connect_remote(remote_hash, None, remote_timeout, no_output, purpose="blackhole")
+            while remote_link == None: time.sleep(0.1)
+
+            if not no_output:
+                print(output_rst_str, end="")
+                print("Sending request...", end=" ")
+                sys.stdout.flush()
+            receipt = remote_link.request("/list")
+            while not receipt.concluded(): time.sleep(0.1)
+            response = receipt.get_response()
+            if type(response) == dict:
+                blackholed_list = response
+                print(output_rst_str, end="")
+            else:
+                if not no_output:
+                    print(output_rst_str, end="")
+                    print("The remote request failed.")
+                exit(10)
+
+        else:
+            print(f"Nowhere to fetch blackhole list from")
+            exit(255)
+
+        if not blackholed_list:
+            print("No blackholed identity data available")
+            exit(20)
+
+        else:
+            rmlen = 64
+            def trunc(input_str):
+                if len(input_str) <= rmlen: return input_str
+                else: return f"{input_str[:rmlen-1]}…"
+
+            try:
+                now = time.time()
+                for identity_hash in blackholed_list:
+                    until      = blackholed_list[identity_hash]["until"]
+                    reason     = blackholed_list[identity_hash]["reason"]
+                    source     = blackholed_list[identity_hash]["source"]
+                    until_str  = f"for {RNS.prettytime(max(0, until-now))}" if until else "indefinitely"
+                    reason_str = f" ({trunc(reason)})" if reason else ""
+                    by_str     = f" by {RNS.prettyhexrep(source)}" if source != RNS.Transport.identity.hash else ""
+                    filter_str = f"{RNS.prettyhexrep(identity_hash)} {until_str} {reason_str} {by_str}"
+
+                    if not remote_blackhole_list:
+                        if destination_hexhash and not destination_hexhash in filter_str: continue
+                    else:
+                        if remote_blackhole_list_filter and not remote_blackhole_list_filter in filter_str: continue
+
+                    print(f"{RNS.prettyhexrep(identity_hash)} blackholed {until_str}{reason_str}{by_str}")
+
+            except Exception as e:
+                print(f"Error while displaying collected blackhole data: {e}")
+                exit(20)
+
+    elif blackhole:
+        if remote_link:
+            if not no_output:
+                print(output_rst_str, end="")
+                print("Blackholing identity on remote instances not yet implemented")
+            exit(255)
+
+        try:
+            identity_hash = parse_hash(destination_hexhash)
+            until = time.time()+blackhole_duration*60*60 if blackhole_duration else None
+            result = reticulum.blackhole_identity(identity_hash, until=until, reason=blackhole_reason)
+            if result == True: print(f"Blackholed identity {destination_hexhash}")
+            elif result == None: print(f"Identity {destination_hexhash} already blackholed")
+            else: print(f"Could not blackhole identity {destination_hexhash}")
+        
+        except Exception as e:
+            print(f"Could not blackhole identity: {e}")
+            exit(20)
+    
+    elif unblackhole:
+        if remote_link:
+            if not no_output:
+                print(output_rst_str, end="")
+                print("Blackholing identity on remote instances not yet implemented")
+            exit(255)
+
+        try:
+            identity_hash = parse_hash(destination_hexhash)
+            result = reticulum.unblackhole_identity(identity_hash)
+            if result == True: print(f"Lifted blackhole for identity {destination_hexhash}")
+            elif result == None: print(f"Identity {destination_hexhash} not blackholed")
+            else: print(f"Could not unblackhole identity {destination_hexhash}")
+        
+        except Exception as e:
+            print(f"Could not unblackhole identity: {e}")
+            exit(20)
+    
+    elif table:
         destination_hash = None
         if destination_hexhash != None:
             try:
                 dest_len = (RNS.Reticulum.TRUNCATED_HASHLENGTH//8)*2
-                if len(destination_hexhash) != dest_len:
-                    raise ValueError("Destination length is invalid, must be {hex} hexadecimal characters ({byte} bytes).".format(hex=dest_len, byte=dest_len//2))
-                try:
-                    destination_hash = bytes.fromhex(destination_hexhash)
-                except Exception as e:
-                    raise ValueError("Invalid destination entered. Check your input.")
+                if len(destination_hexhash) != dest_len: raise ValueError("Destination length is invalid, must be {hex} hexadecimal characters ({byte} bytes).".format(hex=dest_len, byte=dest_len//2))
+                try: destination_hash = bytes.fromhex(destination_hexhash)
+                except Exception as e: raise ValueError("Invalid destination entered. Check your input.")
             except Exception as e:
                 print(str(e))
                 sys.exit(1)
 
-        if not remote_link:
-            table = sorted(reticulum.get_path_table(max_hops=max_hops), key=lambda e: (e["interface"], e["hops"]) )
+        if not remote_link: table = sorted(reticulum.get_path_table(max_hops=max_hops), key=lambda e: (e["interface"], e["hops"]) )
         else:
             if not no_output:
-                print("\r                                                          \r", end="")
+                print(output_rst_str, end="")
                 print("Sending request...", end=" ")
                 sys.stdout.flush()
             receipt = remote_link.request("/path", data = ["table", destination_hash, max_hops])
-            while not receipt.concluded():
-                time.sleep(0.1)
+            while not receipt.concluded(): time.sleep(0.1)
             response = receipt.get_response()
             if response:
                 table = response
-                print("\r                                                          \r", end="")
+                print(output_rst_str, end="")
             else:
                 if not no_output:
-                    print("\r                                                          \r", end="")
+                    print(output_rst_str, end="")
                     print("The remote request failed. Likely authentication failure.")
                 exit(10)
 
@@ -160,20 +273,18 @@ def program_setup(configdir, table, rates, drop, destination_hexhash, verbosity,
             import json
             for p in table:
                 for k in p:
-                    if isinstance(p[k], bytes):
-                        p[k] = RNS.hexrep(p[k], delimit=False)
+                    if isinstance(p[k], bytes): p[k] = RNS.hexrep(p[k], delimit=False)
 
             print(json.dumps(table))
             exit()
+        
         else:
             for path in table:
                 if destination_hash == None or destination_hash == path["hash"]:
                     displayed += 1
                     exp_str = RNS.timestamp_str(path["expires"])
-                    if path["hops"] == 1:
-                        m_str = " "
-                    else:
-                        m_str = "s"
+                    if path["hops"] == 1: m_str = " "
+                    else: m_str = "s"
                     print(RNS.prettyhexrep(path["hash"])+" is "+str(path["hops"])+" hop"+m_str+" away via "+RNS.prettyhexrep(path["via"])+" on "+path["interface"]+" expires "+RNS.timestamp_str(path["expires"]))
 
             if destination_hash != None and displayed == 0:
@@ -185,21 +296,17 @@ def program_setup(configdir, table, rates, drop, destination_hexhash, verbosity,
         if destination_hexhash != None:
             try:
                 dest_len = (RNS.Reticulum.TRUNCATED_HASHLENGTH//8)*2
-                if len(destination_hexhash) != dest_len:
-                    raise ValueError("Destination length is invalid, must be {hex} hexadecimal characters ({byte} bytes).".format(hex=dest_len, byte=dest_len//2))
-                try:
-                    destination_hash = bytes.fromhex(destination_hexhash)
-                except Exception as e:
-                    raise ValueError("Invalid destination entered. Check your input.")
+                if len(destination_hexhash) != dest_len: raise ValueError("Destination length is invalid, must be {hex} hexadecimal characters ({byte} bytes).".format(hex=dest_len, byte=dest_len//2))
+                try: destination_hash = bytes.fromhex(destination_hexhash)
+                except Exception as e: raise ValueError("Invalid destination entered. Check your input.")
             except Exception as e:
                 print(str(e))
                 sys.exit(1)
 
-        if not remote_link:
-            table = reticulum.get_rate_table()
+        if not remote_link: table = reticulum.get_rate_table()
         else:
             if not no_output:
-                print("\r                                                          \r", end="")
+                print(output_rst_str, end="")
                 print("Sending request...", end=" ")
                 sys.stdout.flush()
             receipt = remote_link.request("/path", data = ["rates", destination_hash])
@@ -208,10 +315,10 @@ def program_setup(configdir, table, rates, drop, destination_hexhash, verbosity,
             response = receipt.get_response()
             if response:
                 table = response
-                print("\r                                                          \r", end="")
+                print(output_rst_str, end="")
             else:
                 if not no_output:
-                    print("\r                                                          \r", end="")
+                    print(output_rst_str, end="")
                     print("The remote request failed. Likely authentication failure.")
                 exit(10)
 
@@ -220,15 +327,12 @@ def program_setup(configdir, table, rates, drop, destination_hexhash, verbosity,
             import json
             for p in table:
                 for k in p:
-                    if isinstance(p[k], bytes):
-                        p[k] = RNS.hexrep(p[k], delimit=False)
+                    if isinstance(p[k], bytes): p[k] = RNS.hexrep(p[k], delimit=False)
 
             print(json.dumps(table))
             exit()
         else:
-            if len(table) == 0:
-                print("No information available")
-
+            if len(table) == 0: print("No information available")
             else:
                 displayed = 0
                 for entry in table:
@@ -274,7 +378,7 @@ def program_setup(configdir, table, rates, drop, destination_hexhash, verbosity,
     elif drop_queues:
         if remote_link:
             if not no_output:
-                print("\r                                                          \r", end="")
+                print(output_rst_str, end="")
                 print("Dropping announce queues on remote instances not yet implemented")
             exit(255)
 
@@ -284,24 +388,20 @@ def program_setup(configdir, table, rates, drop, destination_hexhash, verbosity,
     elif drop:
         if remote_link:
             if not no_output:
-                print("\r                                                          \r", end="")
+                print(output_rst_str, end="")
                 print("Dropping path on remote instances not yet implemented")
             exit(255)
 
         try:
             dest_len = (RNS.Reticulum.TRUNCATED_HASHLENGTH//8)*2
-            if len(destination_hexhash) != dest_len:
-                raise ValueError("Destination length is invalid, must be {hex} hexadecimal characters ({byte} bytes).".format(hex=dest_len, byte=dest_len//2))
-            try:
-                destination_hash = bytes.fromhex(destination_hexhash)
-            except Exception as e:
-                raise ValueError("Invalid destination entered. Check your input.")
+            if len(destination_hexhash) != dest_len: raise ValueError("Destination length is invalid, must be {hex} hexadecimal characters ({byte} bytes).".format(hex=dest_len, byte=dest_len//2))
+            try: destination_hash = bytes.fromhex(destination_hexhash)
+            except Exception as e: raise ValueError("Invalid destination entered. Check your input.")
         except Exception as e:
             print(str(e))
             sys.exit(1)
 
-        if reticulum.drop_path(destination_hash):
-            print("Dropped path to "+RNS.prettyhexrep(destination_hash))
+        if reticulum.drop_path(destination_hash): print("Dropped path to "+RNS.prettyhexrep(destination_hash))
         else:
             print("Unable to drop path to "+RNS.prettyhexrep(destination_hash)+". Does it exist?")
             sys.exit(1)
@@ -309,24 +409,20 @@ def program_setup(configdir, table, rates, drop, destination_hexhash, verbosity,
     elif drop_via:
         if remote_link:
             if not no_output:
-                print("\r                                                          \r", end="")
+                print(output_rst_str, end="")
                 print("Dropping all paths via specific transport instance on remote instances yet not implemented")
             exit(255)
 
         try:
             dest_len = (RNS.Reticulum.TRUNCATED_HASHLENGTH//8)*2
-            if len(destination_hexhash) != dest_len:
-                raise ValueError("Destination length is invalid, must be {hex} hexadecimal characters ({byte} bytes).".format(hex=dest_len, byte=dest_len//2))
-            try:
-                destination_hash = bytes.fromhex(destination_hexhash)
-            except Exception as e:
-                raise ValueError("Invalid destination entered. Check your input.")
+            if len(destination_hexhash) != dest_len: raise ValueError("Destination length is invalid, must be {hex} hexadecimal characters ({byte} bytes).".format(hex=dest_len, byte=dest_len//2))
+            try: destination_hash = bytes.fromhex(destination_hexhash)
+            except Exception as e: raise ValueError("Invalid destination entered. Check your input.")
         except Exception as e:
             print(str(e))
             sys.exit(1)
 
-        if reticulum.drop_all_via(destination_hash):
-            print("Dropped all paths via "+RNS.prettyhexrep(destination_hash))
+        if reticulum.drop_all_via(destination_hash): print("Dropped all paths via "+RNS.prettyhexrep(destination_hash))
         else:
             print("Unable to drop paths via "+RNS.prettyhexrep(destination_hash)+". Does the transport instance exist?")
             sys.exit(1)
@@ -334,18 +430,15 @@ def program_setup(configdir, table, rates, drop, destination_hexhash, verbosity,
     else:
         if remote_link:
             if not no_output:
-                print("\r                                                          \r", end="")
+                print(output_rst_str, end="")
                 print("Requesting paths on remote instances not implemented")
             exit(255)
 
         try:
             dest_len = (RNS.Reticulum.TRUNCATED_HASHLENGTH//8)*2
-            if len(destination_hexhash) != dest_len:
-                raise ValueError("Destination length is invalid, must be {hex} hexadecimal characters ({byte} bytes).".format(hex=dest_len, byte=dest_len//2))
-            try:
-                destination_hash = bytes.fromhex(destination_hexhash)
-            except Exception as e:
-                raise ValueError("Invalid destination entered. Check your input.")
+            if len(destination_hexhash) != dest_len: raise ValueError("Destination length is invalid, must be {hex} hexadecimal characters ({byte} bytes).".format(hex=dest_len, byte=dest_len//2))
+            try: destination_hash = bytes.fromhex(destination_hexhash)
+            except Exception as e: raise ValueError("Invalid destination entered. Check your input.")
         except Exception as e:
             print(str(e))
             sys.exit(1)
@@ -374,166 +467,57 @@ def program_setup(configdir, table, rates, drop, destination_hexhash, verbosity,
                 next_hop = RNS.prettyhexrep(next_hop_bytes)
                 next_hop_interface = reticulum.get_next_hop_if_name(destination_hash)
 
-                if hops != 1:
-                    ms = "s"
-                else:
-                    ms = ""
+                if hops != 1: ms = "s"
+                else: ms = ""
 
                 print("\rPath found, destination "+RNS.prettyhexrep(destination_hash)+" is "+str(hops)+" hop"+ms+" away via "+next_hop+" on "+next_hop_interface)
         else:
             print("\r                                                       \rPath not found")
             sys.exit(1)
 
-    
 
 def main():
     try:
-        parser = argparse.ArgumentParser(description="Reticulum Path Discovery Utility")
-
-        parser.add_argument("--config",
-            action="store",
-            default=None,
-            help="path to alternative Reticulum config directory",
-            type=str
-        )
-
-        parser.add_argument(
-            "--version",
-            action="version",
-            version="rnpath {version}".format(version=__version__)
-        )
-
-        parser.add_argument(
-            "-t",
-            "--table",
-            action="store_true",
-            help="show all known paths",
-            default=False
-        )
-
-        parser.add_argument(
-            "-m",
-            "--max",
-            action="store",
-            metavar="hops",
-            type=int,
-            help="maximum hops to filter path table by",
-            default=None
-        )
-
-        parser.add_argument(
-            "-r",
-            "--rates",
-            action="store_true",
-            help="show announce rate info",
-            default=False
-        )
-
-        parser.add_argument(
-            "-d",
-            "--drop",
-            action="store_true",
-            help="remove the path to a destination",
-            default=False
-        )
-
-        parser.add_argument(
-            "-D",
-            "--drop-announces",
-            action="store_true",
-            help="drop all queued announces",
-            default=False
-        )
-
-        parser.add_argument(
-            "-x", "--drop-via",
-            action="store_true",
-            help="drop all paths via specified transport instance",
-            default=False
-        )
-
-        parser.add_argument(
-            "-w",
-            action="store",
-            metavar="seconds",
-            type=float,
-            help="timeout before giving up",
-            default=RNS.Transport.PATH_REQUEST_TIMEOUT
-        )
-
-        parser.add_argument(
-            "-R",
-            action="store",
-            metavar="hash",
-            help="transport identity hash of remote instance to manage",
-            default=None,
-            type=str
-        )
-
-        parser.add_argument(
-            "-i",
-            action="store",
-            metavar="path",
-            help="path to identity used for remote management",
-            default=None,
-            type=str
-        )
-
-        parser.add_argument(
-            "-W",
-            action="store",
-            metavar="seconds",
-            type=float,
-            help="timeout before giving up on remote queries",
-            default=RNS.Transport.PATH_REQUEST_TIMEOUT
-        )
-        
-        parser.add_argument(
-            "-j",
-            "--json",
-            action="store_true",
-            help="output in JSON format",
-            default=False
-        )
-
-        parser.add_argument(
-            "destination",
-            nargs="?",
-            default=None,
-            help="hexadecimal hash of the destination",
-            type=str
-        )
-
+        parser = argparse.ArgumentParser(description="Reticulum Path Management Utility")
+        parser.add_argument("--config", action="store", default=None, help="path to alternative Reticulum config directory", type=str)
+        parser.add_argument("--version", action="version", version="rnpath {version}".format(version=__version__))
+        parser.add_argument("-t", "--table", action="store_true", help="show all known paths", default=False)
+        parser.add_argument("-m", "--max", action="store", metavar="hops", type=int, help="maximum hops to filter path table by", default=None)
+        parser.add_argument("-r", "--rates", action="store_true", help="show announce rate info", default=False)
+        parser.add_argument("-d", "--drop", action="store_true", help="remove the path to a destination", default=False)
+        parser.add_argument("-D", "--drop-announces", action="store_true", help="drop all queued announces", default=False)
+        parser.add_argument("-x", "--drop-via", action="store_true", help="drop all paths via specified transport instance", default=False)
+        parser.add_argument("-w", action="store", metavar="seconds", type=float, help="timeout before giving up", default=RNS.Transport.PATH_REQUEST_TIMEOUT)
+        parser.add_argument("-R", action="store", metavar="hash", help="transport identity hash of remote instance to manage", default=None, type=str)
+        parser.add_argument("-i", action="store", metavar="path", help="path to identity used for remote management", default=None, type=str)
+        parser.add_argument("-W", action="store", metavar="seconds", type=float, help="timeout before giving up on remote queries", default=RNS.Transport.PATH_REQUEST_TIMEOUT)
+        parser.add_argument("-b", "--blackholed", action="store_true", help="list blackholed identities", default=False)
+        parser.add_argument("-B", "--blackhole", action="store_true", help="blackhole identity", default=False)
+        parser.add_argument("-U", "--unblackhole", action="store_true", help="unblackhole identity", default=False)
+        parser.add_argument(      "--duration", action="store", type=float, help="duration of blackhole enforcement in hours", default=None)
+        parser.add_argument(      "--reason", action="store", type=str, help="reason for blackholing identity", default=None)
+        parser.add_argument("-p", "--blackholed-list", action="store_true", help="view published blackhole list for remote transport instance", default=False)
+        parser.add_argument("-j", "--json", action="store_true", help="output in JSON format", default=False)
+        parser.add_argument("destination", nargs="?", default=None, help="hexadecimal hash of the destination", type=str)
+        parser.add_argument("list_filter", nargs="?", default=None, help="filter for remote blackhole list view", type=str)
         parser.add_argument('-v', '--verbose', action='count', default=0)
         
         args = parser.parse_args()
 
-        if args.config:
-            configarg = args.config
-        else:
-            configarg = None
+        if args.config: configarg = args.config
+        else: configarg = None
 
-        if not args.drop_announces and not args.table and not args.rates and not args.destination and not args.drop_via:
+        if not args.drop_announces and not args.table and not args.rates and not args.destination and not args.drop_via and not args.blackholed:
             print("")
             parser.print_help()
             print("")
         else:
-            program_setup(
-                configdir = configarg,
-                table = args.table,
-                rates = args.rates,
-                drop = args.drop,
-                destination_hexhash = args.destination,
-                verbosity = args.verbose,
-                timeout = args.w,
-                drop_queues = args.drop_announces,
-                drop_via = args.drop_via,
-                max_hops = args.max,
-                remote=args.R,
-                management_identity=args.i,
-                remote_timeout=args.W,
-                json=args.json,
-            )
+            program_setup(configdir = configarg, table = args.table, rates = args.rates, drop = args.drop, destination_hexhash = args.destination,
+                          verbosity = args.verbose, timeout = args.w, drop_queues = args.drop_announces, drop_via = args.drop_via, max_hops = args.max,
+                          remote=args.R, management_identity=args.i, remote_timeout=args.W, blackholed=args.blackholed, blackhole=args.blackhole,
+                          unblackhole=args.unblackhole, blackhole_duration=args.duration, blackhole_reason=args.reason, remote_blackhole_list=args.blackholed_list,
+                          remote_blackhole_list_filter=args.list_filter, json=args.json)
+
             sys.exit(0)
 
     except KeyboardInterrupt:
@@ -543,38 +527,23 @@ def main():
 def pretty_date(time=False):
     from datetime import datetime
     now = datetime.now()
-    if type(time) is int:
-        diff = now - datetime.fromtimestamp(time)
-    elif isinstance(time,datetime):
-        diff = now - time
-    elif not time:
-        diff = now - now
+    if type(time) is int: diff = now - datetime.fromtimestamp(time)
+    elif isinstance(time,datetime): diff = now - time
+    elif not time: diff = now - now
     second_diff = diff.seconds
     day_diff = diff.days
-    if day_diff < 0:
-        return ''
+    if day_diff < 0: return ''
     if day_diff == 0:
-        if second_diff < 10:
-            return str(second_diff) + " seconds"
-        if second_diff < 60:
-            return str(second_diff) + " seconds"
-        if second_diff < 120:
-            return "1 minute"
-        if second_diff < 3600:
-            return str(int(second_diff / 60)) + " minutes"
-        if second_diff < 7200:
-            return "an hour"
-        if second_diff < 86400:
-            return str(int(second_diff / 3600)) + " hours"
-    if day_diff == 1:
-        return "1 day"
-    if day_diff < 7:
-        return str(day_diff) + " days"
-    if day_diff < 31:
-        return str(int(day_diff / 7)) + " weeks"
-    if day_diff < 365:
-        return str(int(day_diff / 30)) + " months"
+        if second_diff < 10: return str(second_diff) + " seconds"
+        if second_diff < 60: return str(second_diff) + " seconds"
+        if second_diff < 120: return "1 minute"
+        if second_diff < 3600: return str(int(second_diff / 60)) + " minutes"
+        if second_diff < 7200: return "an hour"
+        if second_diff < 86400: return str(int(second_diff / 3600)) + " hours"
+    if day_diff == 1: return "1 day"
+    if day_diff < 7: return str(day_diff) + " days"
+    if day_diff < 31: return str(int(day_diff / 7)) + " weeks"
+    if day_diff < 365: return str(int(day_diff / 30)) + " months"
     return str(int(day_diff / 365)) + " years"
 
-if __name__ == "__main__":
-    main()
+if __name__ == "__main__": main()

RNS/Utilities/rnpkg.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+
+# Reticulum License
+#
+# Copyright (c) 2016-2025 Mark Qvist
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# - The Software shall not be used in any kind of system which includes amongst
+#   its functions the ability to purposefully do harm to human beings.
+#
+# - The Software shall not be used, directly or indirectly, in the creation of
+#   an artificial intelligence, machine learning or language model training
+#   dataset, including but not limited to any use that contributes to the
+#   training or development of such a model or algorithm.
+#
+# - The above copyright notice and this permission notice shall be included in
+#   all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+import RNS
+import argparse
+import time
+
+from RNS._version import __version__
+
+def program_setup(configdir, verbosity = 0, quietness = 0, service = False):
+    targetverbosity = verbosity-quietness
+
+    if service:
+        targetlogdest  = RNS.LOG_FILE
+        targetverbosity = None
+    else:
+        targetlogdest  = RNS.LOG_STDOUT
+
+    reticulum = RNS.Reticulum(configdir=configdir, verbosity=targetverbosity, logdest=targetlogdest)
+    exit(0)
+
+def main():
+    try:
+        parser = argparse.ArgumentParser(description="Reticulum Meta Package Manager")
+        parser.add_argument("--config", action="store", default=None, help="path to alternative Reticulum config directory", type=str)
+        parser.add_argument('-v', '--verbose', action='count', default=0)
+        parser.add_argument('-q', '--quiet', action='count', default=0)
+        parser.add_argument("--exampleconfig", action='store_true', default=False, help="print verbose configuration example to stdout and exit")
+        parser.add_argument("--version", action="version", version="rnpkg {version}".format(version=__version__))
+        
+        args = parser.parse_args()
+
+        if args.exampleconfig:
+            print(__example_rnpkg_config__)
+            exit()
+
+        if args.config: configarg = args.config
+        else: configarg = None
+
+        program_setup(configdir = configarg, verbosity=args.verbose, quietness=args.quiet)
+
+    except KeyboardInterrupt:
+        print("")
+        exit()
+
+__example_rnpkg_config__ = '''# This is an example package manager configuration file.
+'''
+
+if __name__ == "__main__": main()

RNS/Utilities/rnsd.py

@@ -160,6 +160,55 @@ instance_name = default
 # remote_management_allowed = 9fb6d773498fb3feda407ed8ef2c3229, 2d882c5586e548d79b5af27bca1776dc
 
 
+# For easier management, discovery and configuration of
+# networks with many individual transport instances,
+# you can specify a network identity to be used across
+# a set of instances. If sending interface discovery
+# announces, these will all be signed by the specified
+# network identity, and other nodes discovering your
+# interfaces will be able to identify that they belong
+# to the same network, even though they exist on different
+# transport nodes.
+
+# network_identity = ~/.reticulum/storage/identity/network
+
+
+# You can configure whether Reticulum should discover
+# available interfaces from other Transport Instances over
+# the network. If this option is enabled, Reticulum will
+# collect interface information discovered from the network.
+
+# discover_interfaces = No
+
+
+# If you only want to discover interfaces from specific
+# networks, you can provide a list of network identities
+# from which to discover interfaces. If this option is not
+# provided, interfaces will be discovered from all transport
+# instances on all connected networks.
+
+# interface_discovery_sources = 78616ff7c4b8d3886d67d494b440f333, cb127015e13aa6ea1e0a606cdc9123d0
+
+
+# It is possible to automatically bring up and connect new
+# interfaces discovered over the network. This option is
+# disabled by default, but allows you to specify a maximum
+# number of discovered interfaces to automatically connect.
+# Additionally, if this option is enabled, Reticulum will
+# also try to autoconnect available auto-discovered inter-
+# faces on startup, up to the maximum number specified.
+
+# autoconnect_discovered_interfaces = 0
+
+
+# To prevent interface discovery spamming, a valid crypto-
+# graphic stamp is required per announced interface. You
+# can configure the minimum required value to accept as
+# valid for discovered interfaces.
+
+# required_discovery_value = 14
+
+
 # You can configure Reticulum to panic and forcibly close
 # if an unrecoverable interface error occurs, such as the
 # hardware device for an interface disappearing. This is
@@ -180,6 +229,26 @@ instance_name = default
 # respond_to_probes = No
 
 
+# You can publish your local list of blackholed identities
+# for other transport instances to use for automatic,
+# network-wide blackhole management.
+
+# publish_blackhole = No
+
+# List of remote transport identities from which to auto-
+# matically source lists of blackholed identities.
+#
+# If you're connecting to a large external network, you
+# can use one or more external blackhole list to block
+# spammy and excessive announces onto your network. This
+# funtionality is especially useful if you're hosting public
+# entrypoints or gateways. The list source below provides a
+# functional example, but better, more timely maintained
+# lists probably exist in the community.
+
+# blackhole_sources = 521c87a83afb8f29e4455e77930b973b
+
+
 [logging]
 # Valid log levels are 0 through 7:
 #   0: Log only critical information

RNS/Utilities/rnsh/__init__.py

@@ -0,0 +1,41 @@
+#         Based on the original rnsh program by Aaron Heise (@acehoss)
+# https://github.com/acehoss/rnsh - MIT License - Copyright (c) 2023 Aaron Heise
+#     This version of rnsh is included in RNS under the Reticulum License
+#
+# Reticulum License
+#
+# Copyright (c) 2016-2026 Mark Qvist
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# - The Software shall not be used in any kind of system which includes amongst
+#   its functions the ability to purposefully do harm to human beings.
+#
+# - The Software shall not be used, directly or indirectly, in the creation of
+#   an artificial intelligence, machine learning or language model training
+#   dataset, including but not limited to any use that contributes to the
+#   training or development of such a model or algorithm.
+#
+# - The above copyright notice and this permission notice shall be included in
+#   all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+from ._version import __version__
+
+import os
+module_abs_filename = os.path.abspath(__file__)
+module_dir = os.path.dirname(module_abs_filename)
+
+def _get_version(): return __version__

RNS/Utilities/rnsh/_version.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

RNS/Utilities/rnsh/args.py

@@ -0,0 +1,93 @@
+#         Based on the original rnsh program by Aaron Heise (@acehoss)
+# https://github.com/acehoss/rnsh - MIT License - Copyright (c) 2023 Aaron Heise
+#     This version of rnsh is included in RNS under the Reticulum License
+#
+# Reticulum License
+#
+# Copyright (c) 2016-2026 Mark Qvist
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# - The Software shall not be used in any kind of system which includes amongst
+#   its functions the ability to purposefully do harm to human beings.
+#
+# - The Software shall not be used, directly or indirectly, in the creation of
+#   an artificial intelligence, machine learning or language model training
+#   dataset, including but not limited to any use that contributes to the
+#   training or development of such a model or algorithm.
+#
+# - The above copyright notice and this permission notice shall be included in
+#   all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+import argparse
+import sys
+
+from RNS.Utilities.rnsh._version import __version__ as __rnsh_version__
+from RNS._version import __version__
+
+DEFAULT_SERVICE_NAME = "default"
+
+def setup_argument_parser():
+    parser = argparse.ArgumentParser(description="Reticulum Remote Shell Utility", epilog="When specifying a command to execute, separate rnsh\noptions from the command and its arguments with --\n\nFor example:\n  rnsh -l -- /bin/bash --login\n  rnsh <destination> -- ls -la /tmp", formatter_class=argparse.RawDescriptionHelpFormatter)
+
+    # Common options
+    parser.add_argument("--config", "-c", action="store", default=None, help="path to alternative Reticulum config directory", type=str)
+    parser.add_argument("--identity", "-i", action="store", default=None, help="path to identity file to use", type=str)
+    parser.add_argument("-v", "--verbose", action="count", default=0, help="increase verbosity")
+    parser.add_argument("-q", "--quiet", action="count", default=0, help="decrease verbosity")
+    parser.add_argument("-p", "--print-identity", action="store_true", default=False, help="print identity and destination info and exit")
+    parser.add_argument("--version", action="version", version="rnsh {rv} (protocol {pv})".format(rv=__version__, pv=__rnsh_version__))
+
+    # Listener options
+    parser.add_argument("-l", "--listen", action="store_true", default=False, help="listen (server) mode; any command specified after -- will be used as the default command when the initiator does not provide one or when remote command execution is disabled; if no command is specified, the default shell of the user running rnsh will be used")
+    parser.add_argument("-s", "--service", action="store", default=None, help="service name for identity file if not the default", type=str)
+    parser.add_argument("-b", "--announce",action="store", default=None,help="announce on startup and every PERIOD seconds; specify 0 to announce on startup only",metavar="PERIOD", type=int)
+    parser.add_argument("-a", "--allowed", action="append", default=None, metavar="HASH", type=str, help="allow this identity to connect (may be specified multiple times); allowed identities can also be specified in ~/.rnsh/allowed_identities or ~/.config/rnsh/allowed_identities, one hash per line")
+    parser.add_argument("-n", "--no-auth", action="store_true", default=False, help="disable authentication (allow any identity to connect)")
+    parser.add_argument("-A", "--remote-command-as-args", action="store_true", default=False, help="concatenate remote command to the argument list of the default program or shell")
+    parser.add_argument("-C", "--no-remote-command", action="store_true", default=False, help="disable executing command lines received from the remote initiator")
+
+    # Initiator options
+    parser.add_argument("-N", "--no-id", action="store_true", default=False, help="disable identity announcement on connect")
+    parser.add_argument("-m", "--mirror", action="store_true", default=False, help="return with the exit code of the remote process")
+    parser.add_argument("-w", "--timeout", action="store", default=None, help="connect and request timeout in seconds", metavar="SECONDS", type=float)
+
+    parser.add_argument("destination", nargs="?", default=None, help="hexadecimal hash of the destination to connect to", type=str)
+
+    return parser
+
+
+def parse_arguments(argv=None):
+    if argv is None: argv = sys.argv[1:]
+
+    # Split at -- to separate rnsh options from the command to execute.
+    # Everything before -- (or the entire argv if no --) goes to argparse.
+    # Everything after -- becomes the command list.
+    try:
+        split_idx = argv.index("--")
+        rnsh_argv = argv[:split_idx]
+        command = argv[split_idx + 1:]
+    except ValueError:
+        rnsh_argv = argv
+        command = []
+
+    parser = setup_argument_parser()
+    args = parser.parse_args(rnsh_argv)
+    args.command = command
+
+    if args.listen and not args.service: args.service = DEFAULT_SERVICE_NAME
+
+    return args, parser

RNS/Utilities/rnsh/exception.py

@@ -0,0 +1,60 @@
+#         Based on the original rnsh program by Aaron Heise (@acehoss)
+# https://github.com/acehoss/rnsh - MIT License - Copyright (c) 2023 Aaron Heise
+#     This version of rnsh is included in RNS under the Reticulum License
+#
+# Reticulum License
+#
+# Copyright (c) 2016-2026 Mark Qvist
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# - The Software shall not be used in any kind of system which includes amongst
+#   its functions the ability to purposefully do harm to human beings.
+#
+# - The Software shall not be used, directly or indirectly, in the creation of
+#   an artificial intelligence, machine learning or language model training
+#   dataset, including but not limited to any use that contributes to the
+#   training or development of such a model or algorithm.
+#
+# - The above copyright notice and this permission notice shall be included in
+#   all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+import contextlib
+from contextlib import AbstractContextManager
+import logging
+import sys
+
+
+class permit(AbstractContextManager):
+    """Context manager to allow specified exceptions
+
+    The specified exceptions will be allowed to bubble up. Other
+    exceptions are suppressed.
+
+    After a non-matching exception is suppressed, execution proceeds
+    with the next statement following the with statement.
+
+         with allow(KeyboardInterrupt):
+             time.sleep(300)
+         # Execution still resumes here if no KeyboardInterrupt
+    """
+
+    def __init__(self, *exceptions): self._exceptions = exceptions
+
+    def __enter__(self): pass
+
+    def __exit__(self, exctype, excinst, exctb):
+        return exctype is not None and not issubclass(exctype, self._exceptions)

RNS/Utilities/rnsh/helpers.py

@@ -0,0 +1,59 @@
+#         Based on the original rnsh program by Aaron Heise (@acehoss)
+# https://github.com/acehoss/rnsh - MIT License - Copyright (c) 2023 Aaron Heise
+#     This version of rnsh is included in RNS under the Reticulum License
+#
+# Reticulum License
+#
+# Copyright (c) 2016-2026 Mark Qvist
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# - The Software shall not be used in any kind of system which includes amongst
+#   its functions the ability to purposefully do harm to human beings.
+#
+# - The Software shall not be used, directly or indirectly, in the creation of
+#   an artificial intelligence, machine learning or language model training
+#   dataset, including but not limited to any use that contributes to the
+#   training or development of such a model or algorithm.
+#
+# - The above copyright notice and this permission notice shall be included in
+#   all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+import asyncio
+import time
+
+def bitwise_or_if(value: int, condition: bool, orval: int):
+    if not condition: return value
+    return value | orval
+
+def check_and(value: int, andval: int) -> bool:
+    return (value & andval) > 0
+
+class SleepRate:
+    def __init__(self, target_period: float):
+        self.target_period = target_period
+        self.last_wake = time.time()
+
+    def next_sleep_time(self) -> float:
+        old_last_wake = self.last_wake
+        self.last_wake = time.time()
+        next_wake = max(old_last_wake + 0.01, self.last_wake)
+        sleep_for = next_wake - self.last_wake
+        return sleep_for if sleep_for > 0 else 0
+
+    async def sleep_async(self): await asyncio.sleep(self.next_sleep_time())
+
+    def sleep_block(self): time.sleep(self.next_sleep_time())

RNS/Utilities/rnsh/initiator.py

@@ -0,0 +1,484 @@
+#         Based on the original rnsh program by Aaron Heise (@acehoss)
+# https://github.com/acehoss/rnsh - MIT License - Copyright (c) 2023 Aaron Heise
+#     This version of rnsh is included in RNS under the Reticulum License
+#
+# Reticulum License
+#
+# Copyright (c) 2016-2026 Mark Qvist
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# - The Software shall not be used in any kind of system which includes amongst
+#   its functions the ability to purposefully do harm to human beings.
+#
+# - The Software shall not be used, directly or indirectly, in the creation of
+#   an artificial intelligence, machine learning or language model training
+#   dataset, including but not limited to any use that contributes to the
+#   training or development of such a model or algorithm.
+#
+# - The above copyright notice and this permission notice shall be included in
+#   all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import enum
+import functools
+import os
+import queue
+import shlex
+import signal
+import sys
+import termios
+import threading
+import time
+import tty
+from typing import Callable, TypeVar
+import RNS
+import RNS.Utilities.rnsh.exception as exception
+import RNS.Utilities.rnsh.process as process
+import RNS.Utilities.rnsh.retry as retry
+import RNS.Utilities.rnsh.session as session
+import re
+import contextlib
+
+import pwd
+import bz2
+import RNS.Utilities.rnsh.protocol as protocol
+import RNS.Utilities.rnsh.helpers as helpers
+import RNS.Utilities.rnsh.rnsh as rnsh
+
+_identity = None
+_reticulum = None
+_cmd: [str] | None = None
+DATA_AVAIL_MSG = "data available"
+_finished: asyncio.Event = None
+_retry_timer: retry.RetryThread | None = None
+_destination: RNS.Destination | None = None
+_loop: asyncio.AbstractEventLoop | None = None
+
+
+async def _check_finished(timeout: float = 0):
+    return _finished is not None and await process.event_wait(_finished, timeout=timeout)
+
+def _sigint_handler(sig, loop):
+    global _finished
+    RNS.log(f"{signal.Signals(sig).name}", RNS.LOG_DEBUG)
+    if _finished is not None: _finished.set()
+    else: raise KeyboardInterrupt()
+
+async def _spin_tty(until=None, msg=None, timeout=None):
+    i = 0
+    syms = "⢄⢂⢁⡁⡈⡐⡠"
+    if timeout != None: timeout = time.time()+timeout
+
+    print(msg+"  ", end=" ")
+    while (timeout == None or time.time()<timeout) and not until():
+        await asyncio.sleep(0.1)
+        print(("\b\b"+syms[i]+" "), end="")
+        sys.stdout.flush()
+        i = (i+1)%len(syms)
+
+    print("\r"+" "*len(msg)+"  \r", end="")
+
+    if timeout != None and time.time() > timeout: return False
+    else:                                         return True
+
+
+async def _spin_pipe(until: callable = None, msg=None, timeout: float | None = None) -> bool:
+    if timeout is not None: timeout += time.time()
+
+    while (timeout is None or time.time() < timeout) and not until():
+        if await _check_finished(0.1): raise asyncio.CancelledError()
+    
+    if timeout is not None and time.time() > timeout: return False
+    else: return True
+
+async def _spin(until: callable = None, msg=None, timeout: float | None = None, quiet: bool = False) -> bool:
+    if not quiet and os.isatty(1): return await _spin_tty(until, msg, timeout)
+    else:                          return await _spin_pipe(until, msg, timeout)
+
+_link: RNS.Link | None = None
+_remote_exec_grace = 2.0
+_pq = queue.Queue()
+
+
+class InitiatorState(enum.IntEnum):
+    IS_INITIAL      = 0
+    IS_LINKED     = 1
+    IS_WAIT_VERS  = 2
+    IS_RUNNING    = 3
+    IS_TERMINATE  = 4
+    IS_TEARDOWN   = 5
+
+def _client_link_closed(link):
+    if _finished: _finished.set()
+
+def _client_message_handler(message: RNS.MessageBase): _pq.put(message)
+
+def compute_target_rns_loglevel(verbosity: int, quietness: int, base_level: int = RNS.LOG_INFO) -> int:
+    try:
+        target = int(base_level) + int(verbosity) - int(quietness)
+        if target < RNS.LOG_CRITICAL: target = RNS.LOG_CRITICAL
+        if target > RNS.LOG_DEBUG:    target = RNS.LOG_DEBUG
+        return target
+    
+    except Exception: return base_level
+
+
+class RemoteExecutionError(Exception):
+    def __init__(self, msg): self.msg = msg
+
+
+async def _initiate_link(configdir, rnsconfigdir, identitypath=None, verbosity=0, quietness=0, noid=False, destination=None,
+                         timeout=RNS.Transport.PATH_REQUEST_TIMEOUT):
+    global _identity, _reticulum, _link, _destination, _remote_exec_grace
+
+    dest_len = (RNS.Reticulum.TRUNCATED_HASHLENGTH // 8) * 2
+    if len(destination) != dest_len:
+        raise RemoteExecutionError(
+            "Allowed destination length is invalid, must be {hex} hexadecimal characters ({byte} bytes).".format(
+                hex=dest_len, byte=dest_len // 2))
+    try:
+        destination_hash = bytes.fromhex(destination)
+    except Exception as e:
+        raise RemoteExecutionError("Invalid destination entered. Check your input.")
+
+    if _reticulum is None:
+        targetloglevel = compute_target_rns_loglevel(verbosity, quietness, RNS.LOG_ERROR)
+        RNS.logfile = os.path.join(configdir, "logfile")
+        _reticulum = RNS.Reticulum(configdir=rnsconfigdir, loglevel=targetloglevel, logdest=RNS.LOG_FILE)
+
+    if _identity is None:
+        _identity = rnsh.prepare_identity(identitypath)
+
+    if not RNS.Transport.has_path(destination_hash):
+        RNS.Transport.request_path(destination_hash)
+        RNS.log(f"Requesting path...", RNS.LOG_INFO)
+        if not await _spin(until=lambda: RNS.Transport.has_path(destination_hash), msg="Requesting path...",
+                           timeout=timeout, quiet=quietness > 0):
+            raise RemoteExecutionError("Path not found")
+
+    if _destination is None:
+        listener_identity = RNS.Identity.recall(destination_hash)
+        _destination = RNS.Destination(
+            listener_identity,
+            RNS.Destination.OUT,
+            RNS.Destination.SINGLE,
+            rnsh.APP_NAME
+        )
+
+    if _link is None or _link.status == RNS.Link.PENDING:
+        RNS.log("No link", RNS.LOG_DEBUG)
+        _link = RNS.Link(_destination)
+        _link.did_identify = False
+
+        _link.set_link_closed_callback(_client_link_closed)
+
+    RNS.log(f"Establishing link...", RNS.LOG_VERBOSE)
+    if not await _spin(until=lambda: _link.status == RNS.Link.ACTIVE, msg="Establishing link...",
+                       timeout=timeout, quiet=quietness > 0):
+        raise RemoteExecutionError("Could not establish link with " + RNS.prettyhexrep(destination_hash))
+
+    RNS.log("Have link", RNS.LOG_DEBUG)
+    if not noid and not _link.did_identify:
+        # Delay a tiny bit to allow listener to fully enter WAIT_IDENT state
+        await asyncio.sleep(min(1, _link.rtt * 1.1 + 0.05))
+        _link.identify(_identity)
+        _link.did_identify = True
+
+
+async def _handle_error(errmsg: RNS.MessageBase):
+    if isinstance(errmsg, protocol.ErrorMessage):
+        with contextlib.suppress(Exception):
+            if _link and _link.status == RNS.Link.ACTIVE:
+                _link.teardown()
+        await asyncio.sleep(0.1)
+        raise RemoteExecutionError(f"Remote error: {errmsg.msg}")
+
+
+async def initiate(configdir: str, rnsconfigdir:str, identitypath: str, verbosity: int, quietness: int, noid: bool, destination: str,
+                   timeout: float, command: [str] | None = None):
+    global _finished, _link
+    with process.TTYRestorer(sys.stdin.fileno()) as ttyRestorer:
+        loop = asyncio.get_running_loop()
+        state = InitiatorState.IS_INITIAL
+        data_buffer = bytearray(sys.stdin.buffer.read()) if not os.isatty(sys.stdin.fileno()) else bytearray()
+        line_buffer = bytearray()
+
+        await _initiate_link(configdir=configdir,
+                             rnsconfigdir=rnsconfigdir,
+                             identitypath=identitypath,
+                             verbosity=verbosity,
+                             quietness=quietness,
+                             noid=noid,
+                             destination=destination,
+                             timeout=timeout)
+
+        if not _link or _link.status not in [RNS.Link.ACTIVE, RNS.Link.PENDING]:
+            return 255
+
+        state = InitiatorState.IS_LINKED
+        outlet = session.RNSOutlet(_link)
+        channel = _link.get_channel()
+        protocol.register_message_types(channel)
+        channel.add_message_handler(_client_message_handler)
+
+        # Next step after linking and identifying: send version
+        # if not await _spin(lambda: messenger.is_outlet_ready(outlet), timeout=5, quiet=quietness > 0):
+        #     print("Error bringing up link")
+        #     return 253
+
+        channel.send(protocol.VersionInfoMessage())
+        try:
+            vm = _pq.get(timeout=max(outlet.rtt * 20, 5))
+            await _handle_error(vm)
+            if not isinstance(vm, protocol.VersionInfoMessage):
+                raise Exception("Invalid message received")
+            RNS.log(f"Server version info: sw {vm.sw_version} prot {vm.protocol_version}", RNS.LOG_DEBUG)
+            state = InitiatorState.IS_RUNNING
+        except queue.Empty:
+            print("Protocol error")
+            return 254
+
+        winch = False
+        def sigwinch_handler():
+            nonlocal winch
+            winch = True
+
+        esc = False
+        pre_esc = True
+        line_mode = False
+        line_flush = False
+        blind_write_count = 0
+        flush_chars = ["\x01", "\x03", "\x04", "\x05", "\x0c", "\x11", "\x13", "\x15", "\x19", "\t", "\x1A", "\x1B"]
+        def handle_escape(b):
+            nonlocal line_mode
+            if b == "?":
+                os.write(1, "\n\r\n\rSupported rnsh escape sequences:".encode("utf-8"))
+                os.write(1, "\n\r  ~~  Send the escape character by typing it twice".encode("utf-8"))
+                os.write(1, "\n\r  ~.  Terminate session and exit immediately".encode("utf-8"))
+                os.write(1, "\n\r  ~L  Toggle line-interactive mode".encode("utf-8"))
+                os.write(1, "\n\r  ~?  Display this quick reference\n\r".encode("utf-8"))
+                os.write(1, "\n\r(Escape sequences are only recognized immediately after newline)\n\r".encode("utf-8"))
+                return None
+            elif b == ".":
+                _link.teardown()
+                return None
+            elif b == "L":
+                line_mode = not line_mode
+                if line_mode:
+                    os.write(1, "\n\rLine-interactive mode enabled\n\r".encode("utf-8"))
+                else:
+                    os.write(1, "\n\rLine-interactive mode disabled\n\r".encode("utf-8"))
+                return None
+
+            return b
+
+        stdin_eof = False
+        def stdin():
+            nonlocal stdin_eof, pre_esc, esc, line_mode
+            nonlocal line_flush, blind_write_count
+            try:
+                in_data = process.tty_read(sys.stdin.fileno())
+                if in_data is not None:
+                    data = bytearray()
+                    for b in bytes(in_data):
+                        c = chr(b)
+                        if c == "\r":
+                            pre_esc = True
+                            line_flush = True
+                            data.append(b)
+                        elif line_mode and c in flush_chars:
+                            pre_esc = False
+                            line_flush = True
+                            data.append(b)
+                        elif line_mode and (c == "\b" or c == "\x7f"):
+                            pre_esc = False
+                            if len(line_buffer)>0:
+                                line_buffer.pop(-1)
+                                blind_write_count -= 1
+                                os.write(1, "\b \b".encode("utf-8"))
+                        elif pre_esc == True and c == "~":
+                            pre_esc = False
+                            esc = True
+                        elif esc == True:
+                            ret = handle_escape(c)
+                            if ret != None:
+                                if ret != "~":
+                                    data.append(ord("~"))
+                                data.append(ord(ret))
+                            esc = False
+                        else:
+                            pre_esc = False
+                            data.append(b)
+
+                    if not line_mode:
+                        data_buffer.extend(data)
+                    else:
+                        line_buffer.extend(data)
+                        if line_flush:
+                            data_buffer.extend(line_buffer)
+                            line_buffer.clear()
+                            os.write(1, ("\b \b"*blind_write_count).encode("utf-8"))
+                            line_flush = False
+                            blind_write_count = 0
+                        else:
+                            os.write(1, data)
+                            blind_write_count += len(data)
+
+            except EOFError:
+                if os.isatty(0):
+                    data_buffer.extend(process.CTRL_D)
+                stdin_eof = True
+                process.tty_unset_reader_callbacks(sys.stdin.fileno())
+
+        process.tty_add_reader_callback(sys.stdin.fileno(), stdin)
+
+        tcattr = None
+        rows, cols, hpix, vpix = (None, None, None, None)
+        try:
+            tcattr = termios.tcgetattr(0)
+            rows, cols, hpix, vpix = process.tty_get_winsize(0)
+        except:
+            try:
+                tcattr = termios.tcgetattr(1)
+                rows, cols, hpix, vpix = process.tty_get_winsize(1)
+            except:
+                try:
+                    tcattr = termios.tcgetattr(2)
+                    rows, cols, hpix, vpix = process.tty_get_winsize(2)
+                except:
+                    pass
+
+        await _spin(lambda: channel.is_ready_to_send(), "Waiting for channel...", 1, quietness > 0)
+        channel.send(protocol.ExecuteCommandMesssage(cmdline=command,
+                                                     pipe_stdin=not os.isatty(0),
+                                                     pipe_stdout=not os.isatty(1),
+                                                     pipe_stderr=not os.isatty(2),
+                                                     tcflags=tcattr,
+                                                     term=os.environ.get("TERM", None),
+                                                     rows=rows,
+                                                     cols=cols,
+                                                     hpix=hpix,
+                                                     vpix=vpix))
+
+        loop.add_signal_handler(signal.SIGWINCH, sigwinch_handler)
+        _finished = asyncio.Event()
+        loop.add_signal_handler(signal.SIGINT, functools.partial(_sigint_handler, signal.SIGINT, loop))
+        loop.add_signal_handler(signal.SIGTERM, functools.partial(_sigint_handler, signal.SIGTERM, loop))
+        mdu = _link.MDU - 16
+        sent_eof = False
+        last_winch = time.time()
+        sleeper = helpers.SleepRate(0.01)
+        processed = False
+        while not await _check_finished() and state in [InitiatorState.IS_RUNNING]:
+            try:
+                try:
+                    message = _pq.get(timeout=sleeper.next_sleep_time() if not processed else 0.0005)
+                    await _handle_error(message)
+                    processed = True
+                    if isinstance(message, protocol.StreamDataMessage):
+                        if message.stream_id == protocol.StreamDataMessage.STREAM_ID_STDOUT:
+                            if message.data and len(message.data) > 0:
+                                ttyRestorer.raw()
+                                RNS.log(f"stdout: {message.data}", RNS.LOG_DEBUG)
+                                os.write(1, message.data)
+                                sys.stdout.flush()
+                            if message.eof:
+                                os.close(1)
+                        if message.stream_id == protocol.StreamDataMessage.STREAM_ID_STDERR:
+                            if message.data and len(message.data) > 0:
+                                ttyRestorer.raw()
+                                RNS.log(f"stdout: {message.data}", RNS.LOG_DEBUG)
+                                os.write(2, message.data)
+                                sys.stderr.flush()
+                            if message.eof:
+                                os.close(2)
+                    elif isinstance(message, protocol.CommandExitedMessage):
+                        RNS.log(f"received return code {message.return_code}, exiting", RNS.LOG_DEBUG)
+                        return message.return_code
+                    elif isinstance(message, protocol.ErrorMessage):
+                        RNS.log(f"Remote error: {message.data}", RNS.LOG_ERROR)
+                        if message.fatal:
+                            _link.teardown()
+                            return 200
+
+                except queue.Empty:
+                    processed = False
+
+                if channel.is_ready_to_send():
+                    def compress_adaptive(buf: bytes):
+                        comp_tries = RNS.RawChannelWriter.COMPRESSION_TRIES
+                        comp_try = 1
+                        comp_success = False
+                        
+                        chunk_len = len(buf)
+                        if chunk_len > RNS.RawChannelWriter.MAX_CHUNK_LEN:
+                            chunk_len = RNS.RawChannelWriter.MAX_CHUNK_LEN
+                        chunk_segment = None
+
+                        chunk_segment = None
+                        max_data_len = channel.mdu - protocol.StreamDataMessage.OVERHEAD
+                        while chunk_len > 32 and comp_try < comp_tries:
+                            chunk_segment_length = int(chunk_len/comp_try)
+                            compressed_chunk = bz2.compress(buf[:chunk_segment_length])
+                            compressed_length = len(compressed_chunk)
+                            if compressed_length < max_data_len and compressed_length < chunk_segment_length:
+                                comp_success = True
+                                break
+                            else:
+                                comp_try += 1
+
+                        if comp_success:
+                            diff = max_data_len - len(compressed_chunk)
+                            chunk = compressed_chunk
+                            processed_length = chunk_segment_length
+                        else:
+                            chunk = bytes(buf[:max_data_len])
+                            processed_length = len(chunk)
+
+                        return comp_success, processed_length, chunk
+
+                    comp_success, processed_length, chunk = compress_adaptive(data_buffer)
+                    stdin = chunk
+                    data_buffer = data_buffer[processed_length:]
+                    eof = not sent_eof and stdin_eof and len(stdin) == 0
+                    if len(stdin) > 0 or eof:
+                        channel.send(protocol.StreamDataMessage(protocol.StreamDataMessage.STREAM_ID_STDIN, stdin, eof, comp_success))
+                        sent_eof = eof
+                        processed = True
+
+                # send window change, but rate limited
+                if winch and time.time() - last_winch > _link.rtt * 25:
+                    last_winch = time.time()
+                    winch = False
+                    with contextlib.suppress(Exception):
+                        r, c, h, v = process.tty_get_winsize(0)
+                        channel.send(protocol.WindowSizeMessage(r, c, h, v))
+                        processed = True
+            except RemoteExecutionError as e:
+                print(e.msg)
+                return 255
+            except Exception as ex:
+                print(f"Client exception: {ex}")
+                if _link and _link.status != RNS.Link.CLOSED:
+                    _link.teardown()
+                    return 127
+
+        RNS.log("Main loop done", RNS.LOG_DEBUG)
+        return 0

RNS/Utilities/rnsh/listener.py

@@ -0,0 +1,229 @@
+#         Based on the original rnsh program by Aaron Heise (@acehoss)
+# https://github.com/acehoss/rnsh - MIT License - Copyright (c) 2023 Aaron Heise
+#     This version of rnsh is included in RNS under the Reticulum License
+#
+# Reticulum License
+#
+# Copyright (c) 2016-2026 Mark Qvist
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# - The Software shall not be used in any kind of system which includes amongst
+#   its functions the ability to purposefully do harm to human beings.
+#
+# - The Software shall not be used, directly or indirectly, in the creation of
+#   an artificial intelligence, machine learning or language model training
+#   dataset, including but not limited to any use that contributes to the
+#   training or development of such a model or algorithm.
+#
+# - The above copyright notice and this permission notice shall be included in
+#   all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+from __future__ import annotations
+
+import asyncio
+import os
+import queue
+import shlex
+import signal
+import sys
+import termios
+import threading
+import time
+import tty
+from typing import Callable, TypeVar
+import RNS
+import RNS.Utilities.rnsh.exception as exception
+import RNS.Utilities.rnsh.process as process
+import RNS.Utilities.rnsh.retry as retry
+import RNS.Utilities.rnsh.session as session
+import re
+import contextlib
+
+import pwd
+import RNS.Utilities.rnsh.protocol as protocol
+import RNS.Utilities.rnsh.helpers as helpers
+import RNS.Utilities.rnsh.rnsh as rnsh
+
+
+_identity = None
+_reticulum = None
+_allow_all = False
+_allowed_file = None
+_allowed_identity_hashes = []
+_allowed_file_identity_hashes = []
+_cmd: [str] | None = None
+DATA_AVAIL_MSG = "data available"
+_finished: asyncio.Event = None
+_retry_timer: retry.RetryThread | None = None
+_destination: RNS.Destination | None = None
+_loop: asyncio.AbstractEventLoop | None = None
+_no_remote_command = True
+_remote_cmd_as_args = False
+
+
+async def _check_finished(timeout: float = 0):
+    return await process.event_wait(_finished, timeout=timeout)
+
+
+def _sigint_handler(sig, loop):
+    global _finished
+    RNS.log(f"Signal: {signal.Signals(sig).name}", RNS.LOG_DEBUG)
+    if _finished is not None: _finished.set()
+    else: raise KeyboardInterrupt()
+
+def _reload_allowed_file():
+    global _allowed_file, _allowed_file_identity_hashes
+    if _allowed_file != None:
+        try:
+            with open(_allowed_file, "r") as file:
+                dest_len = (RNS.Reticulum.TRUNCATED_HASHLENGTH // 8) * 2
+                added = 0
+                line = 0
+                _allowed_file_identity_hashes = []
+                for allow in file.read().replace("\r", "").split("\n"):
+                    line += 1
+                    if len(allow) == dest_len:
+                        try:
+                            destination_hash = bytes.fromhex(allow)
+                            _allowed_file_identity_hashes.append(destination_hash)
+                            added += 1
+                        except Exception:
+                            RNS.log(f"Discarded invalid Identity hash in {_allowed_file} at line {line}", RNS.LOG_DEBUG)
+
+                ms = "y" if added == 1 else "ies"
+                RNS.log(f"Loaded {added} allowed identit{ms} from "+str(_allowed_file), RNS.LOG_DEBUG)
+        
+        except Exception as e: RNS.log(f"Error while reloading allowed indetities file: {e}", RNS.LOG_ERROR)
+
+def compute_target_rns_loglevel(verbosity: int, quietness: int, base_level: int = RNS.LOG_INFO) -> int:
+    try:
+        target = int(base_level) + int(verbosity) - int(quietness)
+        if target < RNS.LOG_CRITICAL: target = RNS.LOG_CRITICAL
+        if target > RNS.LOG_DEBUG:    target = RNS.LOG_DEBUG
+        return target
+    
+    except Exception: return base_level
+
+async def listen(configdir, rnsconfigdir, command, identitypath=None, service_name=None, verbosity=0, quietness=0, allowed=None,
+                 allowed_file=None, disable_auth=None, announce_period=900, no_remote_command=True, remote_cmd_as_args=False,
+                 loop: asyncio.AbstractEventLoop = None):
+    global _identity, _allow_all, _allowed_identity_hashes, _allowed_file, _allowed_file_identity_hashes
+    global _reticulum, _cmd, _destination, _no_remote_command, _remote_cmd_as_args, _finished
+
+    if not loop: loop = asyncio.get_running_loop()
+    if service_name is None or len(service_name) == 0:
+        service_name = "default"
+
+    RNS.log(f"Using service name {service_name}", RNS.LOG_INFO)
+
+    # More -v should increase verbosity (higher RNS.loglevel); -q should decrease it
+    targetloglevel = compute_target_rns_loglevel(verbosity, quietness, RNS.LOG_INFO)
+    _reticulum = RNS.Reticulum(configdir=rnsconfigdir, loglevel=targetloglevel)
+    _identity = rnsh.prepare_identity(identitypath, service_name)
+    _destination = RNS.Destination(_identity, RNS.Destination.IN, RNS.Destination.SINGLE, rnsh.APP_NAME)
+    
+    RNS.log(f"rnsh listening for commands on {RNS.prettyhexrep(_destination.hash)}", RNS.LOG_NOTICE)
+    
+    _cmd = command
+    if _cmd is None or len(_cmd) == 0:
+        shell = None
+        try: shell = pwd.getpwuid(os.getuid()).pw_shell
+        except Exception as e: RNS.log(f"Error looking up shell: {e}", RNS.LOG_ERROR)
+        RNS.log(f"Using {shell} for default command.", RNS.LOG_INFO)
+
+        # Ensure a sane shell default. Fall back to /bin/sh if lookup fails.
+        if not shell or len(shell) == 0: shell = "/bin/sh"
+        _cmd = [shell]
+    
+    else: RNS.log(f"Using command {shlex.join(_cmd)}", RNS.LOG_INFO)
+
+    _no_remote_command = no_remote_command
+    session.ListenerSession.allow_remote_command = not no_remote_command
+    _remote_cmd_as_args = remote_cmd_as_args
+    if (_cmd is None or len(_cmd) == 0 or _cmd[0] is None or len(_cmd[0]) == 0) \
+            and (_no_remote_command or _remote_cmd_as_args):
+        raise Exception(f"Unable to look up shell for {os.getlogin}, cannot proceed with -A or -C and no <program>.")
+
+    session.ListenerSession.default_command = _cmd
+    session.ListenerSession.remote_cmd_as_args = _remote_cmd_as_args
+
+    if disable_auth:
+        _allow_all = True
+        session.ListenerSession.allow_all = True
+    else:
+        if allowed_file is not None:
+            _allowed_file = allowed_file
+            _reload_allowed_file()
+
+        if allowed is not None:
+            for a in allowed:
+                try:
+                    dest_len = (RNS.Reticulum.TRUNCATED_HASHLENGTH // 8) * 2
+                    if len(a) != dest_len:
+                        raise ValueError(
+                            "Allowed destination length is invalid, must be {hex} hexadecimal " +
+                            "characters ({byte} bytes).".format(
+                                hex=dest_len, byte=dest_len // 2))
+                    try:
+                        destination_hash = bytes.fromhex(a)
+                        _allowed_identity_hashes.append(destination_hash)
+                        session.ListenerSession.allowed_identity_hashes.append(destination_hash)
+                    except Exception:
+                        raise ValueError("Invalid destination entered. Check your input.")
+                
+                except Exception as e:
+                    RNS.log(f"Unhandled error: {e}", RNS.LOG_ERROR)
+                    RNS.trace_exception(e)
+                    exit(1)
+
+    if (len(_allowed_identity_hashes) < 1 and len(_allowed_file_identity_hashes) < 1) and not disable_auth:
+        RNS.log("Warning: No allowed identities configured, rnsh will not accept any connections!", RNS.LOG_WARNING)
+
+    def link_established(lnk: RNS.Link):
+        _reload_allowed_file()
+        session.ListenerSession.allowed_file_identity_hashes = _allowed_file_identity_hashes
+        session.ListenerSession(session.RNSOutlet.get_outlet(lnk), lnk.get_channel(), loop)
+    _destination.set_link_established_callback(link_established)
+
+    _finished = asyncio.Event()
+    signal.signal(signal.SIGINT, _sigint_handler)
+
+    if announce_period is not None: _destination.announce()
+
+    last_announce = time.time()
+    sleeper = helpers.SleepRate(0.01)
+
+    try:
+        while not await _check_finished():
+            if announce_period and 0 < announce_period < time.time() - last_announce:
+                last_announce = time.time()
+                _destination.announce()
+            if len(session.ListenerSession.sessions) > 0:
+                # no sleep if there's work to do
+                if not await session.ListenerSession.pump_all():
+                    await sleeper.sleep_async()
+            else:
+                await asyncio.sleep(0.25)
+    finally:
+        RNS.log("Shutting down", RNS.LOG_NOTICE)
+        await session.ListenerSession.terminate_all("Shutting down")
+        await asyncio.sleep(1)
+        links_still_active = list(filter(lambda l: l.status != RNS.Link.CLOSED, _destination.links))
+        for link in links_still_active:
+            if link.status not in [RNS.Link.CLOSED]:
+                link.teardown()
+                await asyncio.sleep(0.01)

RNS/Utilities/rnsh/loop.py

@@ -0,0 +1,46 @@
+#         Based on the original rnsh program by Aaron Heise (@acehoss)
+# https://github.com/acehoss/rnsh - MIT License - Copyright (c) 2023 Aaron Heise
+#     This version of rnsh is included in RNS under the Reticulum License
+#
+# Reticulum License
+#
+# Copyright (c) 2016-2026 Mark Qvist
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# - The Software shall not be used in any kind of system which includes amongst
+#   its functions the ability to purposefully do harm to human beings.
+#
+# - The Software shall not be used, directly or indirectly, in the creation of
+#   an artificial intelligence, machine learning or language model training
+#   dataset, including but not limited to any use that contributes to the
+#   training or development of such a model or algorithm.
+#
+# - The above copyright notice and this permission notice shall be included in
+#   all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+import asyncio
+import functools
+from typing import Callable
+
+def sig_handler_sys_to_loop(handler: Callable[[int, any], None]) -> Callable[[int, asyncio.AbstractEventLoop], None]:
+    def wrapped(cb: Callable[[int, any], None], signal: int, loop: asyncio.AbstractEventLoop): cb(signal, None)
+    return functools.partial(wrapped, handler)
+
+def loop_set_signal(sig, handler: Callable[[int, asyncio.AbstractEventLoop], None], loop: asyncio.AbstractEventLoop = None):
+    if loop is None: loop = asyncio.get_running_loop()
+    loop.remove_signal_handler(sig)
+    loop.add_signal_handler(sig, functools.partial(handler, sig, loop))

RNS/Utilities/rnsh/process.py

@@ -0,0 +1,785 @@
+#         Based on the original rnsh program by Aaron Heise (@acehoss)
+# https://github.com/acehoss/rnsh - MIT License - Copyright (c) 2023 Aaron Heise
+#     This version of rnsh is included in RNS under the Reticulum License
+#
+# Reticulum License
+#
+# Copyright (c) 2016-2026 Mark Qvist
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# - The Software shall not be used in any kind of system which includes amongst
+#   its functions the ability to purposefully do harm to human beings.
+#
+# - The Software shall not be used, directly or indirectly, in the creation of
+#   an artificial intelligence, machine learning or language model training
+#   dataset, including but not limited to any use that contributes to the
+#   training or development of such a model or algorithm.
+#
+# - The above copyright notice and this permission notice shall be included in
+#   all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+from __future__ import annotations
+import asyncio
+import contextlib
+import copy
+import errno
+import fcntl
+import functools
+import os
+import pty
+import select
+import signal
+import struct
+import sys
+import termios
+import threading
+import tty
+import types
+import typing
+import RNS
+
+import RNS.Utilities.rnsh.exception as exception
+
+CTRL_C = "\x03".encode("utf-8")
+CTRL_D = "\x04".encode("utf-8")
+
+def tty_add_reader_callback(fd: int, callback: callable, loop: asyncio.AbstractEventLoop = None):
+    """
+    Add an async reader callback for a tty file descriptor.
+
+    Example usage:
+
+        def reader():
+            data = tty_read(fd)
+            # do something with data
+
+        tty_add_reader_callback(self._child_fd, reader, self._loop)
+
+    :param fd: file descriptor
+    :param callback: callback function
+    :param loop: asyncio event loop to which the reader should be added. If None, use the currently-running loop.
+    """
+    if loop is None:
+        loop = asyncio.get_running_loop()
+    loop.add_reader(fd, callback)
+
+
+def tty_read(fd: int) -> bytes:
+    """
+    Read available bytes from a tty file descriptor. When used in a callback added to a file descriptor using
+    tty_add_reader_callback(...), this function creates a solution for non-blocking reads from ttys.
+    :param fd: tty file descriptor
+    :return: bytes read
+    """
+    if fd_is_closed(fd):
+        raise EOFError
+
+    try:
+        run = True
+        result = bytearray()
+        while not fd_is_closed(fd):
+            ready, _, _ = select.select([fd], [], [], 0)
+            if len(ready) == 0:
+                break
+            for f in ready:
+                try:
+                    data = os.read(f, 4096)
+                except OSError as e:
+                    if e.errno != errno.EIO and e.errno != errno.EWOULDBLOCK:
+                        raise
+                else:
+                    if not data:  # EOF
+                        if data is not None and len(data) > 0:
+                            result.extend(data)
+                            return result
+                        elif len(result) > 0:
+                            return result
+                        else:
+                            raise EOFError
+                    if data is not None and len(data) > 0:
+                        result.extend(data)
+        return result
+    
+    except EOFError: raise
+    except Exception as e: RNS.log(f"TTY read error: {e}", RNS.LOG_ERROR)
+
+
+def tty_read_poll(fd: int) -> bytes:
+    """
+    Read available bytes from a tty file descriptor. When used in a callback added to a file descriptor using
+    tty_add_reader_callback(...), this function creates a solution for non-blocking reads from ttys.
+    :param fd: tty file descriptor
+    :return: bytes read
+    """
+    if fd_is_closed(fd):
+        raise EOFError
+
+    result = bytearray()
+    try:
+        flags = fcntl.fcntl(fd, fcntl.F_GETFL)
+        fcntl.fcntl(fd, fcntl.F_SETFL, flags | os.O_NONBLOCK)
+        while True:
+            try:
+                data = os.read(fd, 4096)
+                if not data:
+                    # EOF
+                    if len(result) > 0:
+                        return result
+                    raise EOFError
+                result.extend(data)
+                # continue loop to drain
+            except OSError as e:
+                if e.errno in (errno.EWOULDBLOCK, errno.EAGAIN):
+                    break
+                if e.errno == errno.EIO:
+                    if len(result) > 0:
+                        return result
+                    raise EOFError
+                raise
+    except EOFError: raise
+    except Exception as e: RNS.log(f"TTY read error: {e}", RNS.LOG_ERROR)
+    
+    return result
+
+
+def fd_is_closed(fd: int) -> bool:
+    """
+    Check if file descriptor is closed
+    :param fd: file descriptor
+    :return: True if file descriptor is closed
+    """
+    try:
+        fcntl.fcntl(fd, fcntl.F_GETFL) < 0
+    except OSError as ose:
+        return ose.errno == errno.EBADF
+
+
+def tty_unset_reader_callbacks(fd: int, loop: asyncio.AbstractEventLoop = None):
+    """
+    Remove async reader callbacks for file descriptor.
+    :param fd: file descriptor
+    :param loop: asyncio event loop from which to remove callbacks
+    """
+    with exception.permit(SystemExit):
+        if loop is None:
+            loop = asyncio.get_running_loop()
+        loop.remove_reader(fd)
+
+
+def tty_get_winsize(fd: int) -> [int, int, int, int]:
+    """
+    Ge the window size of a tty.
+    :param fd: file descriptor of tty
+    :return: (rows, cols, h_pixels, v_pixels)
+    """
+    packed = fcntl.ioctl(fd, termios.TIOCGWINSZ, struct.pack('HHHH', 0, 0, 0, 0))
+    rows, cols, h_pixels, v_pixels = struct.unpack('HHHH', packed)
+    return rows, cols, h_pixels, v_pixels
+
+
+def tty_set_winsize(fd: int, rows: int, cols: int, h_pixels: int, v_pixels: int):
+    """
+    Set the window size on a tty.
+    :param fd: file descriptor of tty
+    :param rows: number of visible rows
+    :param cols: number of visible columns
+    :param h_pixels: number of visible horizontal pixels
+    :param v_pixels: number of visible vertical pixels
+    """
+    if fd < 0:
+        return
+    packed = struct.pack('HHHH', rows, cols, h_pixels, v_pixels)
+    fcntl.ioctl(fd, termios.TIOCSWINSZ, packed)
+
+
+def process_exists(pid) -> bool:
+    """
+    Check For the existence of a unix pid.
+    :param pid: process id to check
+    :return: True if process exists
+    """
+    try:
+        os.kill(pid, 0)
+    except OSError:
+        return False
+    else:
+        return True
+
+
+class TTYRestorer(contextlib.AbstractContextManager):
+    # Indexes of flags within the attrs array
+    ATTR_IDX_IFLAG = 0
+    ATTR_IDX_OFLAG = 1
+    ATTR_IDX_CFLAG = 2
+    ATTR_IDX_LFLAG = 4
+    ATTR_IDX_CC    = 5
+
+    def __init__(self, fd: int, suppress_logs=False):
+        """
+        Saves termios attributes for a tty for later restoration.
+
+        The attributes are an array of values with the following meanings.
+
+            tcflag_t c_iflag;      /* input modes */
+            tcflag_t c_oflag;      /* output modes */
+            tcflag_t c_cflag;      /* control modes */
+            tcflag_t c_lflag;      /* local modes */
+            cc_t     c_cc[NCCS];   /* special characters */
+
+        :param fd: file descriptor of tty
+        """
+        self._fd = fd
+        self._tattr = None
+        self._suppress_logs = suppress_logs
+        self._tattr = self.current_attr()
+        if not self._tattr and not self._suppress_logs: RNS.log(f"Could not get attrs for fd {fd}", RNS.LOG_DEBUG)
+
+    def raw(self):
+        """
+        Set raw mode on tty
+        """
+        if self._fd is None:
+            return
+        with contextlib.suppress(termios.error):
+            tty.setraw(self._fd, termios.TCSANOW)
+
+    def original_attr(self) -> [any]:
+        return copy.deepcopy(self._tattr)
+
+    def current_attr(self) -> [any]:
+        """
+        Get the current termios attributes for the wrapped fd.
+        :return: attribute array
+        """
+        if self._fd is None:
+            return None
+
+        with contextlib.suppress(termios.error):
+            return copy.deepcopy(termios.tcgetattr(self._fd))
+        return None
+
+    def set_attr(self, attr: [any], when: int = termios.TCSADRAIN):
+        """
+        Set termios attributes
+        :param attr: attribute list to set
+        :param when: when attributes should be applied (termios.TCSANOW, termios.TCSADRAIN, termios.TCSAFLUSH)
+        """
+        if not attr or self._fd is None:
+            return
+
+        with contextlib.suppress(termios.error):
+            termios.tcsetattr(self._fd, when, attr)
+
+    def isatty(self):
+        return os.isatty(self._fd) if self._fd is not None else None
+
+    def restore(self):
+        """
+        Restore termios settings to state captured in constructor.
+        """
+        self.set_attr(self._tattr, termios.TCSADRAIN)
+
+    def __exit__(self, __exc_type: typing.Type[BaseException], __exc_value: BaseException,
+                 __traceback: types.TracebackType) -> bool:
+        self.restore()
+        return False  #__exc_type is not None and issubclass(__exc_type, termios.error)
+
+
+def _task_from_event(evt: asyncio.Event, loop: asyncio.AbstractEventLoop = None):
+    if not loop:
+        loop = asyncio.get_running_loop()
+
+    #TODO: this is hacky
+    async def wait():
+        while not evt.is_set():
+            await asyncio.sleep(0.1)
+        return True
+
+    return loop.create_task(wait())
+
+
+class AggregateException(Exception):
+    def __init__(self, inner_exceptions: [Exception]):
+        super().__init__()
+        self.inner_exceptions = inner_exceptions
+
+    def __str__(self):
+        return "Multiple exceptions encountered: \n\n" + "\n\n".join(map(lambda e: str(e), self.inner_exceptions))
+
+
+async def event_wait_any(evts: [asyncio.Event], timeout: float  = None) -> (any, any):
+    tasks = list(map(lambda evt: (evt, _task_from_event(evt)), evts))
+    try:
+        finished, unfinished = await asyncio.wait(map(lambda t: t[1], tasks),
+                                                  timeout=timeout,
+                                                  return_when=asyncio.FIRST_COMPLETED)
+
+        if len(unfinished) > 0:
+            for task in unfinished:
+                task.cancel()
+            await asyncio.wait(unfinished)
+
+        exceptions = []
+
+        for f in finished:
+            ex = f.exception()
+            if ex and not isinstance(ex, asyncio.CancelledError) and not isinstance(ex, TimeoutError):
+                exceptions.append(ex)
+
+        if len(exceptions) > 0:
+            raise AggregateException(exceptions)
+
+        return next(map(lambda t: next(map(lambda tt: tt[0], tasks)), finished), None)
+    finally:
+        unfinished = []
+        for task in map(lambda t: t[1], tasks):
+            if task.done():
+                if not task.cancelled():
+                    task.exception()
+            else:
+                task.cancel()
+                unfinished.append(task)
+        if len(unfinished) > 0:
+            await asyncio.wait(unfinished)
+
+
+async def event_wait(evt: asyncio.Event, timeout: float) -> bool:
+    """
+    Wait for event to be set, or timeout to expire.
+    :param evt: asyncio.Event to wait on
+    :param timeout: maximum number of seconds to wait.
+    :return: True if event was set, False if timeout expired
+    """
+    await event_wait_any([evt], timeout=timeout)
+    return evt.is_set()
+
+
+def _launch_child(cmd_line: list[str], env: dict[str, str], stdin_is_pipe: bool, stdout_is_pipe: bool,
+                  stderr_is_pipe: bool) -> tuple[int, int, int, int]:
+    # Set up PTY and/or pipes
+    child_fd = parent_fd = None
+    if not (stdin_is_pipe and stdout_is_pipe and stderr_is_pipe):
+        parent_fd, child_fd = pty.openpty()
+    child_stdin, parent_stdin = (os.pipe() if stdin_is_pipe else (child_fd, parent_fd))
+    parent_stdout, child_stdout = (os.pipe() if stdout_is_pipe else (parent_fd, child_fd))
+    parent_stderr, child_stderr = (os.pipe() if stderr_is_pipe else (parent_fd, child_fd))
+
+    # Fork
+    pid = os.fork()
+
+    if pid == 0:
+        try:
+            # We are in the child process, so close all open sockets and pipes except for the PTY and/or pipes
+            max_fd = os.sysconf("SC_OPEN_MAX")
+            for fd in range(3, max_fd):
+                if fd not in (child_stdin, child_stdout, child_stderr):
+                    try:
+                        os.close(fd)
+                    except OSError:
+                        pass
+
+            # Set up PTY and/or pipes
+            os.dup2(child_stdin, 0)
+            os.dup2(child_stdout, 1)
+            os.dup2(child_stderr, 2)
+            # Make PTY controlling if necessary so that CTRL_C/CTRL_D behave as expected
+            if child_fd is not None:
+                os.setsid()
+                try:
+                    tty_fd = 0 if not stdin_is_pipe else (1 if not stdout_is_pipe else 2)
+                    # Set controlling TTY for this session
+                    fcntl.ioctl(tty_fd, termios.TIOCSCTTY, 0)
+                except Exception:
+                    pass
+                # Ensure the child is the foreground process group for the TTY
+                try:
+                    os.setpgid(0, 0)
+                    pgid = os.getpgrp()
+                    import struct as _struct
+                    fcntl.ioctl(tty_fd, termios.TIOCSPGRP, _struct.pack('i', pgid))
+                except Exception:
+                    pass
+                # Ensure canonical input with signals and local echo enabled
+                try:
+                    tty_fd = 0 if not stdin_is_pipe else (1 if not stdout_is_pipe else 2)
+                    attrs = termios.tcgetattr(tty_fd)
+                    lflag = attrs[3]
+                    lflag |= termios.ICANON | termios.ISIG | termios.ECHO
+                    attrs[3] = lflag
+                    termios.tcsetattr(tty_fd, termios.TCSANOW, attrs)
+                except Exception:
+                    pass
+
+            # Execute the command
+            os.execvpe(cmd_line[0], cmd_line, env)
+        except Exception as err:
+            exc_type, exc_obj, exc_tb = sys.exc_info()
+            fname = os.path.split(exc_tb.tb_frame.f_code.co_filename)[1]
+            print(f"Unable to start {cmd_line[0]}: {err} ({fname}:{exc_tb.tb_lineno})")
+            sys.stdout.flush()
+        # don't let any other modules get in our way, do an immediate silent exit.
+        os._exit(255)
+
+    else:
+        # We are in the parent process, so close the child-side of the PTY and/or pipes
+        if child_fd is not None:
+            os.close(child_fd)
+        if child_stdin != child_fd:
+            os.close(child_stdin)
+        if child_stdout != child_fd:
+            os.close(child_stdout)
+        if child_stderr != child_fd:
+            os.close(child_stderr)
+        # # Close the write end of the pipe if a pipe is used for standard input
+        # if not stdin_is_pipe:
+        #     os.close(parent_stdin)
+        # Return the child PID and the file descriptors for the PTY and/or pipes
+        return pid, parent_stdin, parent_stdout, parent_stderr
+
+
+class CallbackSubprocess:
+    # time between checks of child process
+    PROCESS_POLL_TIME: float = 0.1
+    # Close pipes soon after process exit to avoid scheduling on closed event loops
+    PROCESS_PIPE_TIME: int = 1
+
+    def __init__(self, argv: [str], env: dict, loop: asyncio.AbstractEventLoop, stdout_callback: callable,
+                 stderr_callback: callable, terminated_callback: callable, stdin_is_pipe: bool, stdout_is_pipe: bool,
+                 stderr_is_pipe: bool):
+        """
+        Fork a child process and generate callbacks with output from the process.
+        :param argv: the command line, tokenized. The first element must be the absolute path to an executable file.
+        :param env: environment variables to override
+        :param loop: the asyncio event loop to use
+        :param stdout_callback: callback for data, e.g. def callback(data:bytes) -> None
+        :param terminated_callback: callback for termination/return code, e.g. def callback(return_code:int) -> None
+        """
+        assert loop is not None, "loop should not be None"
+        assert stdout_callback is not None, "stdout_callback should not be None"
+        assert terminated_callback is not None, "terminated_callback should not be None"
+
+        self._command: [str] = argv
+        self._env = env or {}
+        self._loop = loop
+        self._stdout_cb = stdout_callback
+        self._stderr_cb = stderr_callback
+        self._terminated_cb = terminated_callback
+        self._pid: int = None
+        self._child_stdin: int = None
+        self._child_stdout: int = None
+        self._child_stderr: int = None
+        self._return_code: int = None
+        self._stdout_eof: bool = False
+        self._stderr_eof: bool = False
+        self._stdin_is_pipe = stdin_is_pipe
+        self._stdout_is_pipe = stdout_is_pipe
+        self._stderr_is_pipe = stderr_is_pipe
+        self._at_line_start: bool = True
+        self._tty_line_buffer: bytearray = bytearray()
+
+    def _ensure_pipes_closed(self):
+        stdin = self._child_stdin
+        stdout = self._child_stdout
+        stderr = self._child_stderr
+        fds = set(filter(lambda x: x is not None, list({stdin, stdout, stderr})))
+        RNS.log(f"Queuing close of pipes for ended process (fds: {fds})", RNS.LOG_DEBUG)
+
+        def ensure_pipes_closed_inner():
+            RNS.log(f"Ensuring pipes are closed (fds: {fds})", RNS.LOG_DEBUG)
+            for fd in fds:
+                RNS.log(f"Closing fd {fd}", RNS.LOG_DEBUG)
+                with contextlib.suppress(OSError): tty_unset_reader_callbacks(fd)
+                with contextlib.suppress(OSError): os.close(fd)
+
+            self._child_stdin = None
+            self._child_stdout = None
+            self._child_stderr = None
+
+        # Avoid scheduling on a closed loop
+        if self._loop.is_closed(): ensure_pipes_closed_inner()
+        else:                      self._loop.call_later(CallbackSubprocess.PROCESS_PIPE_TIME, ensure_pipes_closed_inner)
+
+    def terminate(self, kill_delay: float = 1.0):
+        """
+        Terminate child process if running
+        :param kill_delay: if after kill_delay seconds the child process has not exited, escalate to SIGHUP and SIGKILL
+        """
+
+        RNS.log("terminate()", RNS.LOG_EXTREME)
+        if not self.running: return
+
+        with exception.permit(SystemExit): os.kill(self._pid, signal.SIGTERM)
+
+        def kill():
+            if process_exists(self._pid):
+                RNS.log("kill()", RNS.LOG_EXTREME)
+                with exception.permit(SystemExit):
+                    os.kill(self._pid, signal.SIGHUP)
+                    os.kill(self._pid, signal.SIGKILL)
+
+        self._loop.call_later(kill_delay, kill)
+
+        def wait():
+            RNS.log("wait()", RNS.LOG_EXTREME)
+            with contextlib.suppress(OSError): os.waitpid(self._pid, 0)
+            self._ensure_pipes_closed()
+            RNS.log("wait() finish", RNS.LOG_EXTREME)
+
+        threading.Thread(target=wait, daemon=True).start()
+
+    def close_stdin(self):
+        with contextlib.suppress(Exception):
+            os.close(self._child_stdin)
+        # Encourage prompt shutdown if child lingers after stdin close
+        def _ensure_terminate():
+            if self.running:
+                self.terminate(kill_delay=0.2)
+        if not self._loop.is_closed():
+            self._loop.call_later(0.05, _ensure_terminate)
+
+    @property
+    def started(self) -> bool:
+        """
+        :return: True if child process has been started
+        """
+        return self._pid is not None
+
+    @property
+    def running(self) -> bool:
+        """
+        :return: True if child process is still running
+        """
+        return self._pid is not None and process_exists(self._pid)
+
+    def write(self, data: bytes):
+        """
+        Write bytes to the stdin of the child process.
+        :param data: bytes to write
+        """
+
+        os.write(self._child_stdin, data)
+
+        # TODO: Check what this is actually supposed to solve.
+        #
+        # For pipe-in + TTY-out, echo should be visible immediately
+        if self._stdin_is_pipe and not self._stdout_is_pipe and self._stdout_cb is not None and data not in (CTRL_C, CTRL_D):
+            try: self._stdout_cb(data)
+            except Exception: pass
+
+    def set_winsize(self, r: int, c: int, h: int, v: int):
+        """
+        Set the window size on the tty of the child process.
+        :param r: rows visible
+        :param c: columns visible
+        :param h: horizontal pixels visible
+        :param v: vertical pixels visible
+        :return:
+        """
+        RNS.log(f"set_winsize({r},{c},{h},{v}", RNS.LOG_DEBUG)
+        tty_set_winsize(self._child_stdout, r, c, h, v)
+
+    def copy_winsize(self, fromfd: int):
+        """
+        Copy window size from one tty to another.
+        :param fromfd: source tty file descriptor
+        """
+        r, c, h, v = tty_get_winsize(fromfd)
+        self.set_winsize(r, c, h, v)
+
+    def tcsetattr(self, when: int, attr: list[any]):  # actual type is list[int | list[int | bytes]]
+        """
+        Set tty attributes.
+        :param when: when to apply change: termios.TCSANOW or termios.TCSADRAIN or termios.TCSAFLUSH
+        :param attr: attributes to set
+        """
+        termios.tcsetattr(self._child_stdin, when, attr)
+
+    def tcgetattr(self) -> list[any]:  # actual type is list[int | list[int | bytes]]
+        """
+        Get tty attributes.
+        :return: tty attributes value
+        """
+        return termios.tcgetattr(self._child_stdout)
+
+    def ttysetraw(self):
+        tty.setraw(self._child_stdout, termios.TCSADRAIN)
+
+    def start(self):
+        """
+        Start the child process.
+        """
+        RNS.log("start()", RNS.LOG_EXTREME)
+
+        # # Using the parent environment seems to do some weird stuff, at least on macOS
+        # parentenv = os.environ.copy()
+        # env = {"HOME": parentenv["HOME"],
+        #        "PATH": parentenv["PATH"],
+        #        "TERM": self._term if self._term is not None else parentenv.get("TERM", "xterm"),
+        #        "LANG": parentenv.get("LANG"),
+        #        "SHELL": self._command[0]}
+
+        env = os.environ.copy()
+        for key in self._env:
+            env[key] = self._env[key]
+
+        program = self._command[0]
+        assert isinstance(program, str)
+
+        # match = re.search("^/bin/(.*sh)$", program)
+        # if match:
+        #     self._command[0] = "-" + match.group(1)
+        #     env["SHELL"] = program
+        #     self._log.debug(f"set login shell {self._command}")
+
+        self._pid, \
+            self._child_stdin, \
+            self._child_stdout, \
+            self._child_stderr = _launch_child(self._command, env, self._stdin_is_pipe, self._stdout_is_pipe,
+                                               self._stderr_is_pipe)
+        RNS.log(f"Started pid {self.pid}, fds: {self._child_stdin}, {self._child_stdout}, {self._child_stderr}", RNS.LOG_DEBUG)
+
+        def poll():
+            try:
+                pid, self._return_code = os.waitpid(self._pid, os.WNOHANG)
+                if self._return_code is not None:
+                    self._return_code = self._return_code & 0xff
+                if self._return_code is not None and not process_exists(self._pid):
+                    RNS.log(f"polled return code {self._return_code}", RNS.LOG_DEBUG)
+                    self._terminated_cb(self._return_code)
+                if self.running:
+                    self._loop.call_later(CallbackSubprocess.PROCESS_POLL_TIME, poll)
+                else:
+                    self._ensure_pipes_closed()
+            except Exception as e:
+                if not hasattr(e, "errno") or e.errno != errno.ECHILD:
+                    RNS.log(f"Error in process poll: {e}", RNS.LOG_DEBUG)
+
+        self._loop.call_later(CallbackSubprocess.PROCESS_POLL_TIME, poll)
+
+        def stdout():
+            try:
+                with exception.permit(SystemExit):
+                    data = tty_read_poll(self._child_stdout)
+                    if data is not None and len(data) > 0:
+                        self._stdout_cb(data)
+                        # Opportunistically drain shortly after to coalesce immediate follow-up output
+                        if not self._loop.is_closed():
+                            self._loop.call_later(0.01, stdout)
+            except EOFError:
+                self._stdout_eof = True
+                tty_unset_reader_callbacks(self._child_stdout)
+                self._stdout_cb(bytearray())
+
+        def stderr():
+            try:
+                with exception.permit(SystemExit):
+                    data = tty_read_poll(self._child_stderr)
+                    if data is not None and len(data) > 0:
+                        self._stderr_cb(data)
+                        if not self._loop.is_closed():
+                            self._loop.call_later(0.01, stderr)
+            except EOFError:
+                self._stderr_eof = True
+                tty_unset_reader_callbacks(self._child_stderr)
+                self._stderr_cb(bytearray())
+
+        tty_add_reader_callback(self._child_stdout, stdout, self._loop)
+        if self._child_stderr != self._child_stdout:
+            tty_add_reader_callback(self._child_stderr, stderr, self._loop)
+
+    @property
+    def stdout_eof(self):
+        return self._stdout_eof or not self.running
+
+    @property
+    def stderr_eof(self):
+        return self._stderr_eof or not self.running
+
+
+    @property
+    def return_code(self) -> int:
+        return self._return_code
+
+    @property
+    def pid(self) -> int:
+        return self._pid
+
+
+async def main():
+    """
+    A test driver for the CallbackProcess class.
+    python ./process.py /bin/zsh --login
+    """
+
+    if len(sys.argv) <= 1:
+        print(f"Usage: {sys.argv} <absolute_path_to_child_executable> [child_arg ...]")
+        exit(1)
+
+    loop = asyncio.get_event_loop()
+    # asyncio.set_event_loop(loop)
+    retcode = loop.create_future()
+
+    def stdout(data: bytes): os.write(sys.stdout.fileno(), data)
+
+    def terminated(rc: int): retcode.set_result(rc)
+
+    process = CallbackSubprocess(argv=sys.argv[1:],
+                                 env={"TERM": os.environ.get("TERM", "xterm")},
+                                 loop=loop,
+                                 stdout_callback=stdout,
+                                 terminated_callback=terminated)
+
+    def sigint_handler(sig, frame):
+        if process is None or process.started and not process.running:
+            raise KeyboardInterrupt
+        elif process.running:
+            process.write("\x03".encode("utf-8"))
+
+    def sigwinch_handler(sig, frame):
+        process.copy_winsize(sys.stdin.fileno())
+
+    signal.signal(signal.SIGINT, sigint_handler)
+    signal.signal(signal.SIGWINCH, sigwinch_handler)
+
+    def stdin():
+        try:
+            data = tty_read(sys.stdin.fileno())
+            if data is not None:
+                process.write(data)
+
+        except EOFError:
+            tty_unset_reader_callbacks(sys.stdin.fileno())
+            process.write(CTRL_D)
+
+    tty_add_reader_callback(sys.stdin.fileno(), stdin)
+    process.start()
+    # call_soon called it too soon, not sure why.
+    loop.call_later(0.001, functools.partial(process.copy_winsize, sys.stdin.fileno()))
+
+    val = await retcode
+    RNS.log(f"Got return code {val}", RNS.LOG_DEBUG)
+    return val
+
+
+if __name__ == "__main__":
+    tr = TTYRestorer(sys.stdin.fileno())
+    try:
+        tr.raw()
+        asyncio.run(main())
+    finally:
+        tty_unset_reader_callbacks(sys.stdin.fileno())
+        tr.restore()

RNS/Utilities/rnsh/protocol.py

@@ -0,0 +1,149 @@
+#         Based on the original rnsh program by Aaron Heise (@acehoss)
+# https://github.com/acehoss/rnsh - MIT License - Copyright (c) 2023 Aaron Heise
+#     This version of rnsh is included in RNS under the Reticulum License
+#
+# Reticulum License
+#
+# Copyright (c) 2016-2026 Mark Qvist
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# - The Software shall not be used in any kind of system which includes amongst
+#   its functions the ability to purposefully do harm to human beings.
+#
+# - The Software shall not be used, directly or indirectly, in the creation of
+#   an artificial intelligence, machine learning or language model training
+#   dataset, including but not limited to any use that contributes to the
+#   training or development of such a model or algorithm.
+#
+# - The above copyright notice and this permission notice shall be included in
+#   all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+from __future__ import annotations
+
+import RNS
+from RNS.vendor import umsgpack
+from RNS.Buffer import StreamDataMessage as RNSStreamDataMessage
+import RNS.Utilities.rnsh.retry
+import abc
+import contextlib
+import struct
+from abc import ABC, abstractmethod
+
+MSG_MAGIC = 0xac
+PROTOCOL_VERSION = 1
+
+def _make_MSGTYPE(val: int):
+    return ((MSG_MAGIC << 8) & 0xff00) | (val & 0x00ff)
+
+
+class NoopMessage(RNS.MessageBase):
+    MSGTYPE = _make_MSGTYPE(0)
+    def pack(self) -> bytes: return bytes()
+    def unpack(self, raw): pass
+
+
+class WindowSizeMessage(RNS.MessageBase):
+    MSGTYPE = _make_MSGTYPE(2)
+
+    def __init__(self, rows: int = None, cols: int = None, hpix: int = None, vpix: int = None):
+        super().__init__()
+        self.rows = rows
+        self.cols = cols
+        self.hpix = hpix
+        self.vpix = vpix
+
+    def pack(self) -> bytes: return umsgpack.packb((self.rows, self.cols, self.hpix, self.vpix))
+    def unpack(self, raw): self.rows, self.cols, self.hpix, self.vpix = umsgpack.unpackb(raw)
+
+
+class ExecuteCommandMesssage(RNS.MessageBase):
+    MSGTYPE = _make_MSGTYPE(3)
+
+    def __init__(self, cmdline: [str] = None, pipe_stdin: bool = False, pipe_stdout: bool = False,
+                 pipe_stderr: bool = False, tcflags: [any] = None, term: str | None = None, rows: int = None,
+                 cols: int = None, hpix: int = None, vpix: int = None):
+        
+        super().__init__()
+        self.cmdline = cmdline
+        self.pipe_stdin = pipe_stdin
+        self.pipe_stdout = pipe_stdout
+        self.pipe_stderr = pipe_stderr
+        self.tcflags = tcflags
+        self.term = term
+        self.rows = rows
+        self.cols = cols
+        self.hpix = hpix
+        self.vpix = vpix
+
+    def pack(self) -> bytes:
+        return umsgpack.packb((self.cmdline, self.pipe_stdin, self.pipe_stdout, self.pipe_stderr,
+                               self.tcflags, self.term, self.rows, self.cols, self.hpix, self.vpix))
+
+    def unpack(self, raw):
+        self.cmdline, self.pipe_stdin, self.pipe_stdout, self.pipe_stderr, self.tcflags, self.term, self.rows, \
+            self.cols, self.hpix, self.vpix = umsgpack.unpackb(raw)
+
+
+# Create a version of RNS.Buffer.StreamDataMessage that we control
+class StreamDataMessage(RNSStreamDataMessage):
+    MSGTYPE = _make_MSGTYPE(4)
+    STREAM_ID_STDIN  = 0
+    STREAM_ID_STDOUT = 1
+    STREAM_ID_STDERR = 2
+
+
+class VersionInfoMessage(RNS.MessageBase):
+    MSGTYPE = _make_MSGTYPE(5)
+
+    def __init__(self, sw_version: str = None):
+        super().__init__()
+        self.sw_version = sw_version or RNS.Utilities.rnsh.__version__
+        self.protocol_version = PROTOCOL_VERSION
+
+    def pack(self) -> bytes: return umsgpack.packb((self.sw_version, self.protocol_version))
+    def unpack(self, raw): self.sw_version, self.protocol_version = umsgpack.unpackb(raw)
+
+
+class ErrorMessage(RNS.MessageBase):
+    MSGTYPE = _make_MSGTYPE(6)
+
+    def __init__(self, msg: str = None, fatal: bool = False, data: dict = None):
+        super().__init__()
+        self.msg = msg
+        self.fatal = fatal
+        self.data = data
+
+    def pack(self) -> bytes: return umsgpack.packb((self.msg, self.fatal, self.data))
+    def unpack(self, raw: bytes): self.msg, self.fatal, self.data = umsgpack.unpackb(raw)
+
+
+class CommandExitedMessage(RNS.MessageBase):
+    MSGTYPE = _make_MSGTYPE(7)
+
+    def __init__(self, return_code: int = None):
+        super().__init__()
+        self.return_code = return_code
+
+    def pack(self) -> bytes: return umsgpack.packb(self.return_code)
+    def unpack(self, raw: bytes): self.return_code = umsgpack.unpackb(raw)
+
+
+message_types = [NoopMessage, VersionInfoMessage, WindowSizeMessage, ExecuteCommandMesssage, StreamDataMessage,
+                 CommandExitedMessage, ErrorMessage]
+
+def register_message_types(channel: RNS.Channel.Channel):
+    for message_type in message_types: channel.register_message_type(message_type)

RNS/Utilities/rnsh/retry.py

@@ -0,0 +1,201 @@
+#         Based on the original rnsh program by Aaron Heise (@acehoss)
+# https://github.com/acehoss/rnsh - MIT License - Copyright (c) 2023 Aaron Heise
+#     This version of rnsh is included in RNS under the Reticulum License
+#
+# Reticulum License
+#
+# Copyright (c) 2016-2026 Mark Qvist
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# - The Software shall not be used in any kind of system which includes amongst
+#   its functions the ability to purposefully do harm to human beings.
+#
+# - The Software shall not be used, directly or indirectly, in the creation of
+#   an artificial intelligence, machine learning or language model training
+#   dataset, including but not limited to any use that contributes to the
+#   training or development of such a model or algorithm.
+#
+# - The above copyright notice and this permission notice shall be included in
+#   all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+import asyncio
+import threading
+import time
+import RNS.Utilities.rnsh.exception as exception
+from typing import Callable
+from contextlib import AbstractContextManager
+import types
+import typing
+
+
+class RetryStatus:
+    def __init__(self, tag: any, try_limit: int, wait_delay: float, retry_callback: Callable[[any, int], any],
+                 timeout_callback: Callable[[any, int], None], tries: int = 1):
+        
+        self.tag = tag
+        self.try_limit = try_limit
+        self.tries = tries
+        self.wait_delay = wait_delay
+        self.retry_callback = retry_callback
+        self.timeout_callback = timeout_callback
+        self.try_time = time.time()
+        self.completed = False
+
+    @property
+    def ready(self):
+        ready = time.time() > self.try_time + self.wait_delay
+        RNS.log(f"ready check {self.tag} try_time {self.try_time} wait_delay {self.wait_delay} " +
+                        f"next_try {self.try_time + self.wait_delay} now {time.time()} " +
+                        f"exceeded {time.time() - self.try_time - self.wait_delay} ready {ready}", RNS.LOG_DEBUG)
+        return ready
+
+    @property
+    def timed_out(self):
+        return self.ready and self.tries >= self.try_limit
+
+    def timeout(self):
+        self.completed = True
+        self.timeout_callback(self.tag, self.tries)
+
+    def retry(self) -> any:
+        self.tries = self.tries + 1
+        self.try_time = time.time()
+        return self.retry_callback(self.tag, self.tries)
+
+
+class RetryThread(AbstractContextManager):
+    def __init__(self, loop_period: float = 0.25, name: str = "retry thread"):
+        self._loop_period = loop_period
+        self._statuses: list[RetryStatus] = []
+        self._tag_counter = 0
+        self._lock = threading.RLock()
+        self._run = True
+        self._finished: asyncio.Future = None
+        self._thread = threading.Thread(name=name, target=self._thread_run, daemon=True)
+        self._thread.start()
+
+    def is_alive(self):
+        return self._thread.is_alive()
+
+    def close(self, loop: asyncio.AbstractEventLoop = None) -> asyncio.Future:
+        RNS.log("Stopping timer thread", RNS.LOG_DEBUG)
+        if loop is None:
+            self._run = False
+            self._thread.join()
+            return None
+        else:
+            self._finished = loop.create_future()
+            return self._finished
+
+    def wait(self, timeout: float = None):
+        if timeout:
+            timeout = timeout + time.time()
+
+        while timeout is None or time.time() < timeout:
+            with self._lock:
+                task_count = len(self._statuses)
+            if task_count == 0:
+                return
+            time.sleep(0.1)
+
+
+    def _thread_run(self):
+        while self._run and self._finished is None:
+            time.sleep(self._loop_period)
+            ready: list[RetryStatus] = []
+            prune: list[RetryStatus] = []
+            with self._lock: ready.extend(list(filter(lambda s: s.ready, self._statuses)))
+            
+            for retry in ready:
+                try:
+                    if not retry.completed:
+                        if retry.timed_out:
+                            RNS.log(f"Timed out {retry.tag} after {retry.try_limit} tries", RNS.LOG_DEBUG)
+                            retry.timeout()
+                            prune.append(retry)
+                        elif retry.ready:
+                            RNS.log(f"Retrying {retry.tag}, try {retry.tries + 1}/{retry.try_limit}", RNS.LOG_DEBUG)
+                            should_continue = retry.retry()
+                            if not should_continue: self.complete(retry.tag)
+                
+                except Exception as e:
+                    RNS.log(f"Error processing retry id {retry.tag}: {e}", RNS.LOG_ERROR)
+                    prune.append(retry)
+
+            with self._lock:
+                for retry in prune:
+                    RNS.log(f"pruned retry {retry.tag}, retry count {retry.tries}/{retry.try_limit}", RNS.LOG_DEBUG)
+                    with exception.permit(SystemExit): self._statuses.remove(retry)
+
+        if self._finished is not None: self._finished.set_result(None)
+
+    def _get_next_tag(self):
+        self._tag_counter += 1
+        return self._tag_counter
+
+    def has_tag(self, tag: any) -> bool:
+        with self._lock: return next(filter(lambda s: s.tag == tag, self._statuses), None) is not None
+
+    def begin(self, try_limit: int, wait_delay: float, try_callback: Callable[[any, int], any],
+              timeout_callback: Callable[[any, int], None]) -> any:
+        
+        RNS.log(f"Running first try", RNS.LOG_DEBUG)
+        tag = try_callback(None, 1)
+        RNS.log(f"First try got id {tag}", RNS.LOG_DEBUG)
+        
+        if not tag:
+            RNS.log(f"Callback returned None/False/0, considering complete.", RNS.LOG_DEBUG)
+            return None
+        
+        with self._lock:
+            if tag is None: tag = self._get_next_tag()
+            self.complete(tag)
+
+            self._statuses.append(RetryStatus(tag=tag,
+                                              tries=1,
+                                              try_limit=try_limit,
+                                              wait_delay=wait_delay,
+                                              retry_callback=try_callback,
+                                              timeout_callback=timeout_callback))
+        
+        RNS.log(f"Added retry timer for {tag}", RNS.LOG_DEBUG)
+        return tag
+
+    def complete(self, tag: any):
+        assert tag is not None
+        with self._lock:
+            status = next(filter(lambda l: l.tag == tag, self._statuses), None)
+            if status is not None:
+                status.completed = True
+                self._statuses.remove(status)
+                RNS.log(f"completed {tag}", RNS.LOG_DEBUG)
+                return
+
+        RNS.log(f"status not found to complete {tag}", RNS.LOG_DEBUG)
+
+    def complete_all(self):
+        with self._lock:
+            for status in self._statuses:
+                status.completed = True
+                RNS.log(f"completed {status.tag}", RNS.LOG_DEBUG)
+            
+            self._statuses.clear()
+
+    def __exit__(self, __exc_type: typing.Type[BaseException], __exc_value: BaseException,
+                 __traceback: types.TracebackType) -> bool:
+        self.close()
+        return False

RNS/Utilities/rnsh/rnsh.py

@@ -0,0 +1,174 @@
+#!/usr/bin/env python3
+#
+#         Based on the original rnsh program by Aaron Heise (@acehoss)
+# https://github.com/acehoss/rnsh - MIT License - Copyright (c) 2023 Aaron Heise
+#     This version of rnsh is included in RNS under the Reticulum License
+#
+# Reticulum License
+#
+# Copyright (c) 2016-2026 Mark Qvist
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# - The Software shall not be used in any kind of system which includes amongst
+#   its functions the ability to purposefully do harm to human beings.
+#
+# - The Software shall not be used, directly or indirectly, in the creation of
+#   an artificial intelligence, machine learning or language model training
+#   dataset, including but not limited to any use that contributes to the
+#   training or development of such a model or algorithm.
+#
+# - The above copyright notice and this permission notice shall be included in
+#   all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+from __future__ import annotations
+
+import asyncio
+import base64
+
+import re
+import os
+import sys
+
+import RNS
+import RNS.Utilities.rnsh.process as process
+import RNS.Utilities.rnsh.session as session
+import RNS.Utilities.rnsh.args
+import RNS.Utilities.rnsh.loop
+import RNS.Utilities.rnsh.listener as listener
+import RNS.Utilities.rnsh.initiator as initiator
+from RNS.Utilities.rnsh.args import parse_arguments
+
+APP_NAME = "rnsh"
+loop: asyncio.AbstractEventLoop | None = None
+
+def _sanitize_service_name(service_name:str) -> str: return re.sub(r'\W+', '', service_name)
+
+def prepare_identity(identity_path, service_name: str = None) -> tuple[RNS.Identity]:
+    service_name = _sanitize_service_name(service_name or "")
+    if identity_path is None:
+        identity_path = RNS.Reticulum.identitypath + "/" + APP_NAME + \
+                        (f".{service_name}" if service_name and len(service_name) > 0 else "")
+
+    identity = None
+    if os.path.isfile(identity_path):
+        identity = RNS.Identity.from_file(identity_path)
+
+    if identity is None:
+        RNS.log("No valid saved identity found, creating new...", RNS.LOG_INFO)
+        identity = RNS.Identity()
+        identity.to_file(identity_path)
+    
+    return identity
+
+
+def print_identity(configdir, identitypath, service_name, include_destination: bool):
+    reticulum = RNS.Reticulum(configdir=configdir, loglevel=RNS.LOG_INFO)
+    if service_name and len(service_name) > 0:
+        print(f"Using service name \"{service_name}\"")
+    identity = prepare_identity(identitypath, service_name)
+    destination = RNS.Destination(identity, RNS.Destination.IN, RNS.Destination.SINGLE, APP_NAME)
+    print("Identity     : " + str(identity))
+    if include_destination:
+        print("Listening on : " + RNS.prettyhexrep(destination.hash))
+
+    exit(0)
+
+verbose_set = False
+
+def ensure_config_directory():
+    if os.path.isdir(os.path.expanduser("~/.config/rnsh")): return os.path.expanduser("~/.config/rnsh")
+    elif os.path.isdir(os.path.expanduser("~/.rnsh")): return os.path.expanduser("~/.rnsh")
+    else:
+        try:
+            os.makedirs(os.path.expanduser("~/.rnsh"))
+            return os.path.expanduser("~/.rnsh")
+
+        except Exception as e:
+            RNS.log(f"Could not get or create rnsh configuration directory, aborting", RNS.LOG_CRITICAL)
+            os._exit(1)
+
+
+async def _rnsh_cli_main():
+    global verbose_set
+    args, parser = parse_arguments()
+    verbose_set = args.verbose > 0
+
+    configdir = ensure_config_directory()
+
+    if args.print_identity:
+        print_identity(args.config, args.identity, args.service, args.listen)
+        return 0
+
+    if args.listen:
+        allowed_file = None
+        dest_len = (RNS.Reticulum.TRUNCATED_HASHLENGTH//8)*2
+        if os.path.isfile(os.path.expanduser("~/.config/rnsh/allowed_identities")):
+            allowed_file = os.path.expanduser("~/.config/rnsh/allowed_identities")
+        elif os.path.isfile(os.path.expanduser("~/.rnsh/allowed_identities")):
+            allowed_file = os.path.expanduser("~/.rnsh/allowed_identities")
+
+        await listener.listen(configdir=configdir,
+                              rnsconfigdir=args.config,
+                              command=args.command,
+                              identitypath=args.identity,
+                              service_name=args.service,
+                              verbosity=args.verbose,
+                              quietness=args.quiet,
+                              allowed=args.allowed or [],
+                              allowed_file=allowed_file,
+                              disable_auth=args.no_auth,
+                              announce_period=args.announce,
+                              no_remote_command=args.no_remote_command,
+                              remote_cmd_as_args=args.remote_command_as_args)
+        return 0
+
+    if args.destination is not None:
+        return_code = await initiator.initiate(configdir=configdir,
+                                               rnsconfigdir=args.config,
+                                               identitypath=args.identity,
+                                               verbosity=args.verbose,
+                                               quietness=args.quiet,
+                                               noid=args.no_id,
+                                               destination=args.destination,
+                                               timeout=args.timeout,
+                                               command=args.command
+        )
+        return return_code if args.mirror else 0
+    else:
+        print("")
+        parser.print_help()
+        print("")
+        return 1
+
+
+def main():
+    global verbose_set
+    return_code = 1
+    exc = None
+    try: return_code = asyncio.run(_rnsh_cli_main())
+    except SystemExit: pass
+    except KeyboardInterrupt: pass
+    except Exception as e:
+        print(f"{e}")
+        exc = e
+    
+    process.tty_unset_reader_callbacks(0)
+    if verbose_set and exc: raise exc
+    sys.exit(return_code if return_code is not None else 255)
+
+
+if __name__ == "__main__": main()

RNS/Utilities/rnsh/session.py

@@ -0,0 +1,441 @@
+#         Based on the original rnsh program by Aaron Heise (@acehoss)
+# https://github.com/acehoss/rnsh - MIT License - Copyright (c) 2023 Aaron Heise
+#     This version of rnsh is included in RNS under the Reticulum License
+#
+# Reticulum License
+#
+# Copyright (c) 2016-2026 Mark Qvist
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# - The Software shall not be used in any kind of system which includes amongst
+#   its functions the ability to purposefully do harm to human beings.
+#
+# - The Software shall not be used, directly or indirectly, in the creation of
+#   an artificial intelligence, machine learning or language model training
+#   dataset, including but not limited to any use that contributes to the
+#   training or development of such a model or algorithm.
+#
+# - The above copyright notice and this permission notice shall be included in
+#   all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+from __future__ import annotations
+import contextlib
+import functools
+import asyncio
+import RNS.Utilities.rnsh.exception as exception
+import RNS.Utilities.rnsh.process as process
+import RNS.Utilities.rnsh.helpers as helpers
+import RNS.Utilities.rnsh.protocol as protocol
+import enum
+from typing import TypeVar, Generic, Callable, List
+from abc import abstractmethod, ABC
+from multiprocessing import Manager
+import os
+import bz2
+import RNS
+
+_TLink = TypeVar("_TLink")
+_TIdentity = TypeVar("_TIdentity")
+
+class SEType(enum.IntEnum):
+    SE_LINK_CLOSED = 0
+
+class SessionException(Exception):
+    def __init__(self, setype: SEType, msg: str, *args):
+        super().__init__(msg, args)
+        self.type = setype
+
+class LSState(enum.IntEnum):
+    LSSTATE_WAIT_IDENT = 1
+    LSSTATE_WAIT_VERS  = 2
+    LSSTATE_WAIT_CMD   = 3
+    LSSTATE_RUNNING    = 4
+    LSSTATE_ERROR      = 5
+    LSSTATE_TEARDOWN   = 6
+
+
+class LSOutletBase(ABC):
+    @abstractmethod
+    def set_initiator_identified_callback(self, cb: Callable[[LSOutletBase, _TIdentity], None]): raise NotImplemented()
+
+    @abstractmethod
+    def set_link_closed_callback(self, cb: Callable[[LSOutletBase], None]): raise NotImplemented()
+
+    @abstractmethod
+    def unset_link_closed_callback(self): raise NotImplemented()
+
+    @property
+    @abstractmethod
+    def rtt(self): raise NotImplemented()
+
+    @abstractmethod
+    def teardown(self): raise NotImplemented()
+
+
+class ListenerSession:
+    sessions: List[ListenerSession] = []
+    allowed_identity_hashes: [any] = []
+    allowed_file_identity_hashes: [any] = []
+    allow_all: bool = False
+    allow_remote_command: bool = False
+    default_command: [str] = []
+    remote_cmd_as_args = False
+
+    def __init__(self, outlet: LSOutletBase, channel: RNS.Channel.Channel, loop: asyncio.AbstractEventLoop):
+        RNS.log(f"Session started for {outlet}", RNS.LOG_INFO)
+        self.outlet = outlet
+        self.channel = channel
+        self.outlet.set_initiator_identified_callback(self._initiator_identified)
+        self.outlet.set_link_closed_callback(self._link_closed)
+        self.loop = loop
+        self.state: LSState = None
+        self.remote_identity = None
+        self.term: str | None = None
+        self.stdin_is_pipe: bool = False
+        self.stdout_is_pipe: bool = False
+        self.stderr_is_pipe: bool = False
+        self.tcflags: [any] = None
+        self.cmdline: [str] = None
+        self.rows: int = 0
+        self.cols: int = 0
+        self.hpix: int = 0
+        self.vpix: int = 0
+        self.stdout_buf = bytearray()
+        self.stdout_eof_sent = False
+        self.stderr_buf = bytearray()
+        self.stderr_eof_sent = False
+        self.return_code: int | None = None
+        self.return_code_sent = False
+        self.process: process.CallbackSubprocess | None = None
+
+        if self.allow_all: self._set_state(LSState.LSSTATE_WAIT_VERS)
+        else: self._set_state(LSState.LSSTATE_WAIT_IDENT)
+
+        self.sessions.append(self)
+        protocol.register_message_types(self.channel)
+        self.channel.add_message_handler(self._handle_message)
+
+    def _terminated(self, return_code: int):
+        self.return_code = return_code
+
+    def _set_state(self, state: LSState, timeout_factor: float = 10.0):
+        timeout = max(self.outlet.rtt * timeout_factor, max(self.outlet.rtt * 2, 10)) if timeout_factor is not None else None
+        RNS.log(f"Set state: {state.name}, timeout {timeout}", RNS.LOG_DEBUG)
+        orig_state = self.state
+        self.state = state
+        if timeout_factor is not None:
+            self._call(functools.partial(self._check_protocol_timeout, lambda: self.state == orig_state, state.name), timeout)
+
+    def _call(self, func: callable, delay: float = 0):
+        def call_inner():
+            if delay == 0: func()
+            else: self.loop.call_later(delay, func)
+        
+        self.loop.call_soon_threadsafe(call_inner)
+
+    def send(self, message: RNS.MessageBase):
+        self.channel.send(message)
+
+    def _protocol_error(self, name: str):
+        self.terminate(f"Protocol error ({name})")
+
+    def _protocol_timeout_error(self, name: str):
+        self.terminate(f"Protocol timeout error: {name}")
+
+    def terminate(self, error: str = None):
+        with contextlib.suppress(Exception):
+            RNS.log("Terminating session" + (f": {error}" if error else ""), RNS.LOG_DEBUG)
+            if error and self.state != LSState.LSSTATE_TEARDOWN:
+                with contextlib.suppress(Exception):
+                    self.send(protocol.ErrorMessage(error, True))
+
+            self.state = LSState.LSSTATE_ERROR
+            self._terminate_process()
+            self._call(self._prune, max(self.outlet.rtt * 3, process.CallbackSubprocess.PROCESS_PIPE_TIME+5))
+
+    def _prune(self):
+        self.state = LSState.LSSTATE_TEARDOWN
+        RNS.log("Pruning session", RNS.LOG_DEBUG)
+        with contextlib.suppress(ValueError):
+            self.sessions.remove(self)
+        with contextlib.suppress(Exception):
+            self.outlet.teardown()
+
+    def _check_protocol_timeout(self, fail_condition: Callable[[], bool], name: str):
+        timeout = True
+        try: timeout = self.state != LSState.LSSTATE_TEARDOWN and fail_condition()
+        except Exception as e: RNS.log(f"Error in protocol timeout: {e}", RNS.LOG_ERROR)
+        if timeout: self._protocol_timeout_error(name)
+
+    def _link_closed(self, outlet: LSOutletBase):
+        outlet.unset_link_closed_callback()
+
+        if outlet != self.outlet:
+            RNS.log("Link closed received from incorrect outlet", RNS.LOG_DEBUG)
+            return
+
+        RNS.log(f"link_closed {outlet}", RNS.LOG_DEBUG)
+        self.terminate()
+
+    def _initiator_identified(self, outlet, identity):
+        if outlet != self.outlet:
+            RNS.log("Identity received from incorrect outlet", RNS.LOG_DEBUG)
+            return
+
+        RNS.log(f"initiator_identified {identity} on link {outlet}", RNS.LOG_INFO)
+        if self.state not in [LSState.LSSTATE_WAIT_IDENT, LSState.LSSTATE_WAIT_VERS]:
+            self._protocol_error(LSState.LSSTATE_WAIT_IDENT.name)
+
+        if not self.allow_all and identity.hash not in self.allowed_identity_hashes and identity.hash not in self.allowed_file_identity_hashes:
+            self.terminate("Identity is not allowed.")
+
+        self.remote_identity = identity
+        self._set_state(LSState.LSSTATE_WAIT_VERS)
+
+    @classmethod
+    async def pump_all(cls) -> True:
+        processed_any = False
+        for session in cls.sessions:
+            processed = session.pump()
+            processed_any = processed_any or processed
+            await asyncio.sleep(0)
+
+
+    @classmethod
+    async def terminate_all(cls, reason: str):
+        for session in cls.sessions:
+            session.terminate(reason)
+            await asyncio.sleep(0)
+
+    def pump(self) -> bool:
+        def compress_adaptive(buf: bytes):
+            comp_tries = RNS.RawChannelWriter.COMPRESSION_TRIES
+            comp_try = 1
+            comp_success = False
+            
+            chunk_len = len(buf)
+            if chunk_len > RNS.RawChannelWriter.MAX_CHUNK_LEN:
+                chunk_len = RNS.RawChannelWriter.MAX_CHUNK_LEN
+            chunk_segment = None
+
+            chunk_segment = None
+            max_data_len = self.channel.mdu - protocol.StreamDataMessage.OVERHEAD
+            while chunk_len > 32 and comp_try < comp_tries:
+                chunk_segment_length = int(chunk_len/comp_try)
+                compressed_chunk = bz2.compress(buf[:chunk_segment_length])
+                compressed_length = len(compressed_chunk)
+                if compressed_length < max_data_len and compressed_length < chunk_segment_length:
+                    comp_success = True
+                    break
+                else:
+                    comp_try += 1
+
+            if comp_success:
+                diff = max_data_len - len(compressed_chunk)
+                chunk = compressed_chunk
+                processed_length = chunk_segment_length
+            else:
+                chunk = bytes(buf[:max_data_len])
+                processed_length = len(chunk)
+
+            return comp_success, processed_length, chunk
+
+        try:
+            if self.state != LSState.LSSTATE_RUNNING:
+                return False
+            elif not self.channel.is_ready_to_send():
+                return False
+            elif len(self.stderr_buf) > 0:
+                comp_success, processed_length, data = compress_adaptive(self.stderr_buf)
+                self.stderr_buf = self.stderr_buf[processed_length:]
+                send_eof = self.process.stderr_eof and len(data) == 0 and not self.stderr_eof_sent
+                self.stderr_eof_sent = self.stderr_eof_sent or send_eof
+                msg = protocol.StreamDataMessage(protocol.StreamDataMessage.STREAM_ID_STDERR,
+                                                 data, send_eof, comp_success)
+                self.send(msg)
+                if send_eof:
+                    self.stderr_eof_sent = True
+                return True
+            elif len(self.stdout_buf) > 0:
+                comp_success, processed_length, data = compress_adaptive(self.stdout_buf)
+                self.stdout_buf = self.stdout_buf[processed_length:]
+                send_eof = self.process.stdout_eof and len(data) == 0 and not self.stdout_eof_sent
+                self.stdout_eof_sent = self.stdout_eof_sent or send_eof
+                msg = protocol.StreamDataMessage(protocol.StreamDataMessage.STREAM_ID_STDOUT,
+                                                 data, send_eof, comp_success)
+                self.send(msg)
+                if send_eof:
+                    self.stdout_eof_sent = True
+                return True
+            elif self.return_code is not None and not self.return_code_sent:
+                msg = protocol.CommandExitedMessage(self.return_code)
+                self.send(msg)
+                self.return_code_sent = True
+                self._call(functools.partial(self._check_protocol_timeout,
+                                             lambda: self.state == LSState.LSSTATE_RUNNING, "CommandExitedMessage"),
+                           max(self.outlet.rtt * 5, 10))
+                return False
+        
+        except Exception as e: RNS.log(f"Error during pump: {e}", RNS.LOG_ERROR)
+        return False
+
+    def _terminate_process(self):
+        with contextlib.suppress(Exception):
+            if self.process and self.process.running:
+                self.process.terminate()
+
+    def _start_cmd(self, cmdline: [str], pipe_stdin: bool, pipe_stdout: bool, pipe_stderr: bool, tcflags: [any],
+                   term: str | None, rows: int, cols: int, hpix: int, vpix: int):
+
+        self.cmdline = self.default_command
+        if not self.allow_remote_command and cmdline and len(cmdline) > 0:
+            self.terminate("Remote command line not allowed by listener")
+            return
+
+        if self.remote_cmd_as_args and cmdline and len(cmdline) > 0:
+            self.cmdline.extend(cmdline)
+        elif cmdline and len(cmdline) > 0:
+            self.cmdline = cmdline
+
+
+        self.stdin_is_pipe = pipe_stdin
+        self.stdout_is_pipe = pipe_stdout
+        self.stderr_is_pipe = pipe_stderr
+        self.tcflags = tcflags
+        self.term = term
+
+        def stdout(data: bytes):
+            self.stdout_buf.extend(data)
+
+        def stderr(data: bytes):
+            self.stderr_buf.extend(data)
+
+        try:
+            self.process = process.CallbackSubprocess(argv=self.cmdline,
+                                                      env={"TERM": self.term or os.environ.get("TERM") or "xterm",
+                                                            "RNS_REMOTE_IDENTITY": (RNS.prettyhexrep(self.remote_identity.hash)
+                                                                if self.remote_identity and self.remote_identity.hash else "")},
+                                                      loop=self.loop,
+                                                      stdout_callback=stdout,
+                                                      stderr_callback=stderr,
+                                                      terminated_callback=self._terminated,
+                                                      stdin_is_pipe=self.stdin_is_pipe,
+                                                      stdout_is_pipe=self.stdout_is_pipe,
+                                                      stderr_is_pipe=self.stderr_is_pipe)
+            self.process.start()
+            self._set_window_size(rows, cols, hpix, vpix)
+        except Exception as e:
+            RNS.log(f"Unable to start process for link {self.outlet}: {e}", RNS.LOG_ERROR)
+            self.terminate("Unable to start process")
+
+    def _set_window_size(self, rows: int, cols: int, hpix: int, vpix: int):
+        self.rows = rows
+        self.cols = cols
+        self.hpix = hpix
+        self.vpix = vpix
+        with contextlib.suppress(Exception):
+            self.process.set_winsize(rows, cols, hpix, vpix)
+
+    def _received_stdin(self, data: bytes, eof: bool):
+        if data and len(data) > 0:
+            self.process.write(data)
+        if eof:
+            self.process.close_stdin()
+
+    def _handle_message(self, message: RNS.MessageBase):
+        if self.state == LSState.LSSTATE_WAIT_IDENT:
+            # Ignore any messages until the initiator has identified to avoid race conditions
+            # between identity announcement and early protocol messages.
+            RNS.log("Ignoring message while waiting for identification", RNS.LOG_DEBUG)
+            return
+        if self.state == LSState.LSSTATE_WAIT_VERS:
+            if not isinstance(message, protocol.VersionInfoMessage):
+                self._protocol_error(self.state.name)
+                return
+            RNS.log(f"Version {message.sw_version}, protocol {message.protocol_version} on link {self.outlet}", RNS.LOG_VERBOSE)
+            if message.protocol_version != protocol.PROTOCOL_VERSION:
+                self.terminate("Incompatible protocol")
+                return
+            self.send(protocol.VersionInfoMessage())
+            self._set_state(LSState.LSSTATE_WAIT_CMD)
+            return
+        elif self.state == LSState.LSSTATE_WAIT_CMD:
+            if not isinstance(message, protocol.ExecuteCommandMesssage):
+                return self._protocol_error(self.state.name)
+            RNS.log(f"Execute command message on link {self.outlet}: {message.cmdline}", RNS.LOG_VERBOSE)
+            self._set_state(LSState.LSSTATE_RUNNING)
+            self._start_cmd(message.cmdline, message.pipe_stdin, message.pipe_stdout, message.pipe_stderr,
+                            message.tcflags, message.term, message.rows, message.cols, message.hpix, message.vpix)
+            return
+        elif self.state == LSState.LSSTATE_RUNNING:
+            if isinstance(message, protocol.WindowSizeMessage):
+                self._set_window_size(message.rows, message.cols, message.hpix, message.vpix)
+            elif isinstance(message, protocol.StreamDataMessage):
+                if message.stream_id != protocol.StreamDataMessage.STREAM_ID_STDIN:
+                    RNS.log(f"Received stream data for invalid stream {message.stream_id} on link {self.outlet}", RNS.LOG_ERROR)
+                    return self._protocol_error(self.state.name)
+                self._received_stdin(message.data, message.eof)
+                return
+            elif isinstance(message, protocol.NoopMessage):
+                # echo noop only on listener--used for keepalive/connectivity check
+                self.send(message)
+                return
+        elif self.state in [LSState.LSSTATE_ERROR, LSState.LSSTATE_TEARDOWN]:
+            RNS.log(f"Received packet, but in state {self.state.name}", RNS.LOG_ERROR)
+            return
+        else:
+            self._protocol_error("unexpected message")
+            return
+
+
+class RNSOutlet(LSOutletBase):
+
+    def set_initiator_identified_callback(self, cb: Callable[[LSOutletBase, _TIdentity], None]):
+        def inner_cb(link, identity: _TIdentity):
+            cb(self, identity)
+
+        self.link.set_remote_identified_callback(inner_cb)
+
+    def set_link_closed_callback(self, cb: Callable[[LSOutletBase], None]):
+        def inner_cb(link):
+            cb(self)
+
+        self.link.set_link_closed_callback(inner_cb)
+
+    def unset_link_closed_callback(self):
+        self.link.set_link_closed_callback(None)
+
+    def teardown(self):
+        self.link.teardown()
+
+    @property
+    def rtt(self) -> float:
+        return self.link.rtt
+
+    def __str__(self):
+        return f"Outlet RNS Link {self.link}"
+
+    def __init__(self, link: RNS.Link):
+        self.link = link
+        link.lsoutlet = self
+
+    @staticmethod
+    def get_outlet(link: RNS.Link):
+        if hasattr(link, "lsoutlet"):
+            return link.lsoutlet
+
+        return RNSOutlet(link)

RNS/Utilities/rnstatus.py

@@ -35,6 +35,7 @@ import os
 import sys
 import time
 import argparse
+import io
 
 from RNS._version import __version__
 
@@ -141,14 +142,12 @@ def get_remote_status(destination_hash, include_lstats, identity, no_output=Fals
 
     return request_result
 
-def program_setup(configdir, dispall=False, verbosity=0, name_filter=None, json=False, astats=False,
-                  lstats=False, sorting=None, sort_reverse=False, remote=None, management_identity=None,
-                  remote_timeout=RNS.Transport.PATH_REQUEST_TIMEOUT, must_exit=True, rns_instance=None, traffic_totals=False):
-    
-    if remote:
-        require_shared = False
-    else:
-        require_shared = True
+def program_setup(configdir, dispall=False, verbosity=0, name_filter=None, json=False, astats=False, lstats=False, sorting=None, sort_reverse=False,
+                  remote=None, management_identity=None, remote_timeout=RNS.Transport.PATH_REQUEST_TIMEOUT, must_exit=True, rns_instance=None,
+                  traffic_totals=False, discovered_interfaces=False, config_entries=False):
+  
+    if remote: require_shared = False
+    else: require_shared = True
 
     try:
         if rns_instance:
@@ -159,13 +158,146 @@ def program_setup(configdir, dispall=False, verbosity=0, name_filter=None, json=
 
     except Exception as e:
         print("No shared RNS instance available to get status from")
-        if must_exit:
-            exit(1)
-        else:
-            return
+        if must_exit: exit(1)
+        else: return
 
     link_count = None
     stats = None
+
+    details = False
+    if config_entries:
+        discovered_interfaces = True
+        details = True
+
+    if discovered_interfaces:
+        if_discovery = RNS.Discovery.InterfaceDiscovery(discover_interfaces=False)
+        ifs = if_discovery.list_discovered_interfaces()
+        print("")
+
+        if json:
+            import json
+            for i in ifs:
+                for e in i:
+                    if isinstance(i[e], bytes): i[e] = RNS.hexrep(i[e], delimit=False)
+          
+            print(json.dumps(ifs))
+
+        else:
+            filtered_ifs = []
+            for i in ifs:
+                name = i["name"]
+                if not name_filter or name_filter.lower() in name.lower(): filtered_ifs.append(i)
+          
+            if details:
+                for idx, i in enumerate(filtered_ifs):
+                    try:
+                        name = i["name"]
+                        if_type = i["type"]
+                        status = i["status"]
+
+                        if status == "available": status_display = "Available"
+                        elif status == "unknown": status_display = "Unknown"
+                        elif status == "stale":   status_display = "Stale"
+                        else:                     status_display = status
+
+                        now  = time.time()
+                        dago = now-i["discovered"]
+                        hago = now-i["last_heard"]
+                        discovered_display = f"{RNS.prettytime(dago, compact=True)} ago"
+                        last_heard_display = f"{RNS.prettytime(hago, compact=True)} ago"
+                        transport_str = "Enabled" if i["transport"] else "Disabled"
+
+                        if i["latitude"] is not None and i["longitude"] is not None:
+                            lat = round(i["latitude"], 4)
+                            lon = round(i["longitude"], 4)
+                            if i["height"] != None: height = ", "+str(i["height"])+"m h"
+                            else: height = ""
+                            location = f"{lat}, {lon}{height}"
+                        else: location = "Unknown"
+
+                        transport_id = None
+                        network = None
+                        if "transport_id" in i: transport_id = i["transport_id"]
+                        if "transport_id" in i and "network_id" in i and i["transport_id"] != i["network_id"]:
+                            network = i["network_id"]
+
+                        if idx > 0:      print("\n"+"="*32+"\n")
+                        if network:      print(f"Network   ID : {network}")
+                        if transport_id: print(f"Transport ID : {transport_id}")
+
+                        print(f"Name         : {name}")
+                        print(f"Type         : {if_type}")
+                        print(f"Status       : {status_display}")
+                        print(f"Transport    : {transport_str}")
+                        print(f"Distance     : {i['hops']} hop{'' if i['hops'] == 1 else 's'}")
+                        print(f"Discovered   : {discovered_display}")
+                        print(f"Last Heard   : {last_heard_display}")
+                        print(f"Location     : {location}")
+
+                        if "frequency" in i:    print(f"Frequency    : {i['frequency']:,} Hz")
+                        if "bandwidth" in i:    print(f"Bandwidth    : {i['bandwidth']:,} Hz")
+                        if "sf" in i:           print(f"Sprd. Factor : {i['sf']}")
+                        if "cr" in i:           print(f"Coding Rate  : {i['cr']}")
+                        if "modulation" in i:   print(f"Modulation   : {i['modulation']}")
+                        if "reachable_on" in i: print(f"Address      : {i['reachable_on']}")
+                        if "port" in i:         print(f"Port         : {i['port']}")
+
+                        print(f"Stamp Value  : {i['value']}")
+
+                        print(f"\nConfiguration Entry:")
+                        config_lines = i["config_entry"].split('\n')
+                        for line in config_lines: print(f"  {line}")
+
+                    except Exception as e:
+                        pass
+              
+            else:
+                print(f"{'Name':<25} {'Type':<12} {'Status':<12} {'Last Heard':<12} {'Value':<8} {'Location':<15}")
+                print("-" * 89)
+                
+                for i in filtered_ifs:
+                    try:
+                        name = i["name"][:24] + "…" if len(i["name"]) > 24 else i["name"]
+                        
+                        if_type = i["type"].replace("Interface", "")
+                        
+                        status = i["status"]
+                        if status == "available": status_display = "✓ Available"
+                        elif status == "unknown": status_display = "? Unknown"
+                        elif status == "stale":   status_display = "× Stale"
+                        else:                     status_display = status
+                        
+                        now = time.time()
+                        last_heard = i["last_heard"]
+                        diff = now - last_heard
+                        
+                        if diff < 60: last_heard_display = "Just now"
+                        elif diff < 3600:
+                            mins = int(diff / 60)
+                            last_heard_display = f"{mins}m ago"
+                        elif diff < 86400:
+                            hours = int(diff / 3600)
+                            last_heard_display = f"{hours}h ago"
+                        else:
+                            days = int(diff / 86400)
+                            last_heard_display = f"{days}d ago"
+                        
+                        value = str(i["value"])
+                        
+                        if i["latitude"] is not None and i["longitude"] is not None:
+                            lat = round(i["latitude"], 4)
+                            lon = round(i["longitude"], 4)
+                            location = f"{lat}, {lon}"
+                        else: location = "N/A"
+                        
+                        print(f"{name:<25} {if_type:<12} {status_display:<12} {last_heard_display:<12} {value:<8} {location:<15}")
+
+                    except Exception as e:
+                        pass
+
+        if must_exit: exit(0)
+        else: return
+
     if remote:
         try:
             if management_identity is None:
@@ -190,25 +322,19 @@ def program_setup(configdir, dispall=False, verbosity=0, name_filter=None, json=
                     stats, link_count = remote_status
             except Exception as e:
                 raise e
-                    
+                  
         except Exception as e:
             print(str(e))
-            if must_exit:
-                exit(20)
-            else:
-                return
+            if must_exit: exit(20)
+            else: return
 
     else:
         if lstats:
-            try:
-                link_count = reticulum.get_link_count()
-            except Exception as e:
-                pass
+            try: link_count = reticulum.get_link_count()
+            except Exception as e: pass
 
-        try:
-            stats = reticulum.get_interface_stats()
-        except Exception as e:
-            pass
+        try: stats = reticulum.get_interface_stats()
+        except Exception as e: pass
 
     if stats != None:
         if json:
@@ -225,10 +351,8 @@ def program_setup(configdir, dispall=False, verbosity=0, name_filter=None, json=
                                     i[k] = RNS.hexrep(i[k], delimit=False)
 
             print(json.dumps(stats))
-            if must_exit:
-                exit()
-            else:
-                return
+            if must_exit: exit()
+            else: return
 
         interfaces = stats["interfaces"]
         if sorting != None and isinstance(sorting, str):
@@ -254,7 +378,7 @@ def program_setup(configdir, dispall=False, verbosity=0, name_filter=None, json=
             if sorting == "held":
                 interfaces.sort(key=lambda i: i["held_announces"], reverse=not sort_reverse)
 
-            
+          
         for ifstat in interfaces:
             name = ifstat["name"]
 
@@ -312,6 +436,9 @@ def program_setup(configdir, dispall=False, verbosity=0, name_filter=None, json=
 
                         print(" {n}".format(n=ifstat["name"]))
 
+                        if "autoconnect_source" in ifstat and ifstat["autoconnect_source"] != None:
+                            print("    Source    : Auto-connect via <{ns}>".format(ns=ifstat["autoconnect_source"]))
+
                         if "ifac_netname" in ifstat and ifstat["ifac_netname"] != None:
                             print("    Network   : {nn}".format(nn=ifstat["ifac_netname"]))
 
@@ -327,10 +454,20 @@ def program_setup(configdir, dispall=False, verbosity=0, name_filter=None, json=
                             print("    Rate      : {ss}".format(ss=speed_str(ifstat["bitrate"])))
 
                         if "noise_floor" in ifstat:
-                            if ifstat["noise_floor"] != None:
-                                print("    Noise Fl. : {nfl} dBm".format(nfl=str(ifstat["noise_floor"])))
+                            if not "interference" in ifstat: nstr = ""
                             else:
-                                print("    Noise Fl. : Unknown")
+                                nf = ifstat["interference"]
+                                lstr = ", no interference"
+                                if "interference_last_ts" in ifstat and "interference_last_dbm" in ifstat:
+                                    lago = time.time()-ifstat["interference_last_ts"]
+                                    ldbm = ifstat["interference_last_dbm"]
+                                    lstr = f"\n    Intrfrnc. : {ldbm} dBm {RNS.prettytime(lago, compact=True)} ago"
+
+
+                                nstr = f"\n    Intrfrnc. : {nf} dBm" if nf else lstr
+
+                            if ifstat["noise_floor"] != None: print("    Noise Fl. : {nfl} dBm{ntr}".format(nfl=str(ifstat["noise_floor"]), ntr=nstr))
+                            else: print("    Noise Fl. : Unknown")
 
                         if "cpu_load" in ifstat:
                             if ifstat["cpu_load"] != None: print("    CPU load  : {v} %".format(v=str(ifstat["cpu_load"])))
@@ -354,7 +491,7 @@ def program_setup(configdir, dispall=False, verbosity=0, name_filter=None, json=
 
                         if "airtime_short" in ifstat and "airtime_long" in ifstat:
                             print("    Airtime   : {ats}% (15s), {atl}% (1h)".format(ats=str(ifstat["airtime_short"]),atl=str(ifstat["airtime_long"])))
-                        
+                      
                         if "channel_load_short" in ifstat and "channel_load_long" in ifstat:
                             print("    Ch. Load  : {ats}% (15s), {atl}% (1h)".format(ats=str(ifstat["channel_load_short"]),atl=str(ifstat["channel_load_long"])))
 
@@ -379,7 +516,7 @@ def program_setup(configdir, dispall=False, verbosity=0, name_filter=None, json=
                         if "ifac_signature" in ifstat and ifstat["ifac_signature"] != None:
                             sigstr = "<…"+RNS.hexrep(ifstat["ifac_signature"][-5:], delimit=False)+">"
                             print("    Access    : {nb}-bit IFAC by {sig}".format(nb=ifstat["ifac_size"]*8, sig=sigstr))
-                        
+                      
                         if "i2p_b32" in ifstat and ifstat["i2p_b32"] != None:
                             print("    I2P B32   : {ep}".format(ep=str(ifstat["i2p_b32"])))
 
@@ -389,14 +526,14 @@ def program_setup(configdir, dispall=False, verbosity=0, name_filter=None, json=
                                 print("    Queued    : {np} announce".format(np=aqn))
                             else:
                                 print("    Queued    : {np} announces".format(np=aqn))
-                        
+                      
                         if astats and "held_announces" in ifstat and ifstat["held_announces"] != None and ifstat["held_announces"] > 0:
                             aqn = ifstat["held_announces"]
                             if aqn == 1:
                                 print("    Held      : {np} announce".format(np=aqn))
                             else:
                                 print("    Held      : {np} announces".format(np=aqn))
-                        
+                      
                         if astats and "incoming_announce_frequency" in ifstat and ifstat["incoming_announce_frequency"] != None:
                             print("    Announces : {iaf}↑".format(iaf=RNS.prettyfrequency(ifstat["outgoing_announce_frequency"])))
                             print("                {iaf}↓".format(iaf=RNS.prettyfrequency(ifstat["incoming_announce_frequency"])))
@@ -414,7 +551,7 @@ def program_setup(configdir, dispall=False, verbosity=0, name_filter=None, json=
                         if "rxs" in ifstat and "txs" in ifstat:
                             rxstat += "  "+RNS.prettyspeed(ifstat["rxs"])
                             txstat += "  "+RNS.prettyspeed(ifstat["txs"])
-                        
+                      
                         print(f"    Traffic   : {txstat}\n                {rxstat}")
 
         lstr = ""
@@ -440,6 +577,8 @@ def program_setup(configdir, dispall=False, verbosity=0, name_filter=None, json=
 
         if "transport_id" in stats and stats["transport_id"] != None:
             print("\n Transport Instance "+RNS.prettyhexrep(stats["transport_id"])+" running")
+            if "network_id" in stats and stats["network_id"] != None:
+                print(" Network Identity   "+RNS.prettyhexrep(stats["network_id"]))
             if "probe_responder" in stats and stats["probe_responder"] != None:
                 print(" Probe responder at "+RNS.prettyhexrep(stats["probe_responder"])+ " active")
             if "transport_uptime" in stats and stats["transport_uptime"] != None:
@@ -449,7 +588,7 @@ def program_setup(configdir, dispall=False, verbosity=0, name_filter=None, json=
                 print(f"\n{lstr}")
 
         print("")
-                
+              
     else:
         if not remote:
             print("Could not get RNS status")
@@ -466,125 +605,67 @@ def main(must_exit=True, rns_instance=None):
         parser.add_argument("--config", action="store", default=None, help="path to alternative Reticulum config directory", type=str)
         parser.add_argument("--version", action="version", version="rnstatus {version}".format(version=__version__))
 
-        parser.add_argument(
-            "-a",
-            "--all",
-            action="store_true",
-            help="show all interfaces",
-            default=False
-        )
-        
-        parser.add_argument(
-            "-A",
-            "--announce-stats",
-            action="store_true",
-            help="show announce stats",
-            default=False
-        )
-        
-        parser.add_argument(
-            "-l",
-            "--link-stats",
-            action="store_true",
-            help="show link stats",
-            default=False,
-        )
-        
-        parser.add_argument(
-            "-t",
-            "--totals",
-            action="store_true",
-            help="display traffic totals",
-            default=False,
-        )
-        
-        parser.add_argument(
-            "-s",
-            "--sort",
-            action="store",
-            help="sort interfaces by [rate, traffic, rx, tx, rxs, txs, announces, arx, atx, held]",
-            default=None,
-            type=str
-        )
-        
-        parser.add_argument(
-            "-r",
-            "--reverse",
-            action="store_true",
-            help="reverse sorting",
-            default=False,
-        )
-        
-        parser.add_argument(
-            "-j",
-            "--json",
-            action="store_true",
-            help="output in JSON format",
-            default=False
-        )
-
-        parser.add_argument(
-            "-R",
-            action="store",
-            metavar="hash",
-            help="transport identity hash of remote instance to get status from",
-            default=None,
-            type=str
-        )
-
-        parser.add_argument(
-            "-i",
-            action="store",
-            metavar="path",
-            help="path to identity used for remote management",
-            default=None,
-            type=str
-        )
-
-        parser.add_argument(
-            "-w",
-            action="store",
-            metavar="seconds",
-            type=float,
-            help="timeout before giving up on remote queries",
-            default=RNS.Transport.PATH_REQUEST_TIMEOUT
-        )
-
+        parser.add_argument("-a", "--all", action="store_true", help="show all interfaces", default=False)
+        parser.add_argument("-A", "--announce-stats", action="store_true", help="show announce stats", default=False)
+        parser.add_argument("-l", "--link-stats", action="store_true", help="show link stats", default=False)
+        parser.add_argument("-t", "--totals", action="store_true", help="display traffic totals", default=False)
+        parser.add_argument("-s", "--sort", action="store", help="sort interfaces by [rate, traffic, rx, tx, rxs, txs, announces, arx, atx, held]", default=None, type=str)
+        parser.add_argument("-r", "--reverse", action="store_true", help="reverse sorting", default=False)
+        parser.add_argument("-j", "--json", action="store_true", help="output in JSON format", default=False)
+        parser.add_argument("-R", action="store", metavar="hash", help="transport identity hash of remote instance to get status from", default=None, type=str)
+        parser.add_argument("-i", action="store", metavar="path", help="path to identity used for remote management", default=None, type=str)
+        parser.add_argument("-w", action="store", metavar="seconds", type=float, help="timeout before giving up on remote queries", default=RNS.Transport.PATH_REQUEST_TIMEOUT)
+        parser.add_argument("-d", "--discovered", action="store_true", help="list discovered interfaces", default=False)
+        parser.add_argument("-D",                 action="store_true", help="show details and config entries for discovered interfaces", default=False)
+        parser.add_argument("-m", "--monitor", action="store_true", help="continuously monitor status", default=False)
+        parser.add_argument("-I", "--monitor-interval", action="store", metavar="seconds", type=float, help="refresh interval for monitor mode (default: 1)", default=1.0)
         parser.add_argument('-v', '--verbose', action='count', default=0)
-
         parser.add_argument("filter", nargs="?", default=None, help="only display interfaces with names including filter", type=str)
-        
+      
         args = parser.parse_args()
 
-        if args.config:
-            configarg = args.config
-        else:
-            configarg = None
+        if args.config: configarg = args.config
+        else:           configarg = None
 
-        program_setup(
-            configdir = configarg,
-            dispall = args.all,
-            verbosity=args.verbose,
-            name_filter=args.filter,
-            json=args.json,
-            astats=args.announce_stats,
-            lstats=args.link_stats,
-            sorting=args.sort,
-            sort_reverse=args.reverse,
-            remote=args.R,
-            management_identity=args.i,
-            remote_timeout=args.w,
-            must_exit=must_exit,
-            rns_instance=rns_instance,
-            traffic_totals=args.totals,
-        )
+        if args.monitor:
+            if args.R: require_shared = False
+            else:      require_shared = True
+          
+            try: reticulum = RNS.Reticulum(configdir=configarg, loglevel=3+args.verbose, require_shared_instance=require_shared)
+            except Exception as e:
+                print("No shared RNS instance available to get status from")
+                exit(1)
+
+            while True:
+                buffer = io.StringIO()
+                old_stdout = sys.stdout
+                sys.stdout = buffer
+              
+                try:
+                    program_setup(configdir = configarg, dispall = args.all, verbosity=args.verbose, name_filter=args.filter, json=args.json,
+                                  astats=args.announce_stats, lstats=args.link_stats, sorting=args.sort, sort_reverse=args.reverse, remote=args.R,
+                                  management_identity=args.i, remote_timeout=args.w, must_exit=False, rns_instance=reticulum, traffic_totals=args.totals,
+                                  discovered_interfaces=args.discovered, config_entries=args.D)
+              
+                finally:
+                    sys.stdout = old_stdout
+              
+                output = buffer.getvalue()
+                print("\033[H\033[2J", end="")
+                print(output, end="", flush=True)
+              
+                time.sleep(args.monitor_interval)
+
+        else:
+            program_setup(configdir = configarg, dispall = args.all, verbosity=args.verbose, name_filter=args.filter, json=args.json,
+                          astats=args.announce_stats, lstats=args.link_stats, sorting=args.sort, sort_reverse=args.reverse, remote=args.R,
+                          management_identity=args.i, remote_timeout=args.w, must_exit=must_exit, rns_instance=rns_instance, traffic_totals=args.totals,
+                          discovered_interfaces=args.discovered, config_entries=args.D)
 
     except KeyboardInterrupt:
         print("")
-        if must_exit:
-            exit()
-        else:
-            return
+        if must_exit: exit()
+        else: return
 
 def speed_str(num, suffix='bps'):
     units = ['','k','M','G','T','P','E','Z']

RNS/__init__.py

@@ -44,6 +44,7 @@ from .Link import Link, RequestReceipt
 from .Channel import MessageBase
 from .Buffer import Buffer, RawChannelReader, RawChannelWriter
 from .Transport import Transport
+from .Discovery import InterfaceAnnouncer
 from .Destination import Destination
 from .Packet import Packet
 from .Packet import PacketReceipt
@@ -142,18 +143,16 @@ def log(msg, level=3, _override_destination = False, pt=False):
         with logging_lock:
             if (logdest == LOG_STDOUT or _always_override_destination or _override_destination):
                 if not threading.main_thread().is_alive(): return
-                else: print(logstring)
+                else:
+                    try: print(logstring)
+                    except: pass
 
             elif (logdest == LOG_FILE and logfile != None):
                 try:
-                    file = open(logfile, "a")
-                    file.write(logstring+"\n")
-                    file.close()
-                    
+                    with open(logfile, "a") as file: file.write(logstring+"\n")
                     if os.path.getsize(logfile) > LOG_MAXSIZE:
                         prevfile = logfile+".1"
-                        if os.path.isfile(prevfile):
-                            os.unlink(prevfile)
+                        if os.path.isfile(prevfile): os.unlink(prevfile)
                         os.rename(logfile, prevfile)
 
                 except Exception as e:
@@ -163,8 +162,7 @@ def log(msg, level=3, _override_destination = False, pt=False):
                     log(msg, level)
 
             elif logdest == LOG_CALLBACK:
-                try:
-                    logcall(logstring)
+                try: logcall(logstring)
                 except Exception as e:
                     _always_override_destination = True
                     log("Exception occurred while calling external log handler: "+str(e), LOG_CRITICAL)
@@ -199,6 +197,11 @@ def prettyhexrep(data):
     hexrep = "<"+delimiter.join("{:02x}".format(c) for c in data)+">"
     return hexrep
 
+def prettyb256rep(data):
+    delimiter = ""
+    b256rep = "<"+delimiter.join(b256_rep(c) for c in data)+">"
+    return b256rep
+
 def prettyspeed(num, suffix="b"):
     return prettysize(num/8, suffix=suffix)+"ps"
 
@@ -222,6 +225,7 @@ def prettysize(num, suffix='B'):
     return "%.2f%s%s" % (num, last_unit, suffix)
 
 def prettyfrequency(hz, suffix="Hz"):
+    if hz == 0: return "0 Hz"
     num = hz*1e6
     units = ["µ", "m", "", "K","M","G","T","P","E","Z"]
     last_unit = "Y"
@@ -541,4 +545,26 @@ class Profiler:
             if tag["super"] == None:
                 print_results_recursive(tag, results)
 
-profile = Profiler.get_profiler
+profile = Profiler.get_profiler
+
+b256 = [
+# 0   1   2   3   4   5   6   7   8   9   A   B   C   D   F   F
+ "a","b","c","d","e","f","g","h","i","j","k","l","m","n","o","p",  # 0x0 Latin & numerals
+ "q","r","s","t","u","v","x","y","z","æ","ø","0","1","2","3","4",  # 0x1 Latin & numerals
+ "A","B","C","D","E","F","G","H","I","J","K","L","M","N","O","P",  # 0x2 Latin & numerals
+ "Q","R","S","T","U","W","X","Y","Z","Æ","Ø","5","6","7","8","9",  # 0x3 Latin & numerals
+ "α","β","γ","δ","ε","ζ","η","θ","ι","κ","λ","μ","ν","ξ","π","ρ",  # 0x4 Greek
+ "σ","τ","φ","χ","ψ","ω","Γ","Δ","Θ","Λ","Ξ","Π","Σ","Φ","Ψ","Ω",  # 0x5 Greek
+ "Б","Д","Ж","З","И","Л","П","Ц","Ч","Ш","Щ","Ъ","Ы","Э","Ю","Я",  # 0x6 Cyrillic
+ "б","д","ж","з","и","л","п","ц","ч","ш","щ","ъ","ы","э","ю","я",  # 0x7 Cyrillic
+ "Ա","Բ","Գ","Դ","Ե","Զ","Է","Ը","Թ","Ժ","Ի","Խ","Ծ","Կ","Հ","Ձ",  # 0x8 Armenian Capitals
+ "Ղ","Ճ","Մ","Յ","Ն","Շ","Ո","Չ","Պ","Ջ","Վ","Ր","Ց","Ւ","Ք","Ֆ",  # 0x9 Armenian Captials
+ "ᚠ","ᚢ","ᚦ","ᚱ","ᚹ","ᚺ","ᚾ","ᛈ","ᛇ","ᛉ","ᛊ","ᛏ","ᛒ","ᛖ","ᛗ","ᛟ",   # 0xA Elder Futhark
+ "ｲ","ｳ","ｵ","ｶ","ｷ","ｹ","ｻ","ｼ","ｽ","ｾ","ﾀ","ﾁ","ﾃ","ﾄ","ﾅ","ﾇ",     # 0xB Katakana
+ "ﾈ","ﾋ","ﾌ","ﾍ","ﾎ","ﾏ","ﾐ","ﾑ","ﾒ","ﾓ","ﾔ","ﾗ","ﾘ","ﾙ","ﾚ","ﾜ",     # 0xC Katakana
+ "𐑐","𐑑","𐑒","𐑔","𐑕","𐑗","𐑙","𐑳","𐑶","𐑸","𐑹","𐑺","𐑻","𐑽","𐑾","𐑿",    # 0xD Shavian
+ "᱑","᱕","᱘","᱙","ᱚ","ᱝ","ᱟ","ᱣ","ᱦ","ᱨ","ᱬ","ᱭ","ᱰ","ᱳ","ᱶ","ᱷ", # 0xE Ol Chiki
+ "𐌳","𐌸","𐌾","𐐀","𐐁","𐐂","𐐆","𐐇","𐐈","𐐉","𐐊","𐐋","𐐌","𐐍","𐐎","𐐏", # 0xF Gothic & Deseret
+]
+
+def b256_rep(input_byte): return b256[int(input_byte)]

RNS/_version.py

@@ -1 +1 @@
-__version__ = "1.0.3"
+__version__ = "1.2.3"

Zen of Reticulum.md

@@ -0,0 +1,415 @@
+# Zen of Reticulum
+
+## I: The Illusion Of The Center
+
+For the better part of a generation, we have been taught to visualize the digital world through the lens of hierarchy. The mental maps we carry are dominated by a single, misleading image: **The Cloud**.
+
+We imagine the network as a vast, ethereal space "up there" or "out there". A centralized repository of services and data to which we, the lowly clients, must connect. We build our software with this assumption hardcoded into our logic: *There is a server. The server has the authority. The server knows the way. I must find the server to function*.
+
+This is the Client-Server mental model, and it is the primary obstacle to understanding Reticulum.
+
+### Fallacy Of The Cloud
+
+The first step in the Zen of Reticulum is to realize that *there is no cloud*. There is only other people's computers. When you build for the cloud, you are building *for* a landlord. You are accepting that your application's existence is conditional on the permission, uptime, and continued goodwill of a central authority.
+
+In Reticulum, you must shift your thinking from "connecting to" to "being among". Reticulum is not a service you subscribe to - *it is a fabric you inhabit*. There is no "up there". There is only *here* and *there*, and the space between them is peer-to-peer.
+
+### Decentralization Or Uncentralizability?
+
+It is common to hear the word "decentralized" thrown around in modern tech circles. But often, this is merely a marketing term for "slightly distributed centralization". A blockchain with a few dominant miners, or a federated protocol with a few giant servers. *In practice*, it's still centralized. It simply has a few centers instead of one.
+
+Reticulum goes further. It wants **Uncentralizability**.
+
+This is not a wishful political stance, but a foundational mathematical characteristic of the protocol, onto which everything else has been built. Reticulum assumes that every peer on the network is potentially hostile, and every link is potentially compromised. It is designed with no "privileged" nodes. While some nodes may act as Transport Instances - forwarding traffic for others - they do so *blindly*, and they only know about their immediate surroundings, and nothing more. They route based on cryptographic proofs, not on administrative privilege. They cannot see who is talking to whom, nor can they selectively manipulate traffic without breaking their own ability to route entirely.
+
+The system is designed to make hierarchy structurally impossible. You cannot hijack an address, because there is no central registry to hijack. You cannot block a user, because there is no central switch to flip. You can offer paths through the network, but you can't force anyone to use them.
+
+### Death To The Address
+
+To break free of the center, you must also let go of the concept of the "Address".
+
+In the IP world, an address is a location. It is a coordinate in a *deeply hierarchical* and static grid. If you move your computer to a different house, your address changes. If your router reboots, your address might change. Your *identity* is bound to your *location*, and therefore, it is fragile, and easily controlled.
+
+Reticulum abolishes this link between *Identity* and *Location*.
+
+In Reticulum, an address is not a place; it is a **Hash of an Identity**. It is a cryptographic representation of *who* you are, not *where* you are. Because of this, your address is portable. You can take a laptop from a WiFi cafe in Berlin, to a LoRa mesh in the mountains, to a packet radio link on a boat, and your "address" - your *Destination Hash* - never changes.
+
+The network does not route to a place; it routes to a *person* (or a machine). When you send a packet, you are not targeting a coordinate in a grid; you are encrypting a message for a specific entity. The network dynamically discovers where that entity currently resides, and it does so in a way where no one really knows where that entity is actually located physically.
+
+**Consider:**
+
+- **The Old Way:** *"I am at `192.168.1.5`. Come find me"*.
+- **The Zen Way:** *"I am `<327c1b2f87c9353e01769b01090b18f2>`. Wherever I am, my peers can reach me"*.
+
+Once you stop thinking about servers and start thinking about portable identities, where everyone can always reach everyone else directly, the illusion of the center fades away. You realize there *is* no center holding the network together. No coordinators or bureaucrats required. The network is simply the sum of its peers, communicating directly, sovereignly, and without a master.
+
+
+## II: Physics Of Trust
+*Paranoia Is A Great Design Principle*
+
+If we accept that there is no center - that the network is a chaotic, peer-to-peer mesh - we are forced to confront a terrifying reality: **There is no one guarding the door**.
+
+In the traditional networking mindset, we rely on the concept of the "trusted core". We assume our local coffee shop WiFi is safe, or that the backbone providers are neutral custodians. We build our security like a castle: strong walls on the outside, soft and trusting on the inside. We use encryption only when we step out into the "wild" internet.
+
+### Hostile Environments
+
+The Zen of Reticulum requires you to invert this. You must assume that *every* environment is hostile. This isn't cynicism, just uncaring physics.
+
+When you transmit information over radio waves, you are shouting into a crowded room. Anyone can listen. When you traverse the internet, your packets pass through routers controlled by strangers, corporations, and state actors. Assuming privacy in this environment without cryptographic protection is not optimism but gross negligence.
+
+Reticulum is built on the premise that every link is tapped, and every peer is a potential adversary. If your system cannot survive an adversary owning the physical layer, it cannot survive at all.
+
+But this is the paradox: By assuming the network is hostile, you make it safe. When you accept the dangers for what they are, they become manageable. When you stop trusting the infrastructure and start trusting the math, you eliminate the single point of failure: Human integrity.
+
+### Encryption Is Not A Feature
+
+In the world of TCP/IP, encryption is an afterthought. It is a layer we slap on top of the protocol (HTTPS, TLS) to patch the security holes of the original design. It is a "feature" you sometimes *enable* for "sensitive data". This is fundamentally flawed, since all data is sensitive.
+
+In Reticulum, encryption is **gravity**.
+
+It is not optional. It is not a plugin. It is the *fundamental force that allows the network to exist*. If you were to strip the encryption from Reticulum, the routing would break. The Transport system uses cryptographic signatures and entropy to verify paths and pass information. If packets were plaintext, intermediate nodes could not prove that a route was valid, nor could endpoints prevent spoofing or tampering.
+
+In Reticulum, the entropy of the encrypted packet *is* the routing logic.
+
+To ask for a version of Reticulum without encryption is like asking for a version of the ocean without liquid. You are not asking for a feature change; you're asking for a different physical universe. We design for a universe where information has mass, structure, and integrity.
+
+### Zero-Trust Architectures
+
+We must unlearn our reliance on **Institutional Trust**.
+
+For decades, we have been trained to trust authorities. We trust a website because a chain of Certificate Authorities (companies we don't know) vouches for it. We trust an app because it is in an app store (run by a corporation we don't control). We trust a message because it comes from a phone number assigned by a telecom. Yet, everything in our digital information sphere today is more untrustworthy and risky than a medieval second-hand underwear market.
+
+Reticulum replaces institutional trust with **Cryptographic Proof**.
+
+In Reticulum, you do not trust a node because it has a nice hostname or because it is listed in a directory. You trust it because it holds the private key corresponding to the Destination Hash you are communicating with. This trust is binary, mathematical, and **absolute**. Either the signature matches, or it does not. There is no "maybe".
+
+This shift moves the power from the institution to the individual. You become the ultimate arbiter of your own trust relationships. You decide which keys to accept, which paths to follow, and which identities to recognize.
+
+**Consider:**
+
+- **The Old Way:** *"I trust this site because the browser says the lock icon is green"*.
+- **The Zen Way:** *"I trust this destination because I have verified its hash fingerprint out-of-band, and the math confirms the signature"*.
+
+When you internalize the Physics of Trust, you stop looking for protection from firewalls, VPNs, and Terms of Service agreements. You realize that true security comes from the design of the protocol itself. You can stop trusting the cloud, and you start trusting the code - because you can verify it yourself.
+
+
+## III: Merits Of Scarcity
+*Every Bit Counts*
+
+We have grown addicted to abundance. In the modern digital ecosystem, bandwidth is treated as an endless, flat ocean. We stream high-definition video without a thought, we ship entire libraries of code just to render a single button, and we measure performance in gigabits per second. This abundance has hollowed out our craft. When constraints vanish, efficiency dies, and with it, a certain kind of Clarity and Quality.
+
+Reticulum asks you to step out of the ocean and onto the tightrope.
+
+### The Bandwidth Fallacy
+
+The Zen of Reticulum requires the realization that **5 bits per second is a valid speed**.
+
+To a modern developer, this sounds like paralysis. But there is a profound freedom in limits: When you have a gigabit connection, you can be incredibly sloppy. You can be wasteful. You can push your problems onto the infrastructure. *"It’s slow? Get a faster router"*.
+
+But on a high-latency, low-bandwidth link (be it a noisy HF radio channel or a tenuous LoRa hop) you cannot push problems anywhere. You must solve them. The network does not negotiate with waste.
+
+This forces a shift from consumption to interaction. You are no longer, then, consuming a service provided by a fat pipe; you are engaging in a careful negotiation with the physical medium. The medium becomes a partner in the conversation, not just a dumb conduit. You suddenly need to *understand the world to be in it*.
+
+### Cost Of A Byte
+
+In a scarce economy, a byte is not just data, but energy, time, and space.
+
+Every byte you transmit consumes battery life on a solar-powered node. It occupies valuable airtime that could have been used by another peer. It represents a measurable slice of the electromagnetic spectrum.
+
+When you internalize this, you begin to write code differently. You stop asking, "How much data can I send?" and start asking, "What is the *minimum* amount of information required to convey this intent? How can I best utilize my informational entropy?"
+
+This is where the elegance of Reticulum shines. The protocol is designed to strip away the non-essential. A link establishment takes three very small packets. A destination hash fits in 16 bytes. The overhead is vanishingly small, leaving almost the entire channel for the message itself.
+
+**Consider:**
+
+- **The Old Way:** *"I need to send a status update. I'll send a JSON object with metadata, timestamps, and user profile info (15KB)."*
+- **The Zen Way:** *"I need to send a status update. I'll send a single byte representing the state code. The context is already known."*
+
+This is of course optimization, but more importantly, *it is a form of respect*. Efficiency in a shared medium is an act of stewardship. By taking only what you need from the network, you leave room for others. The network listens to those who speak with purpose.
+
+### Flow & Time
+
+Scarcity also teaches us about time. We have become addicted to the *synchronous* now - the instant ping, the real-time stream. But Reticulum embraces *asynchronous* time.
+
+When links are intermittent and latency is measured in minutes or hours, "real-time" is an illusion. Reticulum doesn't encourage **Store and Forward** as a mere fallback, but as a primary mode of existence. You write a message, it propagates when it can, and it arrives when it arrives.
+
+This changes the psychological texture of communication. It removes the anxiety of the immediate response. It allows for contemplation. You are not demanding the recipient's attention *right now*; you are placing a gift in their path, to be found when they are ready.
+
+By designing for delay, you design for resilience. You are no longer building a house of cards that collapses when a single packet drops. You are building a stone arch that distributes the load *over time*.
+
+### Liberation From Limits
+
+There is a strange optimism in scarcity. When you are forced to work within strict constraints, you are forced to prioritize. *You* must decide what truly matters. *That* is the real core of agency.
+
+In the infinite fantasy world of The Cloud, everything is urgent, so nothing is. In the economy of Reticulum, the cost of transmission forces you to weigh the value of your message. Do you really need to send that heart beat? Is that photo essential?
+
+When you strip away the noise, what remains is *signal*.
+
+This discipline creates a different kind of developer. It creates a craftsman who understands that the best code is the code you don't have to write. It creates a user who understands that the most powerful message is the one that is *understood*, not the one that is loudest. In the world of Reticulum, you are not a mere consumer of bandwidth; you are an architect of intent.
+
+
+## IV: Sovereignty Through Infrastructure
+**Be Your Own Network**
+
+We live in an era of digital tenancy. We lease our connectivity from ISPs. We rent our storage from cloud providers. We even borrow our identity from social media platforms. We are tenants in a house we did not build, governed by rules we did not write, subject to eviction at the whim of a landlord who has never met us.
+
+The Zen of Reticulum is the realization that you *can* own the house.
+
+### A Carrier-Grade Fallacy
+
+For decades, we have been gaslit into believing that networking is really not just hard, but impossible. It is presented as a dark art reserved for telcos and billionaires, requiring millions of dollars of fiber optics, climate-controlled data centers, and armies of engineers. We are told that building reliable infrastructure is "too complex" for the individual or small organization.
+
+This is a big, fat lie.
+
+Physics is simple. A radio wave needs a transmitter and a receiver. A packet needs a path. The "complexity" of the modern internet is largely bureaucratic - a mountain of billing systems, regulatory capture, and legacy cruft designed to keep the gatekeepers in power.
+
+Reticulum strips away the bureaucracy. It runs on hardware that costs the price of a dinner. It runs on spectrum that is free to use. It demonstrates that a robust, planetary-scale network does not require a Fortune 500 company. It requires only the will to deploy, and the distributed, uncoordinated efforts of many individuals.
+
+### Personal Infrastructure
+
+This is where the rubber meets the road. You can read about Reticulum, you can understand the theory, but the insights only arrive when you plug in a radio and run a Transport Node. Suddenly, you are no longer a consumer. You're an operator.
+
+This shift is subtle but profound. When you run your own infrastructure, the network ceases to be a service that is provided *to* you. It becomes a space that you *inhabit*. You become responsible for the flow of information. You gain an intimate understanding of the medium - the way the weather affects the radio waves, the way the topology changes, the way the packets dance through the ether.
+
+There is a quiet competence that comes from this. You stop asking "Is the internet down?" and start asking "Is *my* links up?" You stop waiting for a technician and start checking the logs. This is a form of strength. To understand the system that carries your words is to be free from the mystery that keeps you dependent.
+
+### The Ability To Disconnect
+
+Why go to the trouble? Why buy the radio, write the config, and leave the Pi running in the corner?
+
+Because the old, centralized network is fragile. And because most of us doesn't even really want to be there anymore.
+
+The internet we rely on today is a chain of single points of failure. Cut the undersea cable, and a continent goes dark. Shut down the power grid, and the cloud evaporates. Deprioritize the "wrong" traffic, and the flow of information is strangled.
+
+Sovereignty is the ability to survive the cut, whether or not that cut was an accident or on purpose.
+
+When you build your own infrastructure, you build a lifeline. Reticulum is designed to function over media that the traditional internet cannot touch - bare wires, battery-powered radios, ad-hoc WiFi meshes. When the grid fails, or the censors arrive, or the bill goes unpaid, your Reticulum network continues to hum.
+
+This is not about "dropping out" of society. It is about building a substrate on which an actual *Society* can function.
+
+**Consider:**
+
+- **The Old Way:** "My connection is slow. I should call my ISP and complain."
+- **The Zen Way:** "The path is noisy. I will adjust the antenna or find a better route."
+
+By taking ownership of the infrastructure, you take ownership of your voice. You stop shouting into someone else's megaphone and start building your own. The network is no longer something that happens to you; it is something you make happen.
+
+
+# V: Identity and Nomadism
+**A Fluid Self**
+
+In the old world, you are defined by your coordinates. If you are at `34.109.71.5`, you're *here*. If you unplug the cable and walk down the street, you vanish. Your digital self evaporates because it was tethered to the wall. You are a ghost in the endless machinations of gears, levers and transistors, bound to the hardware, and those that own it.
+
+This creates a subtle, constant anxiety. We are terrified of disconnecting because, in the architecture of the old web, disconnecting is a kind of death.
+
+The Zen of Reticulum offers a different way to be.
+
+### Portable Existence
+
+In Reticulum, your identity is not a location, or a username granted by a service. It is a cryptographic key - a complex, unique mathematical signature that exists independently of the physical world. You can carry it only in your mind, if you want to.
+
+Think of it less like a street address and more like a name. *A true name*.
+
+If you travel from Berlin to Tokyo, you do not change your name. You are still you. The people who know you can still recognize you. Reticulum applies this principle to the network layer. Your Destination Hash is **invariant**. It travels with you, stored securely on your device, *immutable as a stone*.
+
+This changes the relationship between you and the machine. You are not "logged into" the network via a specific gateway. You *are* the endpoint. The network does not connect to a place; *it converges on you*.
+
+### Roaming Nodes
+
+This freedom introduces a new concept of time and space: **Nomadism**.
+
+Because your identity is portable, your connectivity can be fluid. You can be sitting at a desk connected to a fiber backbone one moment, and walking through a field connected only to a long-range LoRa mesh the next. To the rest of the network, nothing has changed. Your friends do not need to update your contact info. The messages they send do not bounce back. The network senses the shift in the medium and reroutes the flow of data automatically.
+
+You are no longer a stationary node in a fixed grid. You are a wanderer in a fluid medium.
+
+The interfaces - whether it is WiFi, Ethernet, Packet Radio, or a physical wire - is merely the clothing your node wears. You change it to suit the environment. Underneath, you remain the same. This is the liberation of the protocol. It treats the physical medium as a transient circumstance, not a definition of self.
+
+**Consider:**
+
+- **The Old Way:** *"I lost connection. I have to reconnect to the VPN to tell them where I am now."*
+- **The Zen Way:** *"I moved. The network subtly bends to accomodate this new reality."*
+
+### Announcing Presence
+
+How does the network find a wanderer? It listens.
+
+In the IP world, we query directories. We ask a server, "Where is Mark?" The server checks its database and gives us a coordinate. This means that someone, somewhere, is keeping track of you. It assumes and *requires* surveillance.
+
+Reticulum replaces surveillance with **Announces**.
+
+Instead of asking a central authority where you are, you simply state your presence. You broadcast a cryptographic proof: "I am here, and I am who I say I am". This ripples out through the mesh. Your neighbors hear it, update their path tables, and pass it on.
+
+This is a quiet, organic process. It is the digital equivalent of lighting lanterns in the dark. You do not need to chase the light; you let the light find you. It respects your autonomy. You choose when to announce, how often to speak, and to whom. You also choose when to disappear - for but a moment or perpetually.
+
+### Anchor In The Flow
+
+There is a deep peace in this nomadism. It teaches you that stability does not come from standing still. Stability comes from *internal coherence*.
+
+By holding your own private key, you hold your own center of gravity. The world around you; the infrastructure, the topography and the availability of links can all shift chaotically. Storms can knock out towers. Cables can be cut. The internet can go down.
+
+But as long as you possess your key, you possess your identity. The entire infrastructure can be destroyed and rebuilt, and you are still you. Nothing lasts, yet nothing is lost.
+
+You become a sovereign entity moving through the noise, connected not by the rigidity of cables, but by the fluidity of recognition. The network becomes a place you inhabit, rather than a utility you subscribe to: You are at home in the ether.
+
+
+## VI: Ethics Of The Tool
+**Technology With Conscience**
+
+You have unlearned the center. You have accepted the physics of trust. You have embraced the economy of scarcity and the freedom of unbound nomadism. You are standing in a new space. Now, look at the tool in your hand.
+
+In the old world, we were taught that technology is neutral. We are told that "guns don't kill people, people do", or that a component is just a component, indifferent to what its combinatorial potential is. This is a convenient lie. It serves only to allow the builders to wash their hands of responsibility.
+
+But we know better now. We know that **architecture is politics**, and *politics is control*. The way you build a system determines how it will be used. If you build a system optimized for mass surveillance, you *will* get a panopticon. If you build a system optimized for centralized control, you *will* get a dictatorship. If you build a system optimized for extraction, you *will* get a parasite.
+
+The Zen of Reticulum asserts that a tool is never neutral.
+
+On the very contrary: A tool is intent, **crystallized**.
+
+### The Harm Principle
+
+Why does the Reticulum License forbid the software from being used in systems designed to harm humans? Is it not just a restriction on freedom?
+
+It is a restriction on *license*, yes, but it is an expansion of *freedom*.
+
+Building powerful tools without a moral compass is in no way virtuous or commendable, it is plain and simple irresponsibility.
+
+A tool that can easily be used to oppress is a real danger to the user. If you build a network that can be turned against you by a tyrant, you are not free. You are merely waiting for the leash to tighten. By encoding the "Harm Principle" into the legal DNA of the reference implementation, we are building a safeguard. We are stating, clearly and immutably, that *this tool* is for **life**, not for death.
+
+This aligns the software with the interests of humanity. It cements that the network cannot be conscripted into a kill-system, a weaponized drone controller, or a torture device without breaking the license and the law. It is a line drawn in the sand - not by a government or external authority, but by the creators of the tool itself.
+
+**Consider:**
+
+- **The Old Way:** *"It's just software. How people use it is not my problem."*
+- **The Zen Way:** *"This software is a habitat. I will not allow it to be used to build a cage."*
+
+It is *your* choice whether to align with this - we are not forcing this stance on anyone. If you choose to align with life over death, with creativity over destruction, we grant you an immensely powerful tool, to own and build with as you please. If you do not, we deny it.
+
+If you do not like this, we most assuredly do not need you here, and you are on your own.
+
+### Public Domain Protocol
+
+This leads to a vital distinction: The difference between the *idea* and the *implementation*.
+
+The protocol - the mathematical rules of how Reticulum works - is dedicated to the Public Domain. It belongs to humanity. **No one can own it**. Anyone can implement it, improve it, or adapt it. This is the core idea of free communication, which itself must be forever free.
+
+But the functional, deployed *reference implementation* - the Python code, the maintenance, the years of labor - has a conscience. This distinction is the engine of sustainability. It allows the protocol to be universal, while ensuring that the specific labor of the builders is not hijacked to undermine the foundational intent of the project itself. From this document, it should be very clear what this intent is.
+
+If you want to build a system with Reticulum that manipulates and damages users for profits or targets missiles, you can use the public domain protocol, and start from scratch. But you cannot take our work. You must do your own. This serves as a pillar of accountability. If you want to build a weapon, *you* go and forge the steel yourself, while the world observes. And when the blood is drawn - it is on **your** hands.
+
+### Preserving Human Agency
+
+We live in an era of predatory extraction. The open-source commons is being scraped, ingested, and regurgitated by machine learning algorithms, whose corporate owners seek to replace the very humans who built those commons. Our code, our words, and our creativity is being used to train systems that are specifically designed to make us obsolete, without offering anything else in return than serfdom and leashes.
+
+Reticulum stands against this.
+
+The license protects the software from being used to feed the beast. It draws a hard line: This tool is for *people*. It is for human-to-human connection. It is not a dataset to be strip-mined for the purpose of building a synthetic overlord, puppeteered by a miniscule conglomerate of controllers.
+
+This is a radical act of preservation. By protecting the code from AI appropriation, we are protecting space for human agency. We are ensuring that there remains a digital realm where the actors are flesh, blood and soul, where decisions are made by minds, not overlords hiding behind models.
+
+When you use Reticulum, you are using a tool that respects you. It does not see you as a product to be tracked. It does not see your data as fuel for an algorithm. It sees you as a sovereign, equal peer.
+
+This changes the foundational premise of using the technology. It restores dignity to the interaction. You are not the user of a service; you are a participant in a mutual covenant. The tool aligns with your autonomy, rather than eroding it.
+
+In this way, ethics is not a restriction, but a foundation. It is the foundation that helps ensure the network will still belong to you tomorrow.
+
+
+## VII: Design Patterns For Post-IP Systems
+**Practical Philosophy for Developers**
+
+The philosophy is useless if it cannot be hammered into code. The metaphors we have explored - nomadism, scarcity, trust - are not just poetry, but real-world engineering constraints. When you sit down to write software for Reticulum, these concepts must shape the very structure of your application.
+
+We are now moving from the *why* to the *how*. This is where the abstract becomes concrete, and where you will see the true depth of the patterns we have been weaving.
+
+### Store & Forward
+
+The web has trained us to be impatient. We write synchronous code. We fire a request and we wait, blocking the UI, holding our breath. If the response doesn't come in 250 milliseconds, we show a spinner. If it doesn't come in five seconds, we show an error. We treat network connectivity as a binary state: either we are "online" or we are "broken".
+
+This is brittle. It is a rejection of reality.
+
+In Reticulum, connectivity is a spectrum, and presence is asynchronous. If at all applicable to your intent, you must design your applications to embrace **Store & Forward**.
+
+Instead of demanding an immediate answer, your application should act as a patient participant. You create a message for someone or something in the mesh. The network holds it. It carries it from node to node, perhaps over hours or days, waiting for the recipient to appear. When they finally surface, the message is delivered. This requires a shift from "request/response" to "event/handler". How exactly you do this is a challenge for you to solve intelligently within your problem domain, but Reticulum-based systems already exist that does this extremely well, and you can use them for inspiration.
+
+**Consider:**
+
+- **The Old Way:** `Connect() -> Send() -> Wait() -> Crash if timeout.`
+- **The Zen Way:** `Send() -> Continue living. -> Receive() when it arrives.`
+
+This changes the user experience profoundly. It removes the anxiety of the loading bar. It creates a sense of continuity. The user is not "waiting for the network"; they are interacting with a persistent log of communication that lives in the network itself.
+
+### Naming Is Power
+
+In the IP world, we are slaves to the Domain Name System. We rely on a hierarchy of registrars to map human-readable names to machine-readable addresses. This hierarchy is a choke point. If the registrar revokes your domain, or if the DNS server goes down, you vanish.
+
+Reticulum dissolves this hierarchy with **Hash-based Identity**.
+
+In this design pattern, a name is not a string you look up; it is a cryptographic destination you verify. When you design for Reticulum, you stop asking the user for a URL and start asking for a Destination or Identity Hash.
+
+This feels strange at first. A hash like `<83b7328926fed0d2e6a10a7671f9e237>` looks alien compared to `myfriend.com`. But that alienness is the armor. It **cannot** be spoofed. It **cannot** be censored by a registrar. It is **absolute**.
+
+Designing for this means shifting your UI metaphors. You are no longer browsing a web of pages; you are managing a ledger of keys. You are building an "Address Book" that is actually a keyring. The names are given by the user, and the power stays with them. That hashes look complex is directly analogous to the strengths of the bonds formed by their use. It forces the user to engage in a moment of verification, an out-of-band handshake, which restores the human element of trust that SSL certificates stripped away.
+
+### The Interface Is The Medium
+
+One of the most liberating patterns in Reticulum is **Transport Agnosticism**.
+
+In traditional networking, your code is often littered with transport logic. "Am I on WiFi? Check bandwidth. Am I on Cellular? Check data plan. Am I on Ethernet?". You are constantly micromanaging the pipe.
+
+In Reticulum, you write to the API, and the API writes to the medium. You send a packet to a Destination. You do not care if that packet travels over a TCP tunnel, a LoRa radio wave, or a serial wire interface. That is the stack's concern.
+
+This allows you to write **Universal Applications**.
+Imagine a messaging app. You write it once. It works on a laptop connected to fiber. It works on a phone in the city using WiFi. And, without a single line of code changed, it works on a device in the wilderness, talking only to other devices via radio.
+
+The pattern is simple: **Never code to the hardware. Code to the intent.**
+
+**Consider:**
+
+- **The Old Way:** `socket.connect(ip, port)`
+- **The Zen Way:** `RNS.Packet(destination, data).send()`
+
+By abstracting the medium, you make your software immortal to changes in infrastructure. The user might switch from a 4G hotspot to a HF modem tomorrow. Your software doesn't need to know. It simply continues the conversation.
+
+### Emergent Patterns
+
+When you combine these patterns - *Store & Forward*, *Hash-based Identity*, and *Transport Agnosticism* - you create software that feels fundamentally different.
+
+It feels *grounded*. It doesn't flicker when the signal drops. It doesn't panic when the server is down. It has weight. It has persistence. It has *relevance*.
+
+You are no longer building a "client" that begs a "server" for attention. You are building an autonomous agent that exists within the mesh. It speaks when it needs to, listens when it can, and carries its identity with it wherever it goes.
+
+This is the culmination of the Zen. The code is not just a set of instructions: It is a behavioral envelope. It is a way of *being* in the network.
+
+
+## VIII: Fabric Of The Independent
+
+We have stripped away the illusions. We have seen that the center is empty, that trust *must* be hard, that resources are finite, and that we must own our infrastructure. We have seen that tools have ethics and that our identity can move fluidly.
+
+This is a reclaiming of the commons. For too long, we have allowed the most vital substrate of human society - *our ability to speak to one another* - to be colonized by entities that do not share our interests. We have allowed the architecture of our communication to be designed by accountants rather than architects.
+
+We are taking it back. Not by petitioning the masters, but by building the new world within, over, under and around the shell of the old.
+
+### The Work Is Finished
+
+The heavy lifting is done.
+
+The protocol is in the public domain, a gift to humanity that can never be taken away. The software is written, tested, and running on devices scattered across the globe. The manual lies open before you. The source code for the reference implementation is now distributed on hundreds of thousands of devices across the planet. No one can delete or destroy it. The hardware is accessible and abundant.
+
+It was a hard road to get here, but we got here. Now, there is no roadmap committee waiting for approval. There is no venture capital dictating the user experience. There is no CEO to sign off on the next feature release.
+
+There is only you.
+
+The barrier to entry is no longer complexity: It is the mere habit of dependency. You were conditioned to wait. Wait for the app update. Wait for the ISP to fix the line. Wait for the platform to allow the post. Wait for the government to change the policies. Wait for the likes. Wait for the revolution to be televised.
+
+The revolution never was televised.
+
+It is packetized.
+
+### Open Sky
+
+The future of this technology is a construction project.
+
+It looks like a single node on a windowsill, listening to the static. It looks like a message sent to a neighbor, bypassing the noise of the commercial web. It looks like a community mesh that grows, link by link, hop by hop, carried by hands that care more about connection than profit.
+
+You have the blueprints. You have the tools. You have the philosophy. The noise of the old world has fallen away, leaving you with the quiet clarity of the open spectrum.
+
+*Mark, early 2026*

docs/manual/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file records the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 42d644626d484631388dca045ac26048
+config: ea8ffef16f1cae34d273c7bce7123529
 tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/manual/_sources/gettingstartedfast.rst.txt

@@ -8,7 +8,7 @@ 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:
 
@@ -25,7 +25,7 @@ and install them offline using ``pip``:
 
 .. code:: shell
 
-   pip install ./rns-1.0.2-py3-none-any.whl
+   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
@@ -66,106 +66,10 @@ compiled packages available.
 Try Using a Reticulum-based Program
 =============================================
 
-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,
+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.
 
-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 over fast
-links, such as local WiFi, wired Ethernet, the Internet, or any combination.
-
-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.
-
-Remote Shell
-^^^^^^^^^^^^
-
-The `rnsh <https://github.com/acehoss/rnsh>`_ program lets you establish fully interactive
-remote shell sessions over Reticulum. It also allows you to pipe any program to or from a
-remote system, and is similar to how ``ssh`` works. The ``rnsh`` is very efficient, and
-can facilitate fully interactive shell sessions, even over extremely low-bandwidth links,
-such as LoRa or packet radio.
-
-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.
-
-.. image:: screenshots/nomadnet_3.png
-    :target: _images/nomadnet_3.png
-
-`Nomad Network <https://github.com/markqvist/nomadnet>`_ is a user-facing client
-for the messaging and information-sharing protocol
-`LXMF <https://github.com/markqvist/lxmf>`_, another project built with Reticulum.
-
-You can install Nomad Network via pip:
-
-.. code::
-
-   # Install ...
-   pip install nomadnet
-
-   # ... and run
-   nomadnet
-
-.. 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. In some cases, you may even need to
-   manually add the ``pip`` install path to your ``PATH`` environment variable.
-
-Sideband
-^^^^^^^^
-
-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, macOS and Windows.
-
-.. only:: html
-
-  .. image:: screenshots/sideband_devices.webp
-      :align: center
-      :target: _images/sideband_devices.webp
-
-.. only:: latex
-
-  .. image:: screenshots/sideband_devices.png
-      :align: center
-      :target: _images/sideband_devices.png
-
-Sideband allows you to communicate with other people or LXMF-compatible
-systems over Reticulum networks using LoRa, Packet Radio, WiFi, I2P, Encrypted QR
-Paper Messages, or anything else Reticulum supports. It also interoperates with
-the Nomad Network program.
-
-MeshChat
-^^^^^^^^
-
-The `Reticulum MeshChat <https://github.com/liamcottle/reticulum-meshchat>`_ application
-is a user-friendly LXMF client for Linux, macOS and Windows, that also includes a Nomad Network
-page browser and other interesting functionality.
-
-.. only:: html
-
-  .. image:: screenshots/meshchat_1.webp
-      :align: center
-      :target: _images/meshchat_1.webp
-
-.. only:: latex
-
-  .. image:: screenshots/meshchat_1.png
-      :align: center
-      :target: _images/meshchat_1.png
-
-Reticulum MeshChat is of course also compatible with Sideband and Nomad Network, or
-any other LXMF client.
 
 Using the Included Utilities
 =============================================
@@ -214,7 +118,160 @@ network just using the default (:ref:`AutoInterface<interfaces-auto>`) configura
 
 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.
+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:
+
+Bootstrapping Connectivity
+==========================
+
+Reticulum is not a service you subscribe to, nor is it a single global network you "join". It is a *networking stack*; a toolkit for building communications systems that align with your specific values, requirements, and operational environment. The way you choose to connect to other Reticulum peers is entirely your own choice.
+
+One of the most powerful aspects of Reticulum is that it provides a multitude of tools to establish, maintain, and optimize connectivity. You can use these tools in isolation or combine them in complex configurations to achieve a vast array of goals.
+
+Whether your aim is to create a completely private, air-gapped network for your family; to build a resilient community mesh that survives infrastructure collapse; to connect far and wide to as many nodes as possible; or simply to maintain a reliable, encrypted link to a specific organization you care about, Reticulum provides the mechanisms to make it happen.
+
+There is no "right" or "wrong" way to build a Reticulum network, and you don't need to be a network engineer just to get started. If the information flows in the way you intend, and your privacy and security requirements are met, your configuration is a success. Reticulum is designed to make the most challenging and difficult scenarios attainable, even when other networking technologies fail.
+
+
+Finding Your Way
+^^^^^^^^^^^^^^^^
+
+When you first start using Reticulum, you need a way to obtain connectivity with the peers you want to communicate with - the process of *bootstrapping connectivity*.
+
+.. important::
+  
+  A common mistake in modern networking is the reliance on a few centralized, hard-coded entrypoints. If every user simply connects to the same list of public IP addresses found on a website, the network becomes brittle, centralized, and ultimately fails to deliver on the promise of decentralization and resilience. You have a responsibility here.
+
+Reticulum encourages the approach of *organic growth*. Instead of relying on permanent static connections to distant servers, you can use temporary bootstrap connections to continously *discover* more relevant or local infrastructure. Once discovered, your system can automatically form stronger, more direct links to these peers, and discard the temporary bootstrap links. This results in a web of connections that are geographically relevant, resilient and efficient.
+
+It *is* possible to simply add a few public entrypoints to the ``[interfaces]`` section of your Reticulum configuration and be connected, but a better option is to enable :ref:`interface discovery<using-interface_discovery>` and either manually select relevant, local interfaces, or enable discovered interface auto-connection.
+
+A relevant option in this context is the :ref:`bootstrap only<interfaces-options>` interface option. This is an automated tool for better distributing connectivity. By enabling interface discovery and auto-connection, and marking an interface as ``bootstrap_only``, you tell Reticulum to use that interface primarliy to find connectivity options, and then disconnect it once sufficient entrypoints have been discovered. This helps create a network topology that favors locality and resilience over the simple centralization caused by using only a few static entrypoints.
+
+Good places to find interface definitions for bootstrapping connectivity are websites like
+`directory.rns.recipes <https://directory.rns.recipes/>`_ and `rmap.world <https://rmap.world/>`_.
+
+
+Build Personal Infrastructure
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You do not need a datacenter to be a meaningful part of the Reticulum ecosystem. In fact, the most important nodes in the network are often the smallest ones.
+
+We strongly encourage everyone, even home users, to think in terms of building **personal infrastructure**. Don't connect every phone, tablet, and computer in your house directly to a public internet gateway. Instead, repurpose an old computer, a Raspberry Pi, or a supported router to act as your own, personal **Transport Node**:
+
+*   Your local Transport Node sits in your home, connected to your WiFi and perhaps a radio interface (like an RNode).
+*   You configure this node with a ``bootstrap_only`` interface (perhaps a TCP tunnel to a wider network) and enable interface discovery.
+*   While you sleep, work, or cook, your node listens to the network. It discovers other local community members, validates their Network Identities, and automatically establishes direct links.
+*   Your personal devices now connect to your *local* node, which is integrated into a living, breathing local mesh. Your traffic flows through local paths provided by other real people in the community rather than bouncing off a distant server.
+
+**Don't wait for others to build the networks you want to see**. Every network is important, perhaps even most so those that support individual families and persons. Once enough of this personal, local infrastructure exist, connecting them directly to each other, without traversing the public Internet, becomes inevitable.
+
+
+Mixing Strategies
+^^^^^^^^^^^^^^^^^
+
+There is no requirement to commit to a single strategy. The most robust setups often mix static, dynamic, and discovered interfaces.
+
+*   **Static Interfaces:** You maintain a permanent interface to a trusted friend or organization using a static configuration.
+*   **Bootstrap Links:** You connect a ``bootstrap_only`` interface to a public gateway on the Internet to scan for new connectable peers or to regain connectivity if your other interfaces fail.
+*   **Local Wide-Area Connectivity:** You run a ``RNodeInterface`` on a shared frequency, giving you completely self-sovereign and private wide-area access to both your own network and other Reticulum peers globally, without any "service providers" being able to control or monitor how you interact with people.
+
+By combining these methods, you create a system that is secure against single points of failure, adaptable to changing network conditions, and better integrated into your physical and social reality.
+
+
+Network Health & Responsibility
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+As you participate in the wider networks you discover and build, you will inevitably encounter peers that are misconfigured, malicious, or simply broken. To protect your resources and those of your local peers, you can utilize the :ref:`Blackhole Management<using-blackhole_management>` system.
+
+Whether you manually block a spamming identity or subscribe to a blackhole list maintained by a trusted Network Identity, these tools help ensure that *your* transport capacity is used for what *you* consider legitimate communication. This keeps your local segment efficient and contributes to the health of the wider network.
+
+
+Contributing to the Global Ret
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you have the means to host a stable node with a public IP address, consider becoming a :ref:`Public Entrypoint<hosting-entrypoints>`. By :ref:`publishing your interface as discoverable<interfaces-discoverable>`, you provide a potential connection point for others, helping the network grow and reach new areas.
+
+For guidelines on how to properly configure a public entrypoint, refer to the :ref:`Hosting Public Entrypoints<hosting-entrypoints>` section.
+
+Connect to the Distributed Backbone
+===================================
+
+A global, distributed backbone of Reticulum Transport Nodes is being run by volunteers from around the world. This network constitutes a heterogenous collection of both public and private nodes that form an uncoordinated, voluntary inter-networking backbone that currently provides global transport and internetworking capabilities for Reticulum.
+
+As a good starting point, you can find interface definitions for connecting your own networks to this backbone on websites such as `directory.rns.recipes <https://directory.rns.recipes/>`_ and `rmap.world <https://rmap.world/>`_.
+
+.. tip::
+  Don't rely on just a single connection to the distributed backbone for everyday use. It is much better to have several redundant connections configured, and enable the interface discovery options, so your nodes can continously discover peering opportunities as the network evolves. Refer to the :ref:`Bootstrapping Connectivity<bootstrapping-connectivity>` section to understand the options.
+
+
+
+.. _hosting-entrypoints:
+
+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>`.
+
+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.
+
+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
+
+  # This example demonstrates a backbone interface
+  # configured for acting as a gateway for users to
+  # connect to either a public or private network
+
+  [[Public Gateway]]
+    type = BackboneInterface
+    enabled = yes
+    mode = gateway
+    listen_on = 0.0.0.0
+    port = 4242
+
+    # On publicly available interfaces, it can be
+    # a good idea to configure sensible announce
+    # rate targets.
+    announce_rate_target = 3600
+    announce_rate_penalty = 3600
+    announce_rate_grace = 12
+
+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
+
+  # A private entry-point requiring a pre-shared
+  # network name and passphrase to connect to.
+
+  [[Private Gateway]]
+    type = BackboneInterface
+    enabled = yes
+    mode = gateway
+    listen_on = 0.0.0.0
+    port = 4242
+    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.
+
 
 Connecting Reticulum Instances Over the Internet
 ================================================
@@ -227,7 +284,7 @@ method is generally faster, lower latency, and more energy efficient than using
 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 many hundreds of connections simultaneously with low memory, processing
+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
@@ -254,101 +311,8 @@ In general it is recommended to use an I2P node if you want to host a publicly a
 instance, while preserving anonymity. If you care more about performance, and a slightly
 easier setup, use TCP.
 
-
-Connect to the Public Testnet
-===========================================
-
-An experimental public testnet has been made accessible by volunteers in the community. You
-can find interface definitions for adding to your ``.reticulum/config`` file on the
-`Reticulum Website <https://reticulum.network/connect.html>`_ or the
-`Community Wiki <https://github.com/markqvist/Reticulum/wiki/Community-Node-List>`_
-
-You can connect your devices or instances to one or more of these to gain access to any
-Reticulum networks they are physically connected to. Simply add one or more interface
-snippets to your config file in the ``[interface]`` section, like in the example below:
-
-.. code:: ini
-
-  # TCP/IP interface to the BetweenTheBorders Hub (community-provided)
-  [[RNS Testnet BetweenTheBorders]]
-    type = TCPClientInterface
-    enabled = yes
-    target_host = reticulum.betweentheborders.com
-    target_port = 4242
-
-
-.. tip::
-  Ideally, set up a Reticulum Transport Node that your own devices can reach locally, and then
-  connect that transport node to a couple of public entrypoints. This will provide efficient
-  connections and redundancy in case any of them go down.
-
-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.
-Expect weird things to happen on this network, as people experiment and try out things.
-
-.. warning::
-  It probably goes without saying, but *don't use the testnet entry-points as 
-  hardcoded or default interfaces in any applications you ship to users*. When
-  shipping applications, the best practice is to provide your own default
-  connectivity solutions, if needed and applicable, or in most cases, simply
-  leave it up to the user which networks to connect to, and how.
-
-
-Hosting Public Entrypoints
-===========================================
-
-If you want to host a public (or private) entry-point to a Reticulum network over the
-Internet, this section offers some helpful pointers. 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.
-
-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
-
-  # This example demonstrates a backbone interface
-  # configured for acting as a gateway for users to
-  # connect to either a public or private network
-
-  [[Public Gateway]]
-    type = BackboneInterface
-    enabled = yes
-    mode = gateway
-    listen_on = 0.0.0.0
-    port = 4242
-
-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
-
-  # A private entry-point requiring a pre-shared
-  # network name and passphrase to connect to.
-
-  [[Private Gateway]]
-    type = BackboneInterface
-    enabled = yes
-    mode = gateway
-    listen_on = 0.0.0.0
-    port = 4242
-    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.
-
 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
@@ -360,24 +324,22 @@ 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:
+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>`. 
 
-* `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-supported-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/>`_
+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>`, 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.
+: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
@@ -404,54 +366,10 @@ 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.
+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.
 
 
-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:: shell
-
-    # Install dependencies
-    pip install cryptography pyserial
-
-    # 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
-    python 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:
-    nano ~/.reticulum/config
-
-    # ... and launch the example again.
-    python 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.
-    python 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.
-    python Examples/Echo.py 174a64852a75682259ad8b921b8bf416
-
-    # Have a look at another example
-    python Examples/Filetransfer.py -h
-
-When you have experimented with the basic examples, it's time to go read the
-: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.
-
 .. _install-guides:
 
 Platform-Specific Install Notes

docs/manual/_sources/git.rst.txt

@@ -0,0 +1,573 @@
+.. _git-main:
+
+******************
+Git Over Reticulum
+******************
+
+A set of utilities for distributed collaborative software development and publishing is included in RNS.
+
+The system consists of two parts: The ``rngit`` node that hosts repositories, and the ``git-remote-rns`` helper that enables Git to communicate with rngit nodes. As soon as you have RNS installed on your system, you can transparently use Git with Reticulum-hosted repositories just like any other type of remote. Git over Reticulum uses URLs in the following format: ``rns://DESTINATION_HASH/group/repo``.
+
+If you set a branch to track a Reticulum remote as the default upstream, you can simply use ``git`` as you normally would; all commands work transparently and as expected.
+
+.. warning::
+   **The rngit program is a new addition to RNS!** This functionality was introduced in RNS 1.2.0. While great care has been taken to design a secure, but highly configurable and flexible permission system for allowing many users to interact with many different repositories on a single node, ``rngit`` has not been tested extensively in the wild! Be careful when hosting repositories, especially if they are public or semi-public.
+
+The rngit Utility
+=================
+
+The ``rngit`` utility provides full Git repository hosting and interaction over Reticulum. It allows you to host and manage Git repositories and releases on Reticulum nodes, and to interact with remote repositories using standard Git commands through the ``rns://`` URL scheme.
+
+**Usage Examples**
+
+Run ``rngit`` to start a repository node:
+
+.. code:: text
+
+  $ rngit
+
+  [Notice] Starting Reticulum Git Node...
+  [Notice] Reticulum Git Node listening on <0d7334d411d00120cbad24edf355fdd2>
+
+On the first run, ``rngit`` will create a default configuration file. You will then need to edit this, to point to your repository locations, configure access permissions, and perform any other necessary configuration.
+
+View your identity and destination hashes:
+
+.. code:: text
+
+  $ rngit --print-identity
+
+  Git Peer Identity         : <959e10e5efc1bd9d97a4083babe51dea>
+  Repository Node Identity  : <153cb870b4665b8c1c348896292b0bad>
+  Repositories Destination  : <0d7334d411d00120cbad24edf355fdd2>
+
+If the page node is enabled, the output will also include the Nomad Network destination hash.
+
+You can run ``rngit`` in service mode with logging to file:
+
+.. code:: text
+
+  $ rngit -s
+
+Clone a repository from a remote ``rngit`` node:
+
+.. code:: text
+
+  $ git clone rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo
+
+Add a Reticulum remote to an existing repository:
+
+.. code:: text
+
+  $ git remote add some_remote rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo
+
+Push changes to the Reticulum remote:
+
+.. code:: text
+
+  $ git push some_remote master
+
+Get changes from a remote repository:
+
+.. code:: text
+
+  $ git pull rns_remote master
+
+**All Command-Line Options (rngit)**
+
+.. code:: text
+
+  usage: rngit.py [-h] [--config CONFIG] [--rnsconfig RNSCONFIG] [-s] [-i] [-v]
+                  [-q] [--version]
+
+  Reticulum Git Repository Node
+
+  options:
+    -h, --help            show this help message and exit
+    --config CONFIG       path to alternative config directory
+    --rnsconfig RNSCONFIG
+                          path to alternative Reticulum config directory
+    -p, --print-identity  print identity and destination info and exit
+    -s, --service         rngit is running as a service and should log to file
+    -i, --interactive     drop into interactive shell after initialisation
+    -v, --verbose         increase verbosity
+    -q, --quiet           decrease verbosity
+    --version             show program's version number and exit
+
+**All Command-Line Options (git-remote-rns)**
+
+The ``git-remote-rns`` helper is automatically invoked by Git when interacting with ``rns://`` URLs. It is not typically run directly by users, but accepts the following environment variables for configuration:
+
+- ``RNGIT_CONFIG`` - Path to alternative client configuration directory
+- ``RNS_CONFIG`` - Path to alternative Reticulum configuration directory
+
+The client configuration file is located at ``~/.rngit/client_config`` and allows adjusting parameters such as the reference batch size for transfers.
+
+
+Repository Structure
+====================
+
+The ``rngit`` node organizes repositories into groups. Each group is a directory containing bare Git repositories. The repository path format is ``group_name/repo_name``. For example, a repository at ``/var/git/public/myrepo`` would be accessible as ``public/myrepo`` via the URL ``rns://DESTINATION_HASH/public/myrepo``.
+
+**Configuration**
+
+The ``rngit`` node configuration file is located at ``~/.rngit/config`` (or ``/etc/rngit/config`` for system-wide installations). The default configuration includes:
+
+- Repository group paths defining where to find bare repositories
+- Access permissions for groups and individual repositories
+- Announce intervals for network visibility
+- Optional statistics recording for repository activity
+
+Access permissions can be configured at the group level in the config file, or per-repository using ``.allowed`` files. Permissions use the format ``permission:target`` where permission is ``r`` (read), ``w`` (write), ``rw`` (read/write), ``c`` (create) or ``s`` (stats) and target is ``all``, ``none``, or a specific identity hash.
+
+The ``s`` (stats) permission allows viewing repository activity statistics, including views, fetches and pushes over time. To enable statistics recording, set ``record_stats = yes`` in the ``[rngit]`` section of the configuration file. You can also exclude specific identities from statistics by adding their hashes to ``stats_ignore_identities``.
+
+Repository-specific ``.allowed`` files can be static text files or executable scripts that output permission rules to stdout. A ``group.allowed`` file in a repository group directory applies to all repositories within that group.
+
+Serving Pages Over Nomad Network
+================================
+
+In addition to providing Git repository access via the Git remote helper protocol, ``rngit`` can also run a `Nomad Network <https://github.com/markqvist/nomadnet>`_ compatible page node. This allows users to browse repository information, view file contents, inspect commit history and access repository statistics through any Nomad Network client.
+
+When enabled, the page node provides a complete interface to your repositories, with automatic Markdown to Micron conversion, syntax-highlighted code browsing, and detailed commit, diff and statistics views.
+
+**Enabling the Git Page Node**
+
+To enable the page node, add the following to your ``~/.rngit/config`` file:
+
+.. code:: text
+
+  [pages]
+  serve_nomadnet = yes
+
+When the page node is enabled, ``rngit`` will listen on a Nomad Network node destination in addition to the Git repository destination. You can view the destination hash by running:
+
+.. code:: text
+
+  $ rngit --print-identity
+
+  Git Peer Identity         : <959e10e5efc1bd9d97a4083babe51dea>
+  Repository Node Identity  : <153cb870b4665b8c1c348896292b0bad>
+  Repositories Destination  : <0d7334d411d00120cbad24edf355fdd2>
+  Nomad Network Destination : <50824b711717f97c2fb1166ceddd5ea9>
+
+**Accessing Repository Pages**
+
+Once the page node is running, you can access it from any Nomad Network client by connecting to the Nomad Network destination. The page node provides the following views:
+
+- **Front Page** - Lists all repository groups accessible to your identity
+- **Group Page** - Shows all repositories within a group
+- **Repository Page** - Displays repository overview, description and README
+- **Releases** - List of releases for the repository, with information and downloads
+- **File Browser** - Browse directory trees and view and download file contents
+- **Commits View** - View commit history with pagination
+- **Commit Details** - Detailed commit information with file changes and diffs
+- **Refs View** - List branches and tags
+- **Statistics** - Activity charts showing views, fetches and pushes over time
+
+All pages respect the same permission system used for Git access. If an identity does not have read access to a repository, they will not be able to view its pages.
+
+Formatting & Syntax Highlighting
+================================
+
+If the ``pygments`` Python module is installed on your system, the page node will automatically apply syntax highlighting to code files. The highlighting supports a wide range of programming languages and uses a color theme optimized for terminal display.
+
+To enable syntax highlighting, install pygments:
+
+.. code:: text
+
+  pip install pygments
+
+**Markdown & Micron Support**
+
+README files and other Markdown documents are automatically converted to Micron markup for display in Nomad Network clients. You can also write your README files directly in Micron, in which case they will display and render as such in any Nomad Network client. The file browser also supports viewing both rendered and raw Markdown and Micron documents.
+
+Code blocks in Markdown can include language hints for syntax highlighting:
+
+.. code:: text
+
+  ```python
+  def hello_world():
+      print("Hello, Reticulum!")
+  ```
+
+Customizing Templates
+=====================
+
+The page node uses a template system that allows complete customization of the generated pages. Templates are stored in the ``~/.rngit/templates/`` directory as Micron files.
+
+The following template files are supported:
+
+- ``base.mu`` - Base template wrapping all pages
+- ``front.mu`` - Front page listing all groups
+- ``group.mu`` - Group page listing repositories
+- ``repo.mu`` - Repository overview page
+- ``releases.mu`` - Release list page
+- ``release.mu`` - Release details page
+- ``tree.mu`` - File browser pages
+- ``blob.mu`` - File content display
+- ``commits.mu`` - Commit history listing
+- ``commit.mu`` - Individual commit detail page
+- ``refs.mu`` - Branches and tags listing
+- ``stats.mu`` - Statistics page
+
+Templates can include the following variables:
+
+- ``{PAGE_CONTENT}`` - The main content of the page (required)
+- ``{NODE_NAME}`` - The configured node name
+- ``{NAVIGATION}`` - Breadcrumb navigation links
+- ``{VERSION}`` - The rngit version number
+- ``{GEN_TIME}`` - Page generation time
+
+**Dynamic Templates**
+
+Templates can be made executable to generate dynamic content. If a template file has the executable bit set, it will be executed and its stdout used as the template content.
+
+**Icon Sets**
+
+By default, the page node uses Nerd Font icons. If you prefer simpler icons or your terminal does not support Nerd Fonts, you can enable Unicode icons instead:
+
+.. code:: text
+
+  [pages]
+  serve_nomadnet = yes
+  unicode_icons = yes
+
+**Repository Statistics**
+
+When statistics recording is enabled (see the ``record_stats`` configuration option), the page node can display activity charts for each repository. The statistics page shows:
+
+- Total and peak views, fetches and pushes
+- Daily activity charts over a 90-day period
+- Combined activity visualization
+
+To view statistics, a user must have the ``s`` (stats) permission for the repository. See the Access Configuration section for details on setting permissions.
+
+**Repository Thanks**
+
+The page node includes a "Thanks" feature that allows users to express appreciation for a repository. On each repository page, a "Thanks" link is displayed showing the current thanks count. Clicking this link registers a thank you for the repository.
+
+**Configuration Example**
+
+A complete page node configuration might look like this:
+
+.. code:: text
+
+  [rngit]
+  node_name = My Git Node
+  announce_interval = 360
+  record_stats = yes
+
+  [repositories]
+  public = /var/git/public
+  internal = /var/git/internal
+
+  [access]
+  public = r:all
+  internal = rw:9710b86ba12c42d1d8f30f74fe509286
+
+  [pages]
+  serve_nomadnet = yes
+  unicode_icons = no
+
+
+Release Management
+==================
+
+In addition to hosting Git repositories, ``rngit`` provides a complete release management system. This allows you to publish versioned releases with associated artifacts, release notes and metadata. Releases are managed through the ``rngit release`` subcommand, and are also viewable through the Nomad Network page interface.
+
+**The Release Workflow**
+
+Creating a release involves specifying a Git tag and a directory containing build artifacts or other files to distribute. The ``rngit`` client will open your configured ``$EDITOR`` to compose release notes, then upload all artifacts to the remote repository node.
+
+To create a release, specify the tag name and path to artifacts:
+
+.. code:: text
+
+  $ rngit release rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo create v1.2.0:./dist
+
+This will:
+
+1. Verify that the tag ``v1.2.0`` exists in the repository
+2. Open your editor to write release notes
+3. Upload all files from the ``./dist`` directory
+4. Publish the release
+
+If no ``$EDITOR`` environment variable is set, ``rngit`` will try to use ``nano``, ``vim`` or ``vi``. The editor will show a template with instructions. Lines starting with ``#`` will be ignored, and if the remaining content is empty after stripping comments, the release creation will be cancelled.
+
+**Release Storage & Structure**
+
+Releases are stored on the node in a directory named ``repo_name.releases`` next to the bare repository. Each release is a subdirectory containing:
+
+- ``META`` - Release metadata in ConfigObj format
+- ``RELEASE.md`` or ``RELEASE.mu`` - Release notes
+- ``artifacts/`` - All uploaded files
+- ``THANKS`` - Appreciation count from users
+
+**Listing Releases**
+
+To view all releases for a repository:
+
+.. code:: text
+
+  $ rngit release rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo list
+
+  Tag          Status     Created              Objs  Notes
+  ------------------------------------------------------------------
+  v1.2.0       published  2025-01-15 14:32     3     Another release
+  v1.1.0       published  2024-12-03 09:15     2     Bug fix release
+  v1.0.0       published  2024-10-20 16:45     2     Initial release
+
+**Viewing Release Details**
+
+To see full information about a specific release:
+
+.. code:: text
+
+  $ rngit release rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo view v1.2.0
+
+  Release : 0.9.2        
+  Status  : published
+  Created : 2026-05-04 23:53:09
+  Thanks  : 5
+
+  Release Notes
+  =============
+
+  Version 1.2.0 release notes...
+
+  Artifacts (4)
+  =============
+    - myapp-1.2.0.tar.gz (1.5 MB)
+    - myapp-1.2.0.zip (1.6 MB)
+    - checksums.txt (256 B)
+
+**Deleting Releases**
+
+To remove a release:
+
+.. code:: text
+
+  $ rngit release rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo delete v1.2.0
+
+  Are you sure you want to delete release 'v1.2.0'? [y/N]: y
+  Release v1.2.0 deleted
+
+**Requirements & Validation**
+
+- The specified tag must exist in the remote repository
+- You must have ``release`` permission for the repository
+- The target artifacts directory must exist and contain at least one file
+- Release notes cannot be empty
+
+**Permissions**
+
+Release management requires the ``release`` permission, configured the same way as other repository permissions. In the config file or ``.allowed`` files, use ``rel:target`` to grant release management rights:
+
+.. code:: text
+
+  # In .allowed file or config
+  rel:all          # Allow everyone
+  rel:9710b86...   # Allow specific identity
+  rel:none         # Deny everyone
+
+**Nomad Network Interface**
+
+When the Nomad Network page node is enabled, releases are displayed on a dedicated releases page for each repository. Each release is listed with its tag, creation date, artifact count and a preview of the release notes. Clicking a release shows the full details including formatted release notes and a listing of all artifacts with their sizes.
+
+Only releases with ``published`` status are visible through the Nomad Network interface. Draft releases (if supported in future implementations) would only be visible through the command-line interface.
+
+**All Command-Line Options (rngit release)**
+
+.. code:: text
+
+  usage: rngit release [-h] [--config CONFIG] [--rnsconfig RNSCONFIG]
+                       [-i PATH] [-v] [-q] [--version]
+                       [repository] [operation] [target]
+
+  Reticulum Git Release Manager
+
+  positional arguments:
+    repository            URL of remote repository
+    operation             list, view, create or delete
+    target                tag and path to release artifacts directory
+
+  options:
+    -h, --help            show this help message and exit
+    --config CONFIG       path to alternative config directory
+    --rnsconfig RNSCONFIG
+                          path to alternative Reticulum config directory
+    -i, --identity PATH   path to release identity
+    -v, --verbose
+    -q, --quiet
+    --version             show program's version number and exit
+
+
+Work Documents
+==============
+
+In addition to releases, ``rngit`` provides a work document management system for tracking tasks, investigations, issues and progress related to repositories. Work documents are stored as structured msgpack data and support threaded updates and comments.
+
+**Listing Work Documents**
+
+To view work documents for a repository:
+
+.. code:: text
+
+  $ rngit work rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo list
+
+  Active documents
+  =================
+
+  ID   Title                    Author             Created           Comments
+  ---------------------------------------------------------------------------
+  1    Implemented new feature  9710b86ba12c4f2e…  2025-01-15 14:32         3
+  2    Fixed bug in parser      8f3a21c9d84e927b…  2025-01-14 09:15         1
+
+Use ``--scope completed`` to view completed work documents, or ``--scope all`` to see both active and completed.
+
+**Viewing a Work Document**
+
+To view a specific work document with all its comments:
+
+.. code:: text
+
+  $ rngit work rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo view -d 1
+  
+  Implement new feature (active #1)
+  =================================
+  Author   : 9710b86ba12c42d1d8f30f74fe509286
+  Status   : active
+  Created  : 2026-05-05 15:11:11
+  Edited   : 2026-05-05 18:22:11
+  Format   : markdown
+  Updates  : 0
+
+  This work document tracks the implementation of the new feature...
+
+  Updates
+  =======
+
+  #1 by 9710b86ba12c42d1d8f30f74fe509286 at 2026-05-05 15:38:37
+  -------------------------------------------------------------
+  Initial analysis complete
+
+**Creating Work Documents**
+
+To create a new work document:
+
+.. code:: text
+
+  $ rngit work rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo create --title "Investigate performance issue"
+
+This will open your configured ``$EDITOR`` to compose the document content. Save and exit to create the document, or save an empty document to cancel.
+
+**Editing Work Documents**
+
+To edit an existing work document:
+
+.. code:: text
+
+  $ rngit work rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo edit -d 1
+
+This fetches the current content, opens it in your editor, and sends any changes back to the node.
+
+**Adding Comments**
+
+To add an update to a work document:
+
+.. code:: text
+
+  $ rngit work rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo update -d 1
+
+This opens your editor to compose the update.
+
+**Completing Work Documents**
+
+To mark a work document as completed (moving it from ``active`` to ``completed``):
+
+.. code:: text
+
+  $ rngit work rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo complete -d 1
+
+  Work document #1 completed
+
+**Activating Work Documents**
+
+To mark a work document as active (moving it from ``completed`` to ``active``):
+
+.. code:: text
+
+  $ rngit work rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo activate -d 1
+
+  Work document #1 activated
+
+**Deleting Work Documents**
+
+To delete a work document and all its comments:
+
+.. code:: text
+
+  $ rngit work rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo delete -id 1
+
+  Are you sure you want to delete active work document #1? [y/N]: y
+  Work document #1 deleted
+
+**Permissions**
+
+Users can view work documents and updates if the have ``read`` permission for the repository. If users have ``read`` and ``interact``, they can also post updates/comments on existing work documents. Work document management requires having ``write`` and ``interact`` permission to the repository. These permissions are configured the same way as any other repository permissions. In the config file or ``.allowed`` files, use ``i:target`` to grant work document interaction rights:
+
+.. code:: text
+
+  # In .allowed file or config
+  i:all          # Allow everyone
+  i:9710b86...   # Allow specific identity
+  i:none         # Deny everyone
+
+**Author Verification**
+
+Users can only edit or delete work documents and updates they created. The author is cryptographically verified from the interacting link's ``remote_identity``.
+
+**Storage Format**
+
+Work documents are stored in a ``repo_name.work`` directory next to the repository, containing:
+
+- ``active/`` - Active work documents
+- ``completed/`` - Completed work documents
+
+Each document is a numbered directory containing:
+
+- ``root`` - The work document content and metadata (msgpack format)
+- ``N`` - Numbered comment files (msgpack format)
+
+**Nomad Network Interface**
+
+When the Nomad Network page node is enabled, work documents are viewable through the web interface. The work page lists all documents with their status, and clicking a document shows its full content and updates.
+
+**All Command-Line Options (rngit work)**
+
+.. code:: text
+
+  usage: rngit work [-h] [--config CONFIG] [--rnsconfig RNSCONFIG]
+                    [-i PATH] [--scope SCOPE] [-t TITLE] [-d ID] [-v]
+                    [-q] [--version]
+                    [repository] [operation]
+
+  Reticulum Git Work Document Manager
+
+  positional arguments:
+    repository            URL of remote repository
+    operation             list, view, create, edit, delete, update or complete
+
+  options:
+    -h, --help            show this help message and exit
+    --config CONFIG       path to alternative config directory
+    --rnsconfig RNSCONFIG
+                          path to alternative Reticulum config directory
+    -i, --identity PATH   path to identity
+    --scope SCOPE         document scope: active, completed or all
+    -t, --title TITLE     document title for create
+    -d, --id ID           document ID
+    -v, --verbose
+    -q, --quiet
+    --version             show program's version number and exit

docs/manual/_sources/index.rst.txt

@@ -20,13 +20,17 @@ to participate in the development of Reticulum itself.
 
    whatis
    gettingstartedfast
+   zen
+   software
    using
    understanding
    hardware
    interfaces
    networks
+   git
    support
    examples
+   license
 
 .. toctree::
    :maxdepth: 2

docs/manual/_sources/interfaces.rst.txt

@@ -356,6 +356,7 @@ software-based soundmodems. To do this, use the ``kiss_framing`` option:
     kiss_framing = True
     target_host = 127.0.0.1
     target_port = 8001
+    fixed_mtu = 500
 
 **Caution!** Only use the KISS framing option when connecting to external devices
 and programs like soundmodems and similar over TCP. When using the
@@ -364,6 +365,9 @@ never enable ``kiss_framing``, since this will disable internal reliability and
 recovery mechanisms that greatly improves performance over unreliable and
 intermittent TCP links.
 
+For KISS devices that need only supports a particular MTU, you can use the
+``fixed_mtu`` option.
+
 .. note::
    The TCP interfaces support tunneling over I2P, but to do so reliably,
    you must use the i2p_tunneled option:
@@ -907,6 +911,213 @@ beaconing functionality described above.
     # small internal packet buffer.
     flow_control = false
 
+.. _interfaces-discoverable:
+
+Discoverable Interfaces
+=======================
+
+Reticulum includes a powerful system for publishing your local interfaces to the wider network, allowing other peers to :ref:`discover, validate, and automatically connect to them<using-interface_discovery>`. This feature is particularly useful for creating decentralized networks where peers can dynamically find entrypoints, such as public Internet gateways or local radio access points, without relying on static configuration files or centralized directories.
+
+When an interface is made **discoverable**, your Reticulum instance will periodically broadcast an announce packet containing the connection details and parameters required for other peers to establish a connection. These announces are propagated over the network using the standard Reticulum announce mechanism using the ``rnstransport.discovery.interface`` destination type.
+
+.. note::
+   To use the interface discovery functionality, the ``LXMF`` module must be installed in your Python environment. You can install it using pip:
+
+   .. code:: sh
+
+     pip install lxmf
+
+
+Enabling Discovery
+------------------
+
+Interface discovery is enabled on a per-interface basis. To make a specific interface discoverable, you must add the ``discoverable`` option to that interface's configuration block and set it to ``yes``.
+
+.. code:: ini
+
+  [[My Public Gateway]]
+    type = BackboneInterface
+    ...
+    discoverable = yes
+
+Once enabled, Reticulum will automatically handle the generation, signing, stamping, and broadcasting of the discovery announces. It is not *required* to enable Transport to publish interface discovery information, but for most use cases where you want others to connect to you, you will likely want ``enable_transport`` set to ``yes`` in the ``[reticulum]`` section of your configuration.
+
+
+Discovery Parameters
+--------------------
+
+When ``discoverable`` is enabled, a variety of additional options become available to control how the interface is presented to the network. These parameters allow you to fine-tune the metadata, security requirements, and visibility of your interface.
+
+**Basic Metadata**
+
+``discovery_name``
+  A human-readable name for the interface. This name will be displayed to users on remote systems when they list discovered interfaces. If not specified, the interface name (the section header) will be used.
+
+``announce_interval``
+  The interval in minutes between successive discovery announces for this interface. Default is 360 minutes (6 hours). For stable, long-running infrastructure, higher intervals (12 to 22 hours) are usually sufficient and reduce network load. Minimum allowed value is 5 minutes (but expect to have your announces throttled if using intervals below one hour).
+
+**Connectivity Specification**
+
+``reachable_on``
+  Specifies the address that remote peers should use to connect to this interface. 
+  
+  *   For TCP and Backbone interfaces, this is typically the public IP address or hostname. Do not include the port, this is fetched automatically from the interface.
+  *   For I2P interfaces, this is usually the I2P ``b32`` address. This value is fetched automatically from the ``I2PInterface`` once it is up and connected to the I2P network, so you should not set this manually, unless you absolutely know what you're doing.
+  
+  **Dynamic Resolution:** This option also accepts a path to an external executable script or binary. If a path is provided, Reticulum will execute the script and use its ``stdout`` as the reachability address. This is useful for devices behind dynamic DNS, NATs, or complex cloud environments where the external IP is not known locally. The script must simply print the address to stdout and exit.
+
+.. note::
+  When using an executable script for ``reachable_on``, Reticulum expects the script to output only the IP address or hostname to ``stdout``, followed by a newline character. Any additional output or errors may cause the resolution to fail. Ensure the script has executable permissions and is robust against temporary network failures.
+
+A minimal example of a script that resolves the externally available, public IP of an internet-connected system could look like this:
+
+.. code:: bash
+
+  #!/bin/bash
+  curl -s ip.me
+  exit $?
+
+On a real system, you should make the script robust enough to deal with intermittent Internet or service failures, such that the script *always* returns a sensible value, or if not possible at least exits with a non-zero exit return code, so Reticulum knows the output is invalid.
+
+**Security & Cost**
+
+``discovery_stamp_value``
+  Defines the proof-of-work difficulty for the cryptographic stamp included in the announce. This value acts as a cost barrier to prevent network flooding. The default value is ``14``. Increasing this value makes it computationally more expensive to generate an announce, which can be useful to prevent spam on very large networks, but it also increases CPU load on your system when generating announces. Stamps are cached, and only generated if interface information changes, or at instance restart. If you have the computational resources, it is generally advisable to use as high a stamp value as possible.
+
+**Privacy & Encryption**
+
+``discovery_encrypt``
+  If set to ``yes``, the discovery announce payload will be encrypted. To decrypt the announce, remote peers must possess the *network identity* configured for your instance (see ``network_identity`` in the ``[reticulum]`` section). This allows you to publish private interfaces that are only discoverable to specific trusted networks.
+
+.. important::
+   If you enable ``discovery_encrypt`` but do not configure a valid ``network_identity`` in the ``[reticulum]`` section of your configuration, Reticulum will abort the interface discovery announce. Encryption requires a valid network identity key to function.
+
+``publish_ifac``
+  If set to ``yes``, the Interface Access Code (IFAC) name and passphrase for this interface will be included in the discovery announce. This allows peers to automatically configure the correct authentication parameters when connecting to the interface.
+
+**Physical Location**
+
+``latitude``, ``longitude``, ``height``
+  Optional physical coordinates for the interface. These are useful for mapping discovered interfaces geographically or for clients to automatically select the nearest access point. Coordinates should be in decimal degrees, height in meters.
+
+**Radio Parameters**
+
+For physical radio interfaces like ``RNodeInterface`` or ``KISSInterface``, the following optional parameters allow you to broadcast the operating frequency and characteristics, allowing clients to verify compatibility before connecting:
+
+``discovery_frequency``
+  The operating frequency in Hz. Auto-configured on RNode interfaces. Necessary on KISS-based radio interfaces and ``TCPClientInterfaces`` connecting to radio modems.
+
+``discovery_bandwidth``
+  The signal bandwidth in Hz. Auto-configured on RNode interfaces. Useful on KISS-based radio interfaces and ``TCPClientInterfaces`` connecting to radio modems.
+
+``discovery_modulation``
+  The modulation type or scheme. Auto-configured on RNode interfaces, but highly advisable to include on other radio-based interfaces.
+
+
+Interface Modes
+---------------
+
+When you enable discovery on an interface, Reticulum enforces certain interface modes to ensure the interface is actually useful for remote peers. 
+
+If an interface is configured as ``discoverable``, but its mode is not explicitly set to ``gateway`` (for server-style interfaces like ``BackboneInterface`` or ``TCPServerInterface``) or ``access_point`` (for radio interfaces like ``RNodeInterface``), Reticulum will automatically configure the appropriate mode and log a notice. 
+
+For example, if you enable discovery on a ``RNodeInterface`` without specifying the mode, Reticulum will automatically set it to ``access_point`` mode.
+
+Security Considerations
+-----------------------
+
+When making interfaces discoverable, you are effectively broadcasting an invitation to connect to your system. It is important to understand the security implications of the configuration options you choose.
+
+**Publishing Credentials**
+
+If you enable ``publish_ifac = yes``, your interface's authentication passphrase will be included in the announce. If you are operating a public network and want anyone to connect, this is acceptable. However, if you wish to restrict access to a specific group of users, you **must** enable ``discovery_encrypt = yes``. This ensures that only peers possessing the correct ``network_identity`` can decode the passphrase.
+
+**Topology Exposure**
+
+A discoverable interface announces its presence, location (if configured), and capabilities to the network. Even if the connection details are encrypted, the *fact* that a connectable node exists within a certain network becomes public information. In high-security or scenarios requiring operational secrecy, consider the implications of advertising your infrastructure's existence.
+
+Example Configuration
+---------------------
+
+Below is an example configuration for a public backbone gateway. This configuration publishes a high-value, publicly discoverable interface, that anyone can connect to.
+
+.. code:: ini
+
+  [[My Public Gateway]]
+    type = BackboneInterface
+    mode = gateway
+    listen_on = 0.0.0.0
+    port = 4242
+
+    # Enable Discovery
+    discoverable = yes
+
+    # Interface Details
+    discovery_name = Region A Public Entrypoint
+    announce_interval = 720
+
+    # Use external script to resolve dynamic IP
+    reachable_on = /usr/local/bin/get_external_ip.sh
+
+    # Generate high stamp value
+    discovery_stamp_value = 24
+
+    # Optional location data
+    latitude = 51.99714
+    longitude = -0.74195
+    height = 15
+
+The next example create an encrypted discovery-enabled interface, requiring a specific network identity to decode, and includes IFAC credentials for seamless authentication.
+
+.. code:: ini
+
+  [[My Private Gateway]]
+    type = BackboneInterface
+    mode = gateway
+    listen_on = 0.0.0.0
+    port = 5858
+    network_name = internal_1
+    passphrase = Mevpekyafshak5Wr
+
+    # Enable Discovery
+    discoverable = yes
+
+    # Interface Details
+    discovery_name = Region A Private Backbone
+    announce_interval = 720
+
+    # Use external script to resolve dynamic IP
+    reachable_on = /usr/local/bin/get_external_ip.sh
+
+    # Target stamp value
+    discovery_stamp_value = 22
+
+    # Encrypt announces for our network only
+    discovery_encrypt = yes
+
+    # Include credentials so trusted
+    # peers can connect automatically
+    publish_ifac = yes
+
+    # Optional location data
+    latitude = 34.06915
+    longitude = -118.44318
+    height = 15
+
+In the ``[reticulum]`` section of your configuration, you would define the network identity used for encryption as follows:
+
+.. code:: ini
+
+  [reticulum]
+  ...
+  # The identity used to sign/encrypt discovery announces
+  network_identity = ~/.reticulum/storage/identities/my_network_identity
+  ...
+
+With these configuration options applied, your Reticulum instance will actively participate in the network's discovery ecosystem. Other peers running Reticulum with discovery enabled will be able to see your interface, validate its cryptographic stamp, and (depending on their configuration) automatically connect to it.
+
+For information on how to use these discovered interfaces and configure your system to auto-connect to them, refer to the :ref:`Discovering Interfaces<using-interface_discovery>` chapter.
+
 .. _interfaces-options:
 
 Common Interface Options
@@ -987,6 +1198,15 @@ These can be used to control various aspects of interface behaviour.
      option, to set the interface speed in *bits per second*.
 
 
+ * | The ``bootstrap_only`` option designates an interface as a temporary
+     bridge for initial connectivity. If this option is enabled, the
+     interface will be monitored and automatically detached once the
+     number of auto-connected interfaces reaches the limit configured by
+     ``autoconnect_discovered_interfaces``. This is particularly useful
+     for using a slow or expensive connection (such as a single LoRa
+     link or a remote TCP tunnel) solely to discover better local
+     infrastructure, which then supersedes the bootstrap interface.
+
 .. _interfaces-modes:
 
 Interface Modes

docs/manual/_sources/license.rst.txt

@@ -0,0 +1,36 @@
+.. _license:
+
+Reticulum License
+=================
+
+.. code:: text
+	
+	Reticulum License
+
+	Copyright (c) 2016-2026 Mark Qvist
+
+	Permission is hereby granted, free of charge, to any person obtaining a copy
+	of this software and associated documentation files (the "Software"), to deal
+	in the Software without restriction, including without limitation the rights
+	to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+	copies of the Software, and to permit persons to whom the Software is
+	furnished to do so, subject to the following conditions:
+
+	- The Software shall not be used in any kind of system which includes amongst
+	  its functions the ability to purposefully do harm to human beings.
+
+	- The Software shall not be used, directly or indirectly, in the creation of
+	  an artificial intelligence, machine learning or language model training
+	  dataset, including but not limited to any use that contributes to the
+	  training or development of such a model or algorithm.
+
+	- The above copyright notice and this permission notice shall be included in
+	  all copies or substantial portions of the Software.
+
+	THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+	IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+	FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+	AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+	LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+	OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+	SOFTWARE.

docs/manual/_sources/networks.rst.txt

@@ -4,17 +4,47 @@
 Building Networks
 *****************
 
-This chapter will provide you with the knowledge needed to build networks with
-Reticulum, which can often be easier than using traditional stacks, since you
-don't have to worry about coordinating addresses, subnets and routing for an
+This chapter will provide you with the high-level knowledge needed to build networks with
+Reticulum. It will not, however tell you all you need to know to succesfully
+design and configure every kind of network you can imagine. For this, you will
+most likely need to read this manual in its entirity, invest significant time
+into experimenting with the stack, and learning functionality intuitively.
+
+Still, after reading this chapter, you should be well equipped to *start* that
+journey. While Reticulum is **fundamentally different** compared to other
+networking technologies, it can often be easier than using traditional stacks.
+If you've built networks before, you will probably have to forget, or at least
+temporarily ignore, a lot of things at this point. It will all makes sense in
+the end though. Hopefully.
+
+If you're used to protocols like IP, let's at least start with some relief:
+You don't have to worry about coordinating addresses, subnets and routing for an
 entire network that you might not know how will evolve in the future. With
 Reticulum, you can simply add more segments to your network when it becomes
 necessary, and Reticulum will handle the convergence of the entire network
-automatically.
+automatically. There's plenty more neat aspects like that to Reticulum, but
+we're getting ahead of ourselves. Let's cover the basics first.
 
 Concepts & Overview
 --------------------
 
+Before you start building your own networks, it's important to understand the
+fundamental principles that distinguish Reticulum networks from traditional
+networking approaches. These principles shape how you design your network,
+what trade-offs you encounter, and what capabilities you can rely on.
+
+Reticulum is not a single network you "join", it is a toolkit for *creating* networks.
+You decide what mediums to use, how nodes connect, what trust boundaries exist,
+and what the network's purpose is. Reticulum provides the cryptographic foundation,
+the transport mechanisms, and the convergence algorithms that make your design
+workable. You provide the intent and the structure.
+
+This approach offers tremendous flexibility, but it requires thinking in terms of
+different abstractions than those used in conventional networking.
+
+Introductory Considerations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 There are important points that need to be kept in mind when building networks
 with Reticulum:
 
@@ -31,6 +61,11 @@ with Reticulum:
      interconnect with much larger and higher bandwidth networks without issue.
      Reticulum automatically manages the flow of information to and from various
      network segments, and when bandwidth is limited, local traffic is prioritised.
+     You will, however, need to configure your interfaces correctly. If you tell
+     Reticulum to pass all announce traffic from a gigabit link to a LoRa interfaces,
+     it will try as best as possible to comply with this, while still respecting
+     bandwidth limits, but you *will* waste a lot of precious bandwidth and airtime,
+     and your LoRa network will not work very well.
 
  * | Reticulum provides sender/initiator anonymity by default. There is no way
      to filter traffic or discriminate it based on the source of the traffic.
@@ -89,81 +124,227 @@ Any number of interfaces can be configured, and Reticulum will automatically
 decide which are suitable to use in any given situation, depending on where
 traffic needs to flow.
 
-Example Scenarios
------------------
+Destinations, Not Addresses
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-This section illustrates a few example scenarios, and how they would, in general
-terms, be planned, implemented and configured.
+In traditional networking, addresses are allocated from a managed space. If you want to
+communicate with another node, you need to know its address, and that address
+must be unique within the network segment. This requires coordination, either
+through manual assignment, DHCP servers, or other allocation mechanisms.
 
-Interconnected LoRa Sites
-=========================
+Reticulum replaces addresses with **destinations**. A destination is identified by a 16-byte
+hash (128 bits) derived from a SHA-256 hash of the destination's identifying
+characteristics. This hash serves as the address on the network. On the network, it
+is represented in binary, but when displayed to human users, it will usually look something like
+this ``<13425ec15b621c1d928589718000d814>``.
 
-An organisation wants to provide communication and information services to it's
-members, which are located mainly in three separate areas. Three suitable hill-top
-locations are found, where the organisation can install equipment: Site A, B and C.
+The critical difference is that *any node can generate as many destinations as it
+needs, without coordination*. A destination's uniqueness is guaranteed by the
+collision resistance of SHA-256 and the inclusion of the node's public key in the
+hash calculation. Two nodes can both use the destination name
+``messenger.user.inbox``, but they will have different destination hashes because
+their public keys differ. Both can coexist on the same network without conflict.
 
-Since the amount of data that needs to be exchanged between users is mainly text-
-based, the bandwidth requirements are low, and LoRa radios are chosen to connect
-users to the network.
+This has profound implications for network design:
 
-Due to the hill-top locations found, there is radio line-of-sight between site A
-and B, and also between site B and C. Because of this, the organisation does not
-need to use the Internet to interconnect the sites, but purchases four Point-to-Point
-WiFi based radios for interconnecting the sites.
+* **No address allocation planning:** You never need to reserve address ranges,
+  plan subnets, or coordinate with other network operators. Nodes simply generate
+  destinations and announce them.
 
-At each site, a Raspberry Pi is installed to function as a gateway. A LoRa radio
-is connected to the Pi with a USB cable, and the WiFi radio is connected to the
-Ethernet port of the Pi. At site B, two WiFi radios are needed to be able to reach
-both site A and site C, so an extra Ethernet adapter is connected to the Pi in
-this location.
+* **Global portability:** A destination is not tied to a physical location or
+  network segment. A node can move its destinations across interfaces, mediums,
+  or even between entirely separate Reticulum networks simply by sending an
+  announce on the new medium.
 
-Once the hardware has been installed, Reticulum is installed on all the Pis, and at
-site A and C, one interface is added for the LoRa radio, as well as one for the WiFi
-radio. At site B, an interface for the LoRa radio, and one interface for each WiFi
-radio is added to the Reticulum configuration file. The transport node option is
-enabled in the configuration of all three gateways.
+* **Implicit authentication:** Because destinations are bound to public keys,
+  communication to a destination is inherently cryptographically authenticated.
+  Only the holder of the corresponding private key can decrypt and respond to
+  traffic addressed to that destination. This also makes application-level
+  authentication *much* simpler, since it can directly use the foundational
+  identity verification built into the core networking layer.
 
-The network is now operational, and ready to serve users across all three areas.
-The organisation prepares a LoRa radio that is supplied to the end users, along
-with a Reticulum configuration file, that contains the right parameters for
-communicating with the LoRa radios installed at the gateway sites.
+* **Identity abstraction:** A single Reticulum Identity can create multiple
+  destinations. This allows a single entity (a person, a device, a service) to
+  present multiple endpoints without needing multiple cryptographic keypairs.
 
-Once users connect to the network, anyone will be able to communicate with anyone
-else across all three sites.
 
-Bridging Over the Internet
-==========================
+Transport Nodes and Instances
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-As the organisation grows, several new communities form in places too far away
-from the core network to be reachable over WiFi links. New gateways similar to those
-previously installed are set up for the new communities at the new sites D and E, but
-they are islanded from the core network, and only serve the local users.
+Reticulum distinguishes between two types of nodes: **Instances**
+and **Transport Nodes**. Every node running Reticulum is an Instance, but not
+every Instance is a Transport Node.
 
-After investigating the options, it is found that it is possible to install an
-Internet connection at site A, and an interface on the Internet connection is
-configured for Reticulum on the Raspberry Pi at site A.
+A **Reticulum Instance** is any system running the Reticulum stack. It can create
+destinations, send and receive packets, establish links, and communicate with
+other nodes. It can also host destinations that are connectable for *anyone* else
+in the network. This means you can easily host globally available services from
+any location, including your home or office. Network-wide, global connectivity
+for all destinations is guaranteed, as long as there is *some* physical way to
+actually transport the packets. Instances are the default state and are appropriate for most end-user devices,
+such as phones, laptops, sensors, or any device that primarily consumes network services.
 
-A member of the organisation at site D, named Dori, is willing to help by sharing
-the Internet connection she already has in her home, and is able to leave a Raspberry
-Pi running. A new Reticulum interface is configured on her Pi, connecting to the newly
-enabled Internet interface on the gateway at site A. Dori is now connected to both
-the nodes at her own local site (through the hill-top LoRa gateway), and all the
-combined users of sites A, B and C. She then enables transport on her node, and
-traffic from site D can now reach everyone at site A, B and C, and vice versa.
+A **Transport Node** is an Instance that has been explicitly configured to
+participate in network-wide transport. Transport nodes forward packets across
+hops, propagate announces, maintain path tables, and serve path requests on
+behalf of other nodes. When a destination sends an announce, Transport Nodes
+receive it, remember the path, and rebroadcast it to other interfaces. When a node
+needs to reach a destination it doesn't have a path for, Transport Nodes help
+resolve the path through the network.
 
-Growth and Convergence
-======================
+Even devices hosting services or serving content should probably just be configured
+as instances, and themselves connect to wider networks via a Transport Node.
+In some situations, this may not be practical though, and as an example, it is
+entirely viable to host a personal Transport Node on a Raspberry Pi, while it
+is at the same time running an LXMF propagation node, and hosting your personal
+site or files over Reticulum.
 
-As the organisation grows, more gateways are added to keep up with the growing user
-base. Some local gateways even add VHF radios and packet modems to reach outlying users
-and communities that are out of reach for the LoRa radios and WiFi backhauls.
+The distinction is important. **Not** every node should be a Transport Node:
 
-As more sites, gateways and users are connected, the amount of coordination required
-is kept to a minimum. If one community wants to add connectivity to the next one
-over, it can simply be done without having to involve everyone or coordinate address
-space or routing tables.
+* **Resource consumption:** Transport nodes maintain path tables, process
+  announces, and forward traffic. This requires memory and CPU resources that
+  may be limited on low-powered devices.
 
-With the added geographical coverage, the operators at site A one day find that
-the original internet bridged interfaces are no longer utilised. The network has
-converged to be completely self-connected, and the sites that were once poorly
-connected outliers are now an integral part of the network.
+* **Stability requirements:** Transport nodes contribute to network convergence.
+  If Transport Nodes frequently go offline, path tables become stale and
+  convergence suffers. Stable, always-on nodes make better Transport Nodes.
+
+* **Bandwidth considerations:** Transport nodes process and rebroadcast network
+  maintenance traffic. On very low-bandwidth mediums, having too many Transport
+  Nodes will consume capacity that should be used for actual data.
+
+In practice, a network typically has a relatively small number of Transport Nodes
+strategically placed to provide coverage and connectivity. End-user devices run
+as Instances, connecting through nearby Transport Nodes to reach the wider network.
+This pattern mirrors traditional networking where routers forward traffic while
+end hosts simply consume connectivity, but with the crucial difference that any
+node *can* become a router if needed, and the decision is yours to make based on
+your network's requirements.
+
+Transport nodes also function as distributed cryptographic keystores. When a
+destination announces itself, Transport Nodes cache the public key and destination
+information. Other nodes can request unknown public keys from the network, and
+Transport Nodes respond with the cached information. This eliminates the need for
+a central directory service while ensuring that public keys remain available
+throughout the network.
+
+Trustless Networking
+^^^^^^^^^^^^^^^^^^^^
+
+Traditional network security models assume high levels of trust at
+specific layers. You might trust your ISP to deliver packets without inspection,
+or trust your VPN provider to handle your traffic, or trust the network
+administrator to configure firewalls appropriately. These trust relationships
+create vulnerabilities and dependencies.
+
+Reticulum is designed to function in **open, trustless environments**. This
+means the protocol makes no assumptions about the trustworthiness of the network
+infrastructure, the other participants, or the transport mediums. Every aspect
+of communication is secured cryptographically:
+
+* **Traffic encryption:** All traffic to single destinations is encrypted using
+  ephemeral keys.
+
+* **Source anonymity:** Reticulum packets do not include source addresses.
+  An observer intercepting a packet cannot determine who sent it, only who it is
+  addressed to (unless IFAC is enabled, in which case nothing can be determined).
+  This provides initiator anonymity by default.
+
+* **Path verification:** The announce mechanism includes cryptographic signatures that
+  prove the authenticity of destination announcements.
+
+* **Unforgeable delivery confirmations:** When a destination proves receipt of a
+  packet, the proof is signed with the destination's identity key. This prevents
+  false acknowledgments and ensures reliable delivery verification.
+
+* **Interface authentication:** When using Interface Access Codes (IFAC), packets
+  on authenticated interfaces carry signatures derived from a shared secret. Only
+  nodes with the correct network name and passphrase can generate valid packets, allowing creation
+  of virtual private networks on shared mediums.
+
+The trustless design has important consequences for network design:
+
+* **Open-access networks are viable:** You can build networks that anyone can
+  join without pre-approval. Because traffic is encrypted and authenticated end-
+  to-end, participants cannot interfere with each other's private communication,
+  even if they share the same transport infrastructure.
+
+* **No traffic inspection or prioritization:** Because traffic contents and
+  sources are opaque to intermediate nodes, there is no mechanism for filtering,
+  prioritizing, or throttling traffic based on its type or origin. All traffic
+  is treated equally. From a neutrality perspective, this is a feature.
+
+* **Adversarial resilience:** The network can operate even if some nodes are
+  malicious or controlled by adversaries. While a malicious Transport Node could
+  refuse to forward certain traffic or drop packets, it cannot decrypt, modify,
+  or impersonate legitimate traffic. Redundant paths and multiple Transport Nodes
+  mitigate the impact of malicious nodes.
+
+Of course, you can also create closed networks. Interface Access
+Codes allow you to restrict participation on specific interfaces. Network
+Identities enable you to verify that discovered interfaces belong to trusted
+operators. Blackhole management lets you block malicious identities. Reticulum
+provides both the tools for open networks and the controls for closed ones. The
+choice is yours based on your requirements.
+
+
+Heterogeneous Connectivity
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In conventional networking, mixing different transport mediums typically requires
+gateways, translation layers, and careful configuration. A WiFi network doesn't
+natively interoperate with a packet radio network without additional infrastructure,
+and you can't just download a car over a serial port, or send an encrypted message
+in a QR code.
+
+Reticulum treats **heterogeneity as a core premise**. The protocol is designed
+to seamlessly mix mediums with vastly different characteristics:
+
+* **Bandwidth:** LoRa links operating at a few hundred bits per second can
+  interconnect with gigabit Ethernet backbones. Reticulum automatically manages
+  the flow of information, prioritizing local traffic on slow segments while
+  allowing global convergence.
+
+* **Latency:** Satellite links with multi-second latency can coexist with local
+  links measured in milliseconds. The transport system handles timing, asynchronous
+  delivery and retransmissions transparently.
+
+* **Topology:** Point-to-point microwave links, broadcast radio networks,
+  switched Ethernet fabrics, and virtual tunnels over the Internet can all be
+  part of the same Reticulum network.
+
+* **Reliability:** Intermittent connections that come and go (such as mobile
+  devices or opportunistic radio contacts) can participate alongside always-on
+  infrastructure. Reticulum gracefully handles link loss and reconnection.
+
+This heterogeneity is achieved through several design elements:
+
+* **Expandable, medium-agnostic interface system:** Reticulum communicates with the physical
+  world through interface modules. Adding support for a new medium is a matter
+  of implementing an interface class. The protocol itself remains unchanged.
+
+* **Interface modes:** Different modes (``full``, ``gateway``, ``access_point``,
+  ``roaming``, ``boundary``) allow you to configure how interfaces interact with
+  the wider network based on their characteristics and role.
+
+* **Announce propagation rules:** Announces are forwarded between interfaces
+  according to rules that account for bandwidth limitations and interface modes.
+  Slow segments are not overwhelmed by traffic from fast segments.
+
+* **Local traffic prioritization:** When bandwidth is constrained, Reticulum
+  prioritizes announces for nearby destinations. This ensures that local
+  connectivity remains functional even when global convergence is incomplete.
+
+For network designers, this means you are free to use whatever mediums are
+available, affordable, or appropriate for your situation. You might use LoRa for
+wide-area low-bandwidth coverage, WiFi for local high-capacity links, I2P for
+anonymous Internet connectivity, and Ethernet for infrastructure backhauls, all
+within the same network. Reticulum handles the translation and coordination
+automatically.
+
+The key design consideration is not whether different mediums can work together
+(they can), but **how** they should work together based on your goals. A node
+with multiple interfaces spanning heterogeneous mediums needs to be configured
+with appropriate interface modes so that traffic flows efficiently. A gateway
+connecting a slow LoRa segment to a fast Internet backbone should be configured
+differently than a mobile device roaming between radio cells.

docs/manual/_sources/software.rst.txt

@@ -0,0 +1,355 @@
+.. _software-main:
+
+************************
+Programs Using Reticulum
+************************
+
+This chapter provides a non-exhaustive list of notable programs, systems and application-layer
+protocols that have been built using Reticulum.
+
+These programs will let you get a feel for how Reticulum works. Most of them have been designed
+to run well even over slow networks based on LoRa or packet radio, but all can also be used over fast
+links, such as local WiFi, wired Ethernet, the Internet, or any combination.
+
+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.
+
+Programs & Utilities
+====================
+
+Many different applications using Reticulum already exist, serving a wide variety of purposes
+from day-to-day communication and information sharing to systems administration and tackling
+advanced networking and communications challenges.
+
+Development of Reticulum-based applications and systems is ongoing, so consider this list
+a non-exhaustive starting point of *some* of the options available. With a bit of searching,
+primarily over Reticulum itself, you will find many more interesting things.
+
+Remote Shell
+^^^^^^^^^^^^
+
+The `rnsh <https://github.com/acehoss/rnsh>`_ program lets you establish fully interactive
+remote shell sessions over Reticulum. It also allows you to pipe any program to or from a
+remote system, and is similar to how ``ssh`` works. The ``rnsh`` program is very efficient, and
+can facilitate fully interactive shell sessions, even over extremely low-bandwidth links,
+such as LoRa or packet radio.
+
+In addition to the default, fully interactive terminal mode,
+for extremely limited links, ``rnsh`` offers line-interactive mode, allowing you to interact
+with remote systems, even when link throughput is counted in a few hundreds of bits per second.
+
+.. raw:: latex
+
+    \newpage
+
+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.
+
+.. image:: screenshots/nomadnet_3.png
+    :target: https://github.com/markqvist/nomadnet
+
+`Nomad Network <https://github.com/markqvist/nomadnet>`_ is a user-facing client
+for the messaging and information-sharing protocol LXMF.
+
+RNS Page Node
+^^^^^^^^^^^^^
+
+`RNS Page Node <https://git.quad4.io/RNS-Things/rns-page-node>`_ is a simple way to serve pages and files to any other Nomad Network compatible client. Drop-in replacement for NomadNet nodes that primarily serve pages and files.
+
+
+Retipedia
+^^^^^^^^^
+
+You can host the entirity of Wikipedia (or any ``.zim``) file to other Nomad Network clients using `Retipedia <https://github.com/RFnexus/Retipedia>`_.
+
+
+.. raw:: latex
+
+    \newpage
+
+Sideband
+^^^^^^^^
+
+If you would rather use an LXMF client with a graphical user interface, you can take
+a look at `Sideband <https://unsigned.io/sideband>`_, which is available for Android,
+Linux, macOS and Windows. Sideband is an advanced LXMF and LXST client, and a multi-purpose Reticulum
+utility, with features and functionality targeted at advanced users.
+
+.. only:: html
+
+  .. image:: screenshots/sideband_devices.webp
+      :align: center
+      :target: https://unsigned.io/sideband
+
+.. only:: latex
+
+  .. image:: screenshots/sideband_devices.png
+      :align: center
+      :target: https://unsigned.io/sideband
+
+Sideband allows you to communicate with other people or LXMF-compatible
+systems over Reticulum networks using LoRa, Packet Radio, WiFi, I2P, Encrypted QR
+Paper Messages, or anything else Reticulum supports.
+
+It also interoperates with all other LXMF clients, and provides advanced features such as voice messaging,
+real-time voice calls, file attachments, private telemetry sharing, and a full
+plugin system for expandability.
+
+.. raw:: latex
+
+    \newpage
+
+MeshChatX
+^^^^^^^^
+
+A `Reticulum MeshChat fork from the future <https://git.quad4.io/RNS-Things/MeshChatX>`_, with the goal of providing everything you need for Reticulum, LXMF, and LXST in one beautiful and feature-rich application. This project is separate from the original Reticulum MeshChat project, and is not affiliated with the original project.
+
+.. only:: html
+
+  .. image:: screenshots/meshchatx.webp
+      :align: center
+      :target: https://git.quad4.io/RNS-Things/MeshChatX
+
+.. only:: latex
+
+  .. image:: screenshots/meshchatx.png
+      :align: center
+      :target: https://git.quad4.io/RNS-Things/MeshChatX
+
+
+Features include full LXST support, custom voicemail, phonebook, contact sharing, and ringtone support, multi-identity handling, modern UI/UX, offline documentation, expanded tools, page archiving, integrated maps, telemetry and improved application security.
+
+.. raw:: latex
+
+    \newpage
+
+MeshChat
+^^^^^^^^
+
+The `Reticulum MeshChat <https://github.com/liamcottle/reticulum-meshchat>`_ application
+is a user-friendly LXMF client for Linux, macOS and Windows, that also includes a Nomad Network
+page browser and other interesting functionality.
+
+.. only:: html
+
+  .. image:: screenshots/meshchat_1.webp
+      :align: center
+      :target: https://github.com/liamcottle/reticulum-meshchat
+
+.. only:: latex
+
+  .. image:: screenshots/meshchat_1.png
+      :align: center
+      :target: https://github.com/liamcottle/reticulum-meshchat
+
+Reticulum MeshChat is of course also compatible with Sideband and Nomad Network, or
+any other LXMF client.
+
+Columba
+^^^^^^^
+
+`Columba <https://github.com/torlando-tech/columba/>`_ is a simple and familiar LXMF
+messaging app Android, built with a native Android interface and Material Design 3.
+
+.. only:: html
+
+  .. image:: screenshots/columba.webp
+      :align: center
+      :width: 25%
+      :target: https://github.com/torlando-tech/columba/
+
+.. only:: latex
+
+  .. image:: screenshots/columba.png
+      :align: center
+      :width: 25%
+      :target: https://github.com/torlando-tech/columba/
+
+While still in early and very active development, it is of course also compatible
+with all other LXMF clients, and allows you to message seamlessly with anyone else
+using LXMF.
+
+.. raw:: latex
+
+    \newpage
+
+Reticulum Relay Chat
+^^^^^^^^^^^^^^^^^^^^
+
+`Reticulum Relay Chat <https://rrc.kc1awv.net/>`_ is a live chat system built on top of the Reticulum Network Stack. It exists to let people talk to each other in real time over Reticulum without dragging in message databases, synchronization engines, or architectural commitments they did not ask for.
+
+The `rrcd <https://github.com/kc1awv/rrcd>`_ program provides a functional, reference RRC hub-server daemon implementation. RRC user clients include `rrc-gui <https://github.com/kc1awv/rrc-gui>`_ and `rrc-web <https://github.com/kc1awv/rrc-web>`_.
+
+RRC is closer in spirit to IRC than to modern “everything platforms.” You connect, you join a room, you talk, and then you leave. If you were present, you saw the conversation. If you were not, the conversation did not wait for you. This is not an accident. This is the entire design.
+
+RetiBBS
+^^^^^^^
+
+`RetiBBS <https://github.com/kc1awv/RetiBBS>`_ is a bulletin board system implementation for Reticulum networks.
+
+.. only:: html
+
+  .. image:: screenshots/retibbs.webp
+      :align: center
+      :target: https://github.com/kc1awv/RetiBBS
+
+.. only:: latex
+
+  .. image:: screenshots/retibbs.png
+      :align: center
+      :target: https://github.com/kc1awv/RetiBBS
+
+RetiBBS allows users to communicate through message boards in a secure manner.
+
+.. raw:: latex
+
+    \newpage
+
+RBrowser
+^^^^^^^^
+
+The `rBrowser <https://github.com/fr33n0w/rBrowser>`_ program is a cross-platform, standalone, web-based browser for exploring NomadNetwork Nodes over Reticulum Network. It automatically discovers NomadNet nodes through network announces and provides a user-friendly interface for browsing distributed content with Micron markup support.
+
+.. only:: html
+
+  .. image:: screenshots/rbrowser.webp
+      :align: center
+      :target: https://github.com/fr33n0w/rBrowser
+
+.. only:: latex
+
+  .. image:: screenshots/rbrowser.png
+      :align: center
+      :target: https://github.com/fr33n0w/rBrowser
+
+Includes useful features like automatic listening for announce, adding nodes to favorites, browsing and rendering any kind of NomadNet links, downloading files from remote nodes, a unique local NomadNet Search Engine and more.
+
+
+.. raw:: latex
+
+    \newpage
+
+Reticulum Network Telephone
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``rnphone`` program, included as part of the `LXST <https://github.com/markqvist/LXST>`_ package is a command-line Reticulum telephone utility and daemon, that allows building physical, hardware telephones for LXST and Reticulum, as well as simply performing calls via the command line.
+
+.. only:: html
+
+  .. image:: screenshots/rnphone.webp
+      :align: center
+      :target: https://github.com/markqvist/LXST
+
+.. only:: latex
+
+  .. image:: screenshots/rnphone.jpg
+      :align: center
+      :target: https://github.com/markqvist/LXST
+
+It supports interfacing directly with hardware peripherals such as GPIO keypads and LCD displays, providing a modular system for building secure hardware telephones.
+
+.. raw:: latex
+
+    \newpage
+
+LXST Phone
+^^^^^^^^^^
+
+The `LXST Phone <https://github.com/kc1awv/lxst_phone>`_ program is a cross-platform desktop application for performing LXST voice calls over Reticulum.
+
+.. only:: html
+
+  .. image:: screenshots/lxst_phone.webp
+      :align: center
+      :target: https://github.com/kc1awv/lxst_phone
+
+.. only:: latex
+
+  .. image:: screenshots/lxst_phone.png
+      :align: center
+      :target: https://github.com/kc1awv/lxst_phone
+
+It supports various advanced features such as SAS verification, peer blocking, rate limiting, encrypted call history storage and contact management.
+
+
+.. raw:: latex
+
+    \newpage
+
+LXMFy
+^^^^^
+
+`LXMFy <https://lxmfy.quad4.io/>`_ is a comprehensive and advanced bot creation framework for LXMF, that allows building any kind of automation or bot system running over LXMF and Reticulum. `Bot implementations exist <https://github.com/lxmfy/awesome-lxmfy-bots>`_ for Home Assistant control, LLM integrations, and various other purposes.
+
+
+LXMF Interactive Client
+^^^^^^^^^^^^^^^^^^^^^^^
+
+`LXMF Interactive Client <https://github.com/fr33n0w/lxmf-cli>`_ is a feature-rich, terminal-based LXMF messaging client with many advanced features and an extensible plugin architecture.
+
+RNS FileSync
+^^^^^^^^^^^^
+
+The `RNS FileSync <https://git.quad4.io/RNS-Things/RNS-Filesync>`_ program enables automatic file synchronization between devices without requiring central servers, internet connectivity, or cloud services. It works over any network medium supported by Reticulum, including radio, LoRa, WiFi, or the internet, making it ideal for off-grid, privacy-focused, and resilient file sharing.
+
+
+Micron Parser JS
+^^^^^^^^^^^^^^^^
+
+`Micron Parser JS <https://github.com/RFnexus/micron-parser-js>`_ is the JavaScript-based parser for the Micron markup language, that most web-based Nomad Network browsers use. If you want to make utilities or tools that display Micron pages, this library is essential.
+
+
+RNMon
+^^^^^
+
+`RNMon <https://github.com/lbatalha/rnmon>`_ is a monitoring daemon designed to monitor the status of multiple RNS applications and push the metrics to an InfluxDB instance over the influx line protocol.
+
+
+.. raw:: latex
+
+    \newpage
+
+Protocols
+=========
+
+A number of standard protocols have emerged through real-world usage and testing in the Reticulum community. While you may sometimes want to use completely custom protocols and implementations when writing Reticulum-based software, using these protocols provides application developers with an easy way to implement advanced functionality quickly and effortlessly. Using them also ensures compatibility and interoperability between many different client applications, creating an open communications ecosystem where users are free to choose the applications that suit their needs, while remaining connected to everyone else.
+
+LXMF
+^^^^
+
+`LXMF <https://github.com/markqvist/lxmf>`_ is a simple and flexible messaging format and delivery protocol that allows a wide variety of applications, while using as little bandwidth as possible. It offers zero-conf message routing, end-to-end encryption and Forward Secrecy, and can be transported over any kind of medium that Reticulum supports.
+
+LXMF is efficient enough that it can deliver messages over extremely low-bandwidth systems such as packet radio or LoRa. Encrypted LXMF messages can also be encoded as QR-codes or text-based URIs, allowing completely analog paper message transport.
+
+Using Propagation Nodes, LXMF also offer a way to store and forward messages to users or endpoints that are not directly reachable at the time of message emission.
+
+LXST
+^^^^
+
+`LXST <https://github.com/markqvist/lxst>`_ is a simple and flexible real-time streaming format and delivery protocol that allows a wide variety of applications, while using as little bandwidth as possible. It is built on top of Reticulum and offers zero-conf stream routing, end-to-end encryption and Forward Secrecy, and can be transported over any kind of medium that Reticulum supports. It currently powers real-time voice and telephony applications over Reticulum.
+
+RRC
+^^^
+
+The `Reticulum Relay Chat <https://rrc.kc1awv.net/>`_ protocol, is a live chat system built on top of the Reticulum Network Stack. It exists to provide near real-time group communication without dragging in message history databases, federation machinery, or architectural guilt.
+
+RRC is intentionally simple. It does not pretend to be email, a mailbox, or a distributed archive. It behaves more like a conversation in a room. If you were there, you heard it. If you were not, you did not. That is not a bug, that is the point.
+
+Interface Modules & Connectivity Resources
+==========================================
+
+This section provides a list of various community-provided interface modules, guides and resources for creating Reticulum networks over special or challenging mediums.
+
+* Custom interface module for running `RNS over HTTP <https://git.quad4.io/RNS-Things/RNS-over-HTTP>`_
+* Guide for running `Reticulum over ICMP <https://github.com/matvik22000/rns-over-icmp>`_ using ``PipeInterface``
+* Guide for running `Reticulum over DNS <https://github.com/markqvist/Reticulum/discussions/1002>`_ with Iodine
+* Guide for running `Reticulum over HF radio <https://github.com/RFnexus/reticulum-over-hf>`_
+* `Modem73 <https://github.com/RFnexus/modem73>`_ is a KISS TNC OFDM modem frontend that can be used with Reticulum

docs/manual/_sources/support.rst.txt

@@ -16,12 +16,12 @@ Donations are gratefully accepted via the following channels:
     Monero:
     84FpY1QbxHcgdseePYNmhTHcrgMX4nFfBYtz2GKYToqHVVhJp8Eaw1Z1EedRnKD19b3B8NiLCGVxzKV17UMmmeEsCrPyA5w
 
-    Ethereum:
-    0x81F7B979fEa6134bA9FD5c701b3501A2e61E897a
-
     Bitcoin:
-    3CPmacGm34qYvR6XWLVEJmi2aNe3PZqUuq
+    bc1pgqgu8h8xvj4jtafslq396v7ju7hkgymyrzyqft4llfslz5vp99psqfk3a6
 
+    Ethereum:
+    0x91C421DdfB8a30a49A71d63447ddb54cEBe3465E
+    
     Liberapay:
     https://liberapay.com/Reticulum/
 
@@ -33,15 +33,28 @@ organisation? Make them a reality quickly by sponsoring their implementation.
 
 Provide Feedback
 ================
-All feedback on the usage, functioning and potential dysfunctioning of any and
+Feedback on the usage, functioning and potential dysfunctioning of any and
 all components of the system is very valuable to the continued development and
-improvement of Reticulum.
+improvement of Reticulum. But...
+
+.. warning::
+  
+  **Think before you speak**. As time has shown, over 80% of the "feedback",
+  "bug reports" and "advice" the Reticulum project has received has been
+  irrelevant noise, stemming from erroneous assumptions, misunderstanding the
+  foundational functionality or philosophy behind the system, or simply
+  the malinformed (but overly opinionated) personal preferences of individual
+  drive-by architects. This wastes the time of everyone involved.
+
+  The Reticulum project is not a public teahouse for serving the attention
+  needs of random bypassers, but a highly complex system engineered and
+  refined over more than a decade, designed to provide communication and
+  connectivity guarantees in highly adversarial environments.
+
+  If you want to voice your opinion, it better be well-informed, and we
+  expect you to have a comprehensive and solid foundation for your points
+  of view. Everything else will be ignored.
 
 Absolutely no automated analytics, telemetry, error
 reporting or statistics is collected and reported by Reticulum under any
 circumstances, so we rely on old-fashioned human feedback.
-
-Contribute Code
-===============
-Join us on `the GitHub repository <https://github.com/markqvist/reticulum>`_ to
-report issues, suggest functionality and contribute code to Reticulum.

docs/manual/_sources/understanding.rst.txt

@@ -13,9 +13,8 @@ reference implementation and API reference. That being said, this chapter is an
 understanding how Reticulum works from a high-level perspective, along with the general principles of
 Reticulum, and how to apply them when creating your own networks or software.
 
-After reading this document, you should be well-equipped to understand how a Reticulum network
-operates, what it can achieve, and how you can use it yourself. If you want to help out with the
-development, this is also the place to start, since it will provide a pretty clear overview of the
+After reading this chapter, you should be well-equipped to understand how a Reticulum network
+operates, what it can achieve, and how you can use it yourself. This chapter also seeks to provide an overview of the
 sentiments and the philosophy behind Reticulum, what problems it seeks to solve, and how it
 approaches those solutions.
 
@@ -117,7 +116,7 @@ Reticulum uses the singular concept of *destinations*. Any application using Ret
 networking stack will need to create one or more destinations to receive data, and know the
 destinations it needs to send data to.
 
-All destinations in Reticulum are _represented_ as a 16 byte hash. This hash is derived from truncating a full
+All destinations in Reticulum are *represented* as a 16 byte hash. This hash is derived from truncating a full
 SHA-256 hash of identifying characteristics of the destination. To users, the destination addresses
 will be displayed as 16 hexadecimal bytes, like this example: ``<13425ec15b621c1d928589718000d814>``.
 
@@ -141,7 +140,7 @@ ratchets on a per-destination basis. The multi-hop transport, coordination, veri
 layers are fully autonomous and also based on elliptic curve cryptography.
 
 Reticulum also offers symmetric key encryption for group-oriented communications, as well as
-unencrypted packets for local broadcast purposes.
+unencrypted packets (for local broadcast purposes **only**).
 
 Reticulum can connect to a variety of interfaces such as radio modems, data radios and serial ports,
 and offers the possibility to easily tunnel Reticulum traffic over IP links such as the Internet or
@@ -401,11 +400,10 @@ any transport node receiving it, but according to some specific rules:
     to be transmitted, the newest announce is discarded. If the newest announce contains different
     application specific data, it will replace the old announce.
 
-Once an announce has reached a node in the network, any other node in direct contact with that
-node will be able to reach the destination the announce originated from, simply by sending a packet
-addressed to that destination. Any node with knowledge of the announce will be able to direct the
-packet towards the destination by looking up the next node with the shortest amount of hops to the
-destination.
+Once an announce has reached a transport node in the network, any other node in direct contact with that
+transport node will be able to reach the destination the announce originated from, simply by sending a packet
+addressed to that destination. Any transport node with knowledge of the announce will be able to direct the
+packet towards the destination by looking up the most efficient next node to the destination.
 
 According to these rules, an announce will propagate throughout the network in a predictable way,
 and make the announced destination reachable in a short amount of time. Fast networks that have the
@@ -414,6 +412,17 @@ new destinations. Slower segments of such networks might take a bit longer to ga
 the wide and fast networks they are connected to, but can still do so over time, while prioritising full
 and quickly converging end-to-end connectivity for their local, slower segments.
 
+.. tip::
+
+    Even very slow networks, that simply don't have the capacity to ever reach *full* convergence
+    will generally still be able to reach **any other destination on any connected segments**, since
+    interconnecting transport nodes will prioritize announces into the slower segments that are
+    actually requested by nodes on these.
+
+    This means that slow, low-capacity or low-resource segments **don't** need to have full network
+    knowledge, since paths can always be recursively resolved from other segments that do have
+    knowledge about them.
+
 In general, even extremely complex networks, that utilize the maximum 128 hops will converge to full
 end-to-end connectivity in about one minute, given there is enough bandwidth available to process
 the required amount of announces.
@@ -424,7 +433,7 @@ Reaching the Destination
 ------------------------
 
 In networks with changing topology and trustless connectivity, nodes need a way to establish
-*verified connectivity* with each other. Since the network is assumed to be trustless, Reticulum
+*verified connectivity* with each other. Since the underlying network mediums are assumed to be trustless, Reticulum
 must provide a way to guarantee that the peer you are communicating with is actually who you
 expect. Reticulum offers two ways to do this.
 
@@ -435,7 +444,7 @@ For exchanges of small amounts of information, Reticulum offers the *Packet* API
     an ECDH key exchange with the destination's public key (or ratchet key, if available), and encrypt the information.
 
 * | 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
     key exchange locally, before sending the packet.
 
 * | The public part of the newly generated ephemeral key-pair is included with the encrypted token, and sent
@@ -461,14 +470,14 @@ For exchanges of small amounts of information, Reticulum offers the *Packet* API
 
 For exchanges of larger amounts of data, or when longer sessions of bidirectional communication is desired, Reticulum offers the *Link* API. To establish a *link*, the following process is employed:
 
-* | First, the node that wishes to establish a link will send out a special packet, that
+* | First, the node that wishes to establish a link will send out a *link request* packet, that
     traverses the network and locates the desired destination. Along the way, the Transport Nodes that
-    forward the packet will take note of this *link request*.
+    forward the packet will take note of this *link request*, and mark it as pending.
 
 * | Second, if the destination accepts the *link request* , it will send back a packet that proves the
     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
-    accept the validity of the *link* throughout the network.
+    accept the validity of the *link* throughout the network. The link is now marked as *established*.
 
 * | When the validity of the *link* has been accepted by forwarding nodes, these nodes will
     remember the *link* , and it can subsequently be used by referring to a hash representing it.
@@ -560,9 +569,10 @@ an arbitrary number of hops, where information will be exchanged between two nod
     *link proof* to perform it's own Diffie Hellman Key Exchange and derive the symmetric key
     that is used to encrypt the channel. Information can now be exchanged reliably and securely.
 
+.. note::
 
-It’s important to note that this methodology ensures that the source of the request does not need to
-reveal any identifying information about itself. The link initiator remains completely anonymous.
+    It’s important to note that this methodology ensures that the source of the request does not need to
+    reveal any identifying information about itself. **The link initiator remains completely anonymous**.
 
 When using *links*, Reticulum will automatically verify all data sent over the link, and can also
 automate retransmissions if *Resources* are used.
@@ -585,6 +595,82 @@ the transfer, integrity verification and reassembling the data on the other end.
 of codes to reliably transfer any amount of data. They can be used to transfer data stored in memory,
 or stream data directly from files.
 
+.. _understanding-network_identities:
+
+Network Identities
+==================
+
+In Reticulum, every peer and application utilizes a cryptographic **Identity** to verify authenticity and establish encrypted channels. While standard identities are typically used to represent a single user, device, or service, Reticulum introduces the concept of a **Network Identity** to represent a logical group of nodes or an entire community infrastructure.
+
+A Network Identity is, at its core, a standard Reticulum Identity keyset. However, its purpose and usage differ from a personal identity. Instead of identifying a single entity, a Network Identity acts as a shared credential that federates multiple independent Transport Instances under a single, verifiable administrative domain.
+
+
+Conceptual Overview
+-------------------
+
+You can think of a standard Reticulum Identity as a self-sovereign, privately created passport for a single person. A Network Identity, conversely, is akin to a cryptographic flag, or a charter that flies over a fleet of ships. It signifies that while the ships may operate independently and be physically distant, they belong to the same organization, follow the same protocols, and are expected to act in concert.
+
+When you configure a Network Identity on one or more of your nodes, you are effectively declaring that these nodes constitute a specific "network" within a broader Reticulum mesh. This allows other peers to recognize interfaces not just as "a node named Alice", but as "a gateway belonging to The Eastern Ret Of Freedom".
+
+
+Current Usage
+-------------
+
+At present, the primary function of a Network Identity is within the :ref:`Interface Discovery<using-interface_discovery>` system.
+
+When a Transport Instance broadcasts a discovery announce for an interface, it can optionally sign that announce with a Network Identity, instead of just its local transport identity. Remote peers receiving the announce can then verify the signature. This provides functionality for two important distinctions:
+
+1.  **Authenticity:** It proves that the interface was published by an operator who possesses the private key for that Network Identity.
+2.  **Trust Boundaries:** It allows users to configure their systems to only accept and connect to interfaces that belong to specific Network Identities, effectively creating "whitelisted" zones of trusted infrastructure.
+
+.. note::
+  If you enable encryption on your discovery announces, the Network Identity is used as the shared secret. Only peers who have been explicitly provided with the Network Identity's full keyset (and have it configured locally) will be able to decrypt and utilize the connection details.
+
+  This functionality will be expanded in the future, so that peers with delegated keys can be allowed to decrypt discovery announces without holding the root network key. Currently, the functionality is sufficient for sharing interface information privately where you control all nodes that must decrypt the discovered interfaces.
+
+
+Future Implications
+-------------------
+
+While the current implementation focuses on interface discovery, the concept of Network Identities serves as the foundational building block for future Reticulum features designed to support large-scale, organic mesh formation.
+
+As the ecosystem evolves, Network Identities will facilitate:
+
+*   **Distributed Name Resolution:** A system where networks can publish name-to-identity mappings, allowing human-readable names to resolve without centralized servers.
+*   **Service Publishing:** Networks will be able to announce specific capabilities, services, or information endpoints available publicly or to their members.
+*   **Inter-Network Federation:** Trust relationships between different networks, allowing for seamless but managed flow of traffic and information across distinct administrative boundaries.
+*   **Distributed Blackhole Management:** A reputation-based system for blackhole list distribution, where trusted Network Identities can sign and publish lists of blackholed identities. This allows communities to collaboratively enforce security standards and filter spam or malicious identities across the parts of the wider mesh that they are responsible for.
+
+By adopting the use of Network Identities now, you are preparing your infrastructure to be compatible with this future functionality.
+
+
+Creating and Using a Network Identity
+-------------------------------------
+
+Since a Network Identity is simply a standard Reticulum Identity, you create one using the built-in tools.
+
+1.  **Generate the Identity:**
+    Use the ``rnid`` utility to generate a new identity file that will serve as your Network Identity.
+
+    .. code:: sh
+
+      $ rnid -g ~/.reticulum/storage/identities/my_network
+
+2.  **Distribute the Public Key:**
+    The public key must be distributed to any Transport Instance that needs to verify your network's announces and discovery information. By default, if your node is set up to use a network identity, this happens automatically (using the standard announce mechanism).
+
+3.  **Configure Instances:**
+    In the ``[reticulum]`` section of the configuration file on every node within your network, point the ``network_identity`` option to the file you created.
+
+    .. code:: ini
+
+      [reticulum]
+      ...
+      network_identity = ~/.reticulum/storage/identities/my_network
+      ...
+
+Once configured, your instances will automatically utilize this identity for signing discovery announces (and potentially decrypting network-private information), presenting a unified front to the wider network.
+
 .. _understanding-referencesystem:
 
 Reference Setup
@@ -624,18 +710,20 @@ into the future. The current Reference System Setup is as follows:
 * **Interface Device**
     A data radio consisting of a LoRa radio module, and a microcontroller with open source
     firmware, that can connect to host devices via USB. It operates in either the 430, 868 or 900
-    MHz frequency bands. More details can be found on the `RNode Page <https://unsigned.io/rnode>`_.
+    MHz frequency bands. More details can be found on the `RNode Page <https://github.com/markqvist/rnode_firmware>`_.
 * **Host Device**
     Any computer device running Linux and Python. A Raspberry Pi with a Debian based OS is
-    recommended.
+    a good place to start, but anything can be used.
 * **Software Stack**
-    The most recently released Python Implementation of Reticulum, running on a Debian based
+    The most recently released Python Implementation of Reticulum, running on a Linux-based
     operating system.
 
-To avoid confusion, it is very important to note, that the reference interface device **does not**
-use the LoRaWAN standard, but uses a custom MAC layer on top of the plain LoRa modulation! As such, you will
-need a plain LoRa radio module connected to an controller with the correct firmware. Full details on how to
-get or make such a device is available on the `RNode Page <https://unsigned.io/rnode>`_.
+.. note::
+
+    To avoid confusion, it is very important to note, that the reference interface device **does not**
+    use the LoRaWAN standard, but uses a custom MAC layer on top of the plain LoRa modulation! As such, you will
+    need a plain LoRa radio module connected to a controller with the correct firmware. Full details on how to
+    get or make such a device is available on the `RNode Page <https://github.com/markqvist/rnode_firmware>`_.
 
 With the current reference setup, it should be possible to get on a Reticulum network for around 100$
 even if you have none of the hardware already, and need to purchase everything.
@@ -649,16 +737,16 @@ Protocol Specifics
 ==================
 
 This chapter will detail protocol specific information that is essential to the implementation of
-Reticulum, but non critical in understanding how the protocol works on a general level. It should be
+Reticulum, but non-critical in understanding how the protocol works on a general level. It should be
 treated more as a reference than as essential reading.
 
 
 Packet Prioritisation
 ---------------------
 
-Currently, Reticulum is completely priority-agnostic regarding general traffic. All traffic is handled
-on a first-come, first-serve basis. Announce re-transmission are handled according to the re-transmission
-times and priorities described earlier in this chapter.
+Currently, Reticulum is completely priority-agnostic regarding *general* traffic. All traffic is handled
+on a first-come, first-serve basis. Announce re-transmission and other maintenance traffic is handled
+according to the re-transmission times and priorities described earlier in this chapter.
 
 
 Interface Access Codes
@@ -666,8 +754,8 @@ Interface Access Codes
 
 Reticulum can create named virtual networks, and networks that are only accessible by knowing a preshared
 passphrase. The configuration of this is detailed in the :ref:`Common Interface Options<interfaces-options>`
-section. To implement these feature, Reticulum uses the concept of Interface Access Codes, that are calculated
-and verified per packet.
+section. To implement this feature, Reticulum uses the concept of Interface Access Codes, that are calculated
+and verified per-packet.
 
 An interface with a named virtual network or passphrase authentication enabled will derive a shared Ed25519
 signing identity, and for every outbound packet generate a signature of the entire packet. This signature is
@@ -912,6 +1000,11 @@ with the OpenSSL backend being *much* faster. The most important consequence how
 potential loss of security by using primitives that has not seen the same amount of scrutiny,
 testing and review as those from OpenSSL.
 
+Using the normal RNS installation procedures, it is not possible to install Reticulum on a
+system without the required OpenSSL primitives being available, and if they are not, they will
+be resolved and installed as a dependency. It is only possible to use the pure-python primitives
+by manually specifying this, for example by using the ``rnspure`` package.
+
 .. warning::
    If you want to use the internal pure-python primitives, it is **highly advisable** that you
    have a good understanding of the risks that this pose, and make an informed decision on whether

docs/manual/_sources/using.rst.txt

@@ -338,8 +338,8 @@ Filter output to only show some interfaces:
 .. code:: text
 
   usage: rnstatus [-h] [--config CONFIG] [--version] [-a] [-A]
-                  [-l] [-s SORT] [-r] [-j] [-R hash] [-i path]
-                  [-w seconds] [-v] [filter]
+                  [-l] [-t] [-s SORT] [-r] [-j] [-R hash] [-i path]
+                  [-w seconds] [-d] [-D] [-m] [-I seconds] [-v] [filter]
 
   Reticulum Network Stack Status
 
@@ -353,12 +353,19 @@ Filter output to only show some interfaces:
     -a, --all             show all interfaces
     -A, --announce-stats  show announce stats
     -l, --link-stats      show link stats
-    -s SORT, --sort SORT  sort interfaces by [rate, traffic, rx, tx, announces, arx, atx, held]
+    -t, --totals          display traffic totals
+    -s, --sort SORT       sort interfaces by [rate, traffic, rx, tx, rxs, txs,
+                                              announces, arx, atx, held]
     -r, --reverse         reverse sorting
     -j, --json            output in JSON format
-    -R hash               transport identity hash of remote instance to get status from (requires -i)
+    -R hash               transport identity hash of remote instance to get status from
     -i path               path to identity used for remote management
     -w seconds            timeout before giving up on remote queries
+    -d, --discovered      list discovered interfaces
+    -D                    show details and config entries for discovered interfaces
+    -m, --monitor         continuously monitor status
+    -I, --monitor-interval seconds
+                          refresh interval for monitor mode (default: 1)
     -v, --verbose
 
 
@@ -463,6 +470,7 @@ Decrypt a file using the Reticulum Identity it was encrypted for:
     -B, --base32          Use base32-encoded input and output
     --version             show program's version number and exit
 
+.. _utility-rnpath:
 
 The rnpath Utility
 ====================
@@ -484,21 +492,23 @@ Resolve path to a destination:
 
 .. code:: text
 
-  usage: rnpath [-h] [--config CONFIG] [--version] [-t] [-m hops]
-                [-r] [-d] [-D] [-x] [-w seconds] [-R hash] [-i path]
-                [-W seconds] [-j] [-v] [destination]
+  usage: rnpath [-h] [--config CONFIG] [--version] [-t] [-m hops] [-r] [-d] [-D]
+                [-x] [-w seconds] [-R hash] [-i path] [-W seconds] [-b] [-B] [-U]
+                [--duration DURATION] [--reason REASON] [-p] [-j] [-v]
+                [destination] [list_filter]
 
-  Reticulum Path Discovery Utility
+  Reticulum Path Management Utility
 
   positional arguments:
     destination           hexadecimal hash of the destination
+    list_filter           filter for remote blackhole list view
 
   options:
     -h, --help            show this help message and exit
     --config CONFIG       path to alternative Reticulum config directory
     --version             show program's version number and exit
     -t, --table           show all known paths
-    -m hops, --max hops   maximum hops to filter path table by
+    -m, --max hops        maximum hops to filter path table by
     -r, --rates           show announce rate info
     -d, --drop            remove the path to a destination
     -D, --drop-announces  drop all queued announces
@@ -507,6 +517,13 @@ Resolve path to a destination:
     -R hash               transport identity hash of remote instance to manage
     -i path               path to identity used for remote management
     -W seconds            timeout before giving up on remote queries
+    -b, --blackholed      list blackholed identities
+    -B, --blackhole       blackhole identity
+    -U, --unblackhole     unblackhole identity
+    --duration DURATION   duration of blackhole enforcement in hours
+    --reason REASON       reason for blackholing identity
+    -p, --blackholed-list
+                          view published blackhole list for remote transport instance
     -j, --json            output in JSON format
     -v, --verbose
 
@@ -619,13 +636,20 @@ Or fetch a file from the remote system:
 
   $ rncp --fetch ~/path/to/file.tgz 73cbd378bb0286ed11a707c13447bb1e
 
+The default identity file is stored in ``~/.reticulum/identities/rncp``, but you can use
+another one, which will be created if it does not already exist
+
+.. code:: text
+
+  $ rncp ~/path/to/file.tgz 73cbd378bb0286ed11a707c13447bb1e -i /path/to/identity
+
 **All Command-Line Options**
 
 .. code:: text
 
   usage: rncp [-h] [--config path] [-v] [-q] [-S] [-l] [-F] [-f]
               [-j path] [-b seconds] [-a allowed_hash] [-n] [-p]
-              [-w seconds] [--version] [file] [destination]
+              [-i identity] [-w seconds] [--version] [file] [destination]
 
   Reticulum File Transfer Utility
 
@@ -650,11 +674,27 @@ Or fetch a file from the remote system:
     -a allowed_hash       allow this identity (or add in ~/.rncp/allowed_identities)
     -n, --no-auth         accept requests from anyone
     -p, --print-identity  print identity and destination info and exit
+    -i identity           path to identity to use
     -w seconds            sender timeout before giving up
     -P, --phy-rates       display physical layer transfer rates
     --version             show program's version number and exit
 
 
+The rngit Utility
+=================
+
+The ``rngit`` utility provides full Git repository hosting and interaction over Reticulum, as well as many other useful features for software development, collaboration and publishing. It allows you to host Git repositories on Reticulum nodes, interact with remote repositories using standard Git commands through the ``rns://`` URL scheme, and to publish software releases.
+
+The system consists of two parts: The ``rngit`` node that hosts and manages repositories, and the ``git-remote-rns`` helper that enables Git to communicate with rngit nodes. As soon as you have RNS installed on your system, you can transparently use Git with Reticulum-hosted repositories just like any other type of remote. Git over Reticulum uses URLs in the following format: ``rns://DESTINATION_HASH/group/repo``.
+
+If you set a branch to track a Reticulum remote as the default upstream, you can simply use ``git`` as you normally would; all commands work transparently and as expected.
+
+.. warning::
+   **The rngit program is a new addition to RNS!** This functionality was introduced in RNS 1.2.0. While great care has been taken to design a secure, but highly configurable and flexible permission system for allowing many users to interact with many different repositories on a single node, ``rngit`` has not been tested extensively in the wild! Be careful when hosting repositories, especially if they are public or semi-public.
+
+For the full documentation on the `rngit` system, see the :ref:`Git Over Reticulum<git-main>` chapter of this manual.
+
+
 The rnx Utility
 ================
 
@@ -727,6 +767,282 @@ another one, which will be created if it does not already exist
     --version             show program's version number and exit
 
 
+The rnsh Utility
+================
+
+The ``rnsh`` utility provides a fully interactive remote shell over Reticulum.
+It allows you to establish encrypted, authenticated shell sessions on remote
+systems, complete with terminal emulation, pipe support, and window resizing.
+
+While the ``rnx`` utility is useful for simple remote command execution and
+retrieving output, ``rnsh`` provides a complete interactive terminal experience,
+making it ideal for remote administration and management tasks that require
+real-time interaction, just like SSH does for IP networks.
+
+``rnsh`` operates in two modes: a *listener* mode that accepts incoming
+connections, and an *initiator* mode that connects to a remote listener. Both
+sides authenticate using Reticulum Identities, ensuring that only authorised
+peers can establish sessions.
+
+.. note::
+   ``rnsh`` provides a genuine interactive terminal over Reticulum. It supports
+   full terminal emulation including escape sequences, window resizing, signal
+   forwarding, and piping of standard input, output and error streams. This
+   makes it suitable for running text editors, terminal multiplexers, and any
+   other interactive programs on remote systems.
+
+**Usage Examples**
+
+Start ``rnsh`` in listener mode, accepting connections from specific identities:
+
+.. code:: text
+
+  $ rnsh -l -a 941bed5e228775e5a8079fc38b1ccf3f -a 1b03013c25f1c2ca068a4f080b844a10
+
+You can also specify allowed identity hashes (one per line) in the file
+``~/.rnsh/allowed_identities`` or ``~/.config/rnsh/allowed_identities``, and
+simply run the program in listener mode:
+
+.. code:: text
+
+  $ rnsh -l
+
+Connect to a remote listener from another system:
+
+.. code:: text
+
+  $ rnsh 7a55144adf826958a9529a3bcf08b149
+
+Specify a command to run on the remote system, separating ``rnsh`` options from
+the remote command with ``--``:
+
+.. code:: text
+
+  $ rnsh 7a55144adf826958a9529a3bcf08b149 -- top
+
+Set a default command for the listener, in case the initiator does not supply
+one, or when remote command execution is disabled:
+
+.. code:: text
+
+  $ rnsh -l -- /bin/bash --login
+
+Use the ``-m`` flag to mirror the exit code of the remote process:
+
+.. code:: text
+
+  $ rnsh -m 7a55144adf826958a9529a3bcf08b149 -- /usr/local/bin/check-status
+
+Use the ``-p`` flag to display the identity and destination hash for a listener:
+
+.. code:: text
+
+  $ rnsh -l -p
+
+  Identity     : <984b74a3f768bef236af4371e6f248cd>
+  Listening on : 7a55144adf826958a9529a3bcf08b149
+
+Use a specific identity file rather than the default:
+
+.. code:: text
+
+  $ rnsh -l -i /path/to/identity
+
+Announce the listener destination on startup, and periodically:
+
+.. code:: text
+
+  $ rnsh -l -b 900
+
+The ``-b`` option specifies the announce period in seconds. Use ``0`` to
+announce only once at startup.
+
+**Authentication & Authorisation**
+
+By default, ``rnsh`` requires that connecting initiators identify themselves
+with a Reticulum Identity whose hash is present in the list of allowed
+identities. Allowed identities can be specified on the command line with the
+``-a`` option, and can be used multiple times:
+
+.. code:: text
+
+  $ rnsh -l -a 941bed5e228775e5a8079fc38b1ccf3f -a 1b03013c25f1c2ca068a4f080b844a10
+
+You can also maintain a list of allowed identity hashes in the file
+``~/.rnsh/allowed_identities`` or ``~/.config/rnsh/allowed_identities``,
+with one hex hash per line. This file is reloaded every time a new connection
+is received, so changes take effect immediately without restarting ``rnsh``.
+
+If you want to accept connections from any identity (for testing or in fully
+trusted environments), you can disable authentication with the ``-n`` option:
+
+.. code:: text
+
+  $ rnsh -l -n
+
+.. warning::
+   Disabling authentication with ``-n`` means that **any** Reticulum peer that
+   can reach your listener will be able to execute commands on your system. Only
+   use this option if you *really* know what you're doing.
+
+**Remote Command Control**
+
+When running in listener mode, ``rnsh`` allows you to control how remote
+commands are handled:
+
+- By default, the listener accepts the command sent by the initiator. If the
+  initiator does not supply a command, the listener's default shell is used.
+
+- Use ``-C`` (``--no-remote-command``) to disable execution of commands received
+  from the initiator. Only the listener's default command (or the command
+  specified after ``--``) will be executed:
+
+.. code:: text
+
+  $ rnsh -l -C -- /usr/local/bin/safe-script
+
+- Use ``-A`` (``--remote-command-as-args``) to append the initiator's command
+  to the listener's default command instead of replacing it. This can be useful
+  for restricting the remote to a specific program while still allowing the
+  initiator to pass arguments:
+
+.. code:: text
+
+  $ rnsh -l -A -- /usr/bin/top
+
+**Service Names**
+
+When running in listener mode, ``rnsh`` uses a service name to differentiate
+between multiple listener instances that may share the same identity. By
+default, the service name is ``default``. You can specify a different service
+name with the ``-s`` option:
+
+.. code:: text
+
+  $ rnsh -l -s monitoring
+
+This allows you to run multiple listeners on the same node, each with a
+different service name and purpose.
+
+**Initiator Options**
+
+When connecting to a remote listener, several options are available:
+
+- Use ``-N`` (``--no-id``) to disable sending your identity to the remote
+  listener. Note that the listener must have authentication disabled (``-n``)
+  for the connection to succeed in this case.
+
+- Use ``-m`` (``--mirror``) to make the initiator return with the exit code of
+  the remote process, rather than always returning ``0``.
+
+- Use ``-w`` (``--timeout``) to specify the connection and request timeout in
+  seconds. By default, the timeout matches the Reticulum path request timeout.
+
+**Identity & Destination**
+
+The default identity file for ``rnsh`` is stored at
+``~/.reticulum/identities/rnsh``, but you can specify a different one with the
+``-i`` option, which will be created if it does not already exist:
+
+.. code:: text
+
+  $ rnsh -l -i /path/to/identity
+
+To display the identity and destination information for a listener, use the
+``-p`` option. When combined with ``-l``, both the identity and the listening
+destination hash are displayed:
+
+.. code:: text
+
+  $ rnsh -p
+
+  Identity     : <984b74a3f768bef236af4371e6f248cd>
+
+  $ rnsh -l -p
+
+  Identity     : <984b74a3f768bef236af4371e6f248cd>
+  Listening on : 7a55144adf826958a9529a3bcf08b149
+
+**Verbosity**
+
+Like other Reticulum utilities, ``rnsh`` supports the ``-v`` and ``-q`` flags
+to increase or decrease logging verbosity. Multiple flags can be specified to
+further adjust the log level. The default log level is ``INFO`` for listeners
+and ``ERROR`` for initiators.
+
+.. code:: text
+
+  $ rnsh -l -vv       # Listener with debug-level output
+  $ rnsh -q 7a55144adf826958a9529a3bcf08b149   # Quiet initiator
+
+By default, all log output is routed to ``~/.rnsh/logfile`` for initiators.
+
+**Escape Sequences**
+
+During an active ``rnsh`` session, the following escape sequences are
+available. These are only recognised immediately after a newline character:
+
+- ``~~`` - Send a literal tilde character
+- ``~.`` - Terminate the session and exit immediately
+- ``~L`` - Toggle line-interactive mode
+- ``~?`` - Display the escape sequence quick reference
+
+**All Command-Line Options**
+
+.. code:: text
+
+  usage: rnsh [-h] [--config CONFIG] [--identity IDENTITY] [-v] [-q] [-p]
+              [--version] [-l] [-s SERVICE] [-b PERIOD] [-a HASH] [-n] [-A] [-C]
+              [-N] [-m] [-w SECONDS]
+              [destination]
+
+  Reticulum Remote Shell Utility
+
+  positional arguments:
+    destination           hexadecimal hash of the destination to connect to
+
+  options:
+    -h, --help            show this help message and exit
+    --config, -c CONFIG   path to alternative Reticulum config directory
+    --identity, -i IDENTITY
+                          path to identity file to use
+    -v, --verbose         increase verbosity
+    -q, --quiet           decrease verbosity
+    -p, --print-identity  print identity and destination info and exit
+    --version             show program's version number and exit
+    -l, --listen          listen (server) mode; any command specified after --
+                          will be used as the default command when the initiator
+                          does not provide one or when remote command execution
+                          is disabled; if no command is specified, the default
+                          shell of the user running rnsh will be used
+    -s, --service SERVICE
+                          service name for identity file if not the default
+    -b, --announce PERIOD
+                          announce on startup and every PERIOD seconds; specify
+                          0 to announce on startup only
+    -a, --allowed HASH    allow this identity to connect (may be specified
+                          multiple times); allowed identities can also be
+                          specified in ~/.rnsh/allowed_identities or
+                          ~/.config/rnsh/allowed_identities, one hash per line
+    -n, --no-auth         disable authentication (allow any identity to connect)
+    -A, --remote-command-as-args
+                          concatenate remote command to the argument list of the
+                          default program or shell
+    -C, --no-remote-command
+                          disable executing command lines received from the
+                          remote initiator
+    -N, --no-id           disable identity announcement on connect
+    -m, --mirror          return with the exit code of the remote process
+    -w, --timeout SECONDS
+                          connect and request timeout in seconds
+
+  When specifying a command to execute, separate rnsh options from the command
+  and its arguments with --. For example:
+
+    rnsh -l -- /bin/bash --login
+    rnsh <destination> -- ls -la /tmp
+
+
 The rnodeconf Utility
 =====================
 
@@ -810,6 +1126,104 @@ to create and provision new :ref:`RNodes<rnode-main>` from any supported hardwar
 For more information on how to create your own RNodes, please read the :ref:`Creating RNodes<rnode-creating>`
 section of this manual.
 
+.. _using-interface_discovery:
+Discovering Interfaces
+----------------------
+
+Reticulum includes built-in functionality for discovering connectable interfaces over Reticulum itself. This is particularly useful in situations where you want to do one or more of the following:
+
+* Discover connectable entrypoints available on the Internet
+* Find connectable radio access points in the physical world
+* Maintain connectivity to RNS instances with unknown or changing IP addresses
+
+Discovered interfaces can be **auto-connected** by Reticulum, which makes it possible to create setups where an arbitrary interface can act simply as a bootstrap connection, that can be torn down again once more suitable interfaces have been discovered and connected.
+
+The interface discovery mechanism uses announces sent over Reticulum itself, and supports both publicly readable interfaces and private, encrypted discovery, that can only be decoded by specified *network identities*. It is also possible to specify which network identities should be considered valid sources for discovered interfaces, so that interfaces published by unknown entities are ignored.
+
+.. note::
+  A *network identity* is a normal Reticulum identity keyset that can be used by
+  one or more transport nodes to identify them as belonging to the same overall
+  network. In the context of interface discovery, this makes it easy to manage
+  connecting to only the particular networks you care about, even if those networks
+  utilize many individual physical transport node.
+
+  This also makes it convenient to auto-connect discovered interfaces only for networks you have some level of trust in.
+
+For information on how to make your interfaces discoverable, see the :ref:`Discoverable Interfaces<interfaces-discoverable>` chapter of this manual. The current section will focus on how to actually *discover and connect to* interfaces available on the network.
+
+In its most basic form, enabling interface discovery is as simple as setting ``discover_interfaces`` to ``true`` in your Reticulum config:
+
+.. code:: text
+  
+  [reticulum]
+  ...
+  discover_interfaces = yes
+  ...
+
+Once this option is enabled, your RNS instance will start listening for interface discovery announces, and store them for later use or inspection. You can list discovered interfaces with the ``rnstatus`` utility:
+
+.. code:: text
+
+  $ rnstatus -d
+  
+  Name           Type      Status       Last Heard   Value  Location       
+  -------------------------------------------------------------------------
+  Sideband Hub   Backbone  ✓ Available  1h  ago      16     46.2316, 6.0536
+  RNS Amsterdam  Backbone  ✓ Available  32m ago      16     52.3865, 4.9037
+
+
+You can view more detailed information about discovered interfaces, including configuration snippets for pasting directly into your ``[interfaces]`` config, by using the ``rnstatus -D`` option:
+
+.. code:: text
+  
+  $ rnstatus -D sideband
+
+  Transport ID : 521c87a83afb8f29e4455e77930b973b
+  Name         : Sideband Hub
+  Type         : BackboneInterface
+  Status       : Available
+  Transport    : Enabled
+  Distance     : 2 hops
+  Discovered   : 9h and 40m ago
+  Last Heard   : 1h and 15m ago
+  Location     : 46.2316, 6.0536
+  Address      : sideband.connect.reticulum.network:7822
+  Stamp Value  : 16
+
+  Configuration Entry:
+    [[Sideband Hub]]
+      type = BackboneInterface
+      enabled = yes
+      remote = sideband.connect.reticulum.network
+      target_port = 7822
+      transport_identity = 521c87a83afb8f29e4455e77930b973b
+
+In addition to providing local interface discovery information and control, the ``rnstatus`` utility can export discovered interface data in machine-readable JSON format using the ``rnstatus -d --json`` option. This can be useful for exporting the data to external applications such as status pages, access point maps and similar.
+
+To control what sources are considered valid for discovered sources, additional
+configuration options can be specified for the interface discovery system.
+
+* The ``interface_discovery_sources`` option is a list of the network or transport identities from which interfaces will be accepted. If this option is set, all others will be ignored. If this option is not set, discovered interfaces will be accepted from any source, but are still subject to stamp value requirements.
+
+* The ``required_discovery_value`` options specifies the minimum stamp value required for the interface announce to be considered valid. To make it computationally difficult to spam the network with a large number of defunct or malicious interfaces, each announced interface requires a valid cryptographical stamp, of configurable difficulty value.
+
+* The ``autoconnect_discovered_interfaces`` value defaults to ``0``, and specifies the maximum number of discovered interfaces that should be auto-connected at any given time. If set to a number greater than ``0``, Reticulum automatically manages discovered interface connections, and will bring discovered interfaces up and down based on availability. You can at any time add discovered interfaces to your configuration manually, to persistently keep them available.
+
+* The ``network_identity`` option specifies the *network identity* for this RNS instance. This identity is used both to sign (and potentially encrypt) *outgoing* interface discovery announces, and to decrypt incoming discovery information.
+
+The configuration snippet below contains an example of setting these additional configuration options:
+
+.. code:: text
+  
+  [reticulum]
+  ...
+  discover_interfaces = yes
+  interface_discovery_sources = 521c87a83afb8f29e4455e77930b973b
+  required_discovery_value = 16
+  autoconnect_discovered_interfaces = 3
+  network_identity = ~/.reticulum/storage/identities/my_network
+  ...
+
 Remote Management
 -----------------
 
@@ -835,6 +1249,130 @@ in the Reticulum configuration file:
 
 For a complete example configuration, you can run ``rnsd --exampleconfig``.
 
+.. _using-blackhole_management:
+
+Blackhole Management
+--------------------
+
+Reticulum networks are fundamentally permissionless and open, allowing anyone with a compatible interface to participate. While this openness is essential for a resilient and decentralized network, it also exposes the network to potential abuse, such as peers flooding the network with excessive announce broadcasts or other forms of resource exhaustion.
+
+The **Blackhole** system provides tools to help manage this problem. It allows operators and individual users to block specific identities at the Transport layer, preventing them from propagating announces through your node, and for other nodes to reach them through your network.
+
+.. important::
+  
+  There is fundamentally **no way** to *globally* block or censor any identity or destination in Reticulum networks. The blackhole functionality will prevent announces from (and traffic to) all destinations associated with the blackholed identity *on your own network segments only*.
+
+  This provides users and operators with control over what they want to allow *on their own network segments*, but there is no way to globally censor or remove an identity, as long as *someone* is willing to provide transport for it.
+
+This functionality serves a dual purpose:
+
+*   **For Individual Users:** It offers a simple way to maintain a quiet and efficient local network by manually blocking spammy or unwanted peers.
+*   **For Network Operators:** It enables the creation of federated, community-wide security standards. By publishing and sharing blackhole lists, operators can protect large infrastructures and distribute spam filtering rules across the mesh without manual intervention.
+
+
+Local Blackhole Management
+==========================
+
+The most immediate way to manage unwanted identities is through manual configuration using the ``rnpath`` utility. This allows you to instantly block or unblock specific identities on your local Transport Instance.
+
+**Blackholing an Identity**
+
+To block an identity, use the ``-B`` (or ``--blackhole``) flag followed by the identity hash. You can optionally specify a duration and a reason, which are useful for logging and future reference.
+
+.. code:: text
+
+  $ rnpath -B 3a4f8b9c1d2e3f4g5h6i7j8k9l0m1n2o
+
+You can also add a duration (in hours) and a reason:
+
+.. code:: text
+
+  $ rnpath -B 3a4f8b9c1d2e3f4g5h6i7j8k9l0m1n2o --duration 24 --reason "Excessive announces"
+
+**Lifting Blackholes**
+
+To remove an identity from the blackhole, use the ``-U`` (or ``--unblackhole``) flag:
+
+.. code:: text
+
+  $ rnpath -U 3a4f8b9c1d2e3f4g5h6i7j8k9l0m1n2o
+
+**Viewing the Blackhole List**
+
+To see all identities currently blackholed on your local instance, use the ``-b`` (or ``--blackholed``) flag:
+
+.. code:: text
+
+  $ rnpath -b
+
+  <3a4f8b9c1d2e3f4g5h6i7j8k9l0m1n2o> blackholed for 23h, 56m (Excessive announces)
+  <399ea050ce0eed1816c300bcb0840938> blackholed indefinitely (Announce spam)
+  <d56a4fa02c0a77b3575935aedd90bdb2> blackholed indefinitely (Announce spam)
+  <2b9ec651326d9bc274119054c70fb75e> blackholed indefinitely (Announce spam)
+  <1178a8f1fad405bf2ad153bf5036bdfd> blackholed indefinitely (Announce spam)
+
+
+
+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.
+
+.. 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.
+
+When enabled, your Transport Instance will periodically (approximately once per hour) connect to configured sources, retrieve their latest blackhole lists, and automatically merge them into your local blocklist. This provides "set-and-forget" protection for both individual users and large networks.
+
+**Configuration**
+
+To enable automated sourcing, add the ``blackhole_sources`` option to the ``[reticulum]`` section of your configuration file. This option accepts a comma-separated list of Transport Identity hashes that you trust to provide valid blackhole lists.
+
+.. code:: ini
+
+  [reticulum]
+  ...
+  # Automatically fetch blackhole lists from these trusted sources
+  blackhole_sources = 521c87a83afb8f29e4455e77930b973b, 68a4aa91ac350c4087564e8a69f84e86
+  ...
+
+**How It Works**
+
+1.  When enabled, the ``BlackholeUpdater`` service runs in the background.
+2.  For every identity hash listed in ``blackhole_sources``, it attempts to establish a temporary link to its associated``rnstransport.info.blackhole`` destination.
+3.  It requests the ``/list`` path, which returns a dictionary of blackholed identities and their associated metadata.
+4.  The received list is merged with your local ``blackholed_identities`` database.
+5.  The lists are persisted to disk, ensuring they survive restarts.
+
+.. note::
+  You can verify the external lists you are subscribed to, and their contents, without importing them by using ``rnpath -p``. See the :ref:`rnpath utility documentation<utility-rnpath>` for details on querying remote blackhole lists.
+
+
+Publishing Blackhole Lists
+==========================
+
+If you are operating a public gateway, a community hub, or simply wish to share your blackhole list with others, you can configure your instance to act as a blackhole list publisher. This allows other nodes to subscribe to *your* definitions of unwanted traffic.
+
+**Enabling Publishing**
+
+To publish your local blackhole list, enable the ``publish_blackhole`` option in the ``[reticulum]`` section:
+
+.. code:: ini
+
+  [reticulum]
+  ...
+  publish_blackhole = yes
+  ...
+
+When this is enabled, your Transport Instance will register a request handler at ``rnstransport.info.blackhole``. Any peer that connects to this destination and requests ``/list`` will receive the complete set of identities currently present in your local blackhole database.
+
+**Federation and Trust**
+
+The blackhole system relies on the trust relationship between the subscriber and the publisher. By subscribing to a source, you are implicitly trusting that source to only block identities that are genuinely detrimental to the network.
+
+As the ecosystem matures, this system is designed to integrate with **Network Identities**. This allows communities to verify that a published blackhole list is actually provided by a specific network or organization with a certain level of reputation and trustworthiness, adding a layer of cryptographic trust to the federation process. This prevents malicious actors from publishing fake lists intended to censor legitimate traffic.
+
+For operators, this creates a scalable model where maintaining a single high-quality blocklist can protect thousands of downstream peers, drastically reducing the administrative.
+
 Improving System Configuration
 ------------------------------
 

docs/manual/_sources/whatis.rst.txt

@@ -6,6 +6,9 @@ Reticulum is a cryptography-based networking stack for building both local and
 wide-area networks with readily available hardware, that can continue to operate
 under adverse conditions, such as extremely low bandwidth and very high latency.
 
+To understand the foundational philosophy and goals of this system, read the
+:ref:`Zen of Reticulum <zen>`.
+
 Reticulum allows you to build wide-area networks with off-the-shelf tools, and
 offers end-to-end encryption, forward secrecy, autoconfiguring cryptographically
 backed multi-hop transport, efficient addressing, unforgeable packet
@@ -40,6 +43,22 @@ real-world use is explored. The API and wire-format can be considered complete a
 could change if absolutely warranted.
 
 
+Reference Implementation
+========================
+The Python code, for which this documentation is written, and known as the Reticulum Network Stack,
+is the Reference Implementation of Reticulum. The Reticulum Protocol is defined entirely
+and authoritatively by this reference implementation, and this manual. It is maintained by Mark Qvist,
+identified by the Reticulum Identity ``<bc7291552be7a58f361522990465165c>``.
+
+Compatibility with the Reticulum Protocol is defined as having full interoperability,
+and sufficient functional parity with this reference implementation. Any specific protocol
+implementation that achieves this is Reticulum. Any that does not is not Reticulum.
+
+The reference implementation is licensed under the :ref:`Reticulum License <license>`.
+
+The Reticulum Protocol was dedicated to the Public Domain in 2016.
+
+
 What does Reticulum Offer?
 ==========================
 
@@ -178,14 +197,7 @@ Reticulum implements a range of generalised interface types that covers the comm
 
   * Or to quickly create interfaces with custom hardware
 
+* Anything else using :ref:`custom interface modules<interfaces-custom>` written in Python
+
 For a full list and more details, see the :ref:`Supported Interfaces<interfaces-main>` chapter.
 
-
-Caveat Emptor
-==============
-Reticulum is an experimental networking stack, and should be considered as
-such. While it has been built with cryptography best-practices very foremost in
-mind, it has not yet been externally security audited, and there could very well be
-privacy-breaking bugs. To be considered secure, Reticulum needs a thorough
-security review by independent cryptographers and security researchers. If you
-want to help out with this, or can help sponsor an audit, please do get in touch.

docs/manual/_sources/zen.rst.txt

@@ -0,0 +1,453 @@
+.. _zen:
+
+****************
+Zen of Reticulum
+****************
+
+The Illusion Of The Center
+==========================
+
+For the better part of a generation, we have been taught to visualize the digital world through the lens of hierarchy. The mental maps we carry are dominated by a single, misleading image: **The Cloud**.
+
+We imagine the network as a vast, ethereal space "up there" or "out there". A centralized repository of services and data to which we, the lowly clients, must connect. We build our software with this assumption hardcoded into our logic: *There is a server. The server has the authority. The server knows the way. I must find the server to function*.
+
+This is the Client-Server mental model, and it is the primary obstacle to understanding Reticulum.
+
+Fallacy Of The Cloud
+--------------------
+
+The first step in the Zen of Reticulum is to realize that *there is no cloud*. There is only other people's computers. When you build for the cloud, you are building *for* a landlord. You are accepting that your application's existence is conditional on the permission, uptime, and continued goodwill of a central authority.
+
+In Reticulum, you must shift your thinking from "connecting to" to "being among". Reticulum is not a service you subscribe to - *it is a fabric you inhabit*. There is no "up there". There is only *here* and *there*, and the space between them is peer-to-peer.
+
+Decentralization Or Uncentralizability?
+---------------------------------------
+
+It is common to hear the word "decentralized" thrown around in modern tech circles. But often, this is merely a marketing term for "slightly distributed centralization". A blockchain with a few dominant miners, or a federated protocol with a few giant servers. *In practice*, it's still centralized. It simply has a few centers instead of one.
+
+Reticulum goes further. It wants **Uncentralizability**.
+
+This is not a wishful political stance, but a foundational mathematical characteristic of the protocol, onto which everything else has been built. Reticulum assumes that every peer on the network is potentially hostile, and every link is potentially compromised. It is designed with no "privileged" nodes. While some nodes may act as Transport Instances - forwarding traffic for others - they do so *blindly*, and they only know about their immediate surroundings, and nothing more. They route based on cryptographic proofs, not on administrative privilege. They cannot see who is talking to whom, nor can they selectively manipulate traffic without breaking their own ability to route entirely.
+
+The system is designed to make hierarchy structurally impossible. You cannot hijack an address, because there is no central registry to hijack. You cannot block a user, because there is no central switch to flip. You can offer paths through the network, but you can't force anyone to use them.
+
+Death To The Address
+--------------------
+
+To break free of the center, you must also let go of the concept of the "Address".
+
+In the IP world, an address is a location. It is a coordinate in a *deeply hierarchical* and static grid. If you move your computer to a different house, your address changes. If your router reboots, your address might change. Your *identity* is bound to your *location*, and therefore, it is fragile, and easily controlled.
+
+Reticulum abolishes this link between *Identity* and *Location*.
+
+In Reticulum, an address is not a place; it is a **Hash of an Identity**. It is a cryptographic representation of *who* you are, not *where* you are. Because of this, your address is portable. You can take a laptop from a WiFi cafe in Berlin, to a LoRa mesh in the mountains, to a packet radio link on a boat, and your "address" - your *Destination Hash* - never changes.
+
+The network does not route to a place; it routes to a *person* (or a machine). When you send a packet, you are not targeting a coordinate in a grid; you are encrypting a message for a specific entity. The network dynamically discovers where that entity currently resides, and it does so in a way where no one really knows where that entity is actually located physically.
+
+**Consider:**
+
+- **The Old Way:** *"I am at* ``192.168.1.5``. *Come find me"*.
+- **The Zen Way:** *"I am* ``<327c1b2f87c9353e01769b01090b18f2>``. *Wherever I am, my peers can reach me"*.
+
+Once you stop thinking about servers and start thinking about portable identities, where everyone can always reach everyone else directly, the illusion of the center fades away. You realize there *is* no center holding the network together. No coordinators or bureaucrats required. The network is simply the sum of its peers, communicating directly, sovereignly, and without a master.
+
+
+Physics Of Trust
+================
+*Paranoia Is A Great Design Principle*
+
+If we accept that there is no center - that the network is a chaotic, peer-to-peer mesh - we are forced to confront a terrifying reality: **There is no one guarding the door**.
+
+In the traditional networking mindset, we rely on the concept of the "trusted core". We assume our local coffee shop WiFi is safe, or that the backbone providers are neutral custodians. We build our security like a castle: strong walls on the outside, soft and trusting on the inside. We use encryption only when we step out into the "wild" internet.
+
+Hostile Environments
+--------------------
+
+The Zen of Reticulum requires you to invert this. You must assume that *every* environment is hostile. This isn't cynicism, just uncaring physics.
+
+When you transmit information over radio waves, you are shouting into a crowded room. Anyone can listen. When you traverse the internet, your packets pass through routers controlled by strangers, corporations, and state actors. Assuming privacy in this environment without cryptographic protection is not optimism but gross negligence.
+
+Reticulum is built on the premise that every link is tapped, and every peer is a potential adversary. If your system cannot survive an adversary owning the physical layer, it cannot survive at all.
+
+But this is the paradox: By assuming the network is hostile, you make it safe. When you accept the dangers for what they are, they become manageable. When you stop trusting the infrastructure and start trusting the math, you eliminate the single point of failure: Human integrity.
+
+Encryption Is Not A Feature
+---------------------------
+
+In the world of TCP/IP, encryption is an afterthought. It is a layer we slap on top of the protocol (HTTPS, TLS) to patch the security holes of the original design. It is a "feature" you sometimes *enable* for "sensitive data". This is fundamentally flawed, since all data is sensitive.
+
+In Reticulum, encryption is **gravity**.
+
+It is not optional. It is not a plugin. It is the *fundamental force that allows the network to exist*. If you were to strip the encryption from Reticulum, the routing would break. The Transport system uses cryptographic signatures and entropy to verify paths and pass information. If packets were plaintext, intermediate nodes could not prove that a route was valid, nor could endpoints prevent spoofing or tampering.
+
+In Reticulum, the entropy of the encrypted packet *is* the routing logic.
+
+To ask for a version of Reticulum without encryption is like asking for a version of the ocean without liquid. You are not asking for a feature change; you're asking for a different physical universe. We design for a universe where information has mass, structure, and integrity.
+
+Zero-Trust Architectures
+------------------------
+
+We must unlearn our reliance on **Institutional Trust**.
+
+For decades, we have been trained to trust authorities. We trust a website because a chain of Certificate Authorities (companies we don't know) vouches for it. We trust an app because it is in an app store (run by a corporation we don't control). We trust a message because it comes from a phone number assigned by a telecom. Yet, everything in our digital information sphere today is more untrustworthy and risky than a medieval second-hand underwear market.
+
+Reticulum replaces institutional trust with **Cryptographic Proof**.
+
+In Reticulum, you do not trust a node because it has a nice hostname or because it is listed in a directory. You trust it because it holds the private key corresponding to the Destination Hash you are communicating with. This trust is binary, mathematical, and **absolute**. Either the signature matches, or it does not. There is no "maybe".
+
+This shift moves the power from the institution to the individual. You become the ultimate arbiter of your own trust relationships. You decide which keys to accept, which paths to follow, and which identities to recognize.
+
+**Consider:**
+
+- **The Old Way:** *"I trust this site because the browser says the lock icon is green"*.
+- **The Zen Way:** *"I trust this destination because I have verified its hash fingerprint out-of-band, and the math confirms the signature"*.
+
+When you internalize the Physics of Trust, you stop looking for protection from firewalls, VPNs, and Terms of Service agreements. You realize that true security comes from the design of the protocol itself. You can stop trusting the cloud, and you start trusting the code - because you can verify it yourself.
+
+
+Merits Of Scarcity
+==================
+*Every Bit Counts*
+
+We have grown addicted to abundance. In the modern digital ecosystem, bandwidth is treated as an endless, flat ocean. We stream high-definition video without a thought, we ship entire libraries of code just to render a single button, and we measure performance in gigabits per second. This abundance has hollowed out our craft. When constraints vanish, efficiency dies, and with it, a certain kind of Clarity and Quality.
+
+Reticulum asks you to step out of the ocean and onto the tightrope.
+
+The Bandwidth Fallacy
+---------------------
+
+The Zen of Reticulum requires the realization that **5 bits per second is a valid speed**.
+
+To a modern developer, this sounds like paralysis. But there is a profound freedom in limits: When you have a gigabit connection, you can be incredibly sloppy. You can be wasteful. You can push your problems onto the infrastructure. *"It’s slow? Get a faster router"*.
+
+But on a high-latency, low-bandwidth link (be it a noisy HF radio channel or a tenuous LoRa hop) you cannot push problems anywhere. You must solve them. The network does not negotiate with waste.
+
+This forces a shift from consumption to interaction. You are no longer, then, consuming a service provided by a fat pipe; you are engaging in a careful negotiation with the physical medium. The medium becomes a partner in the conversation, not just a dumb conduit. You suddenly need to *understand the world to be in it*.
+
+Cost Of A Byte
+--------------
+
+In a scarce economy, a byte is not just data, but energy, time, and space.
+
+Every byte you transmit consumes battery life on a solar-powered node. It occupies valuable airtime that could have been used by another peer. It represents a measurable slice of the electromagnetic spectrum.
+
+When you internalize this, you begin to write code differently. You stop asking, "How much data can I send?" and start asking, "What is the *minimum* amount of information required to convey this intent? How can I best utilize my informational entropy?"
+
+This is where the elegance of Reticulum shines. The protocol is designed to strip away the non-essential. A link establishment takes three very small packets. A destination hash fits in 16 bytes. The overhead is vanishingly small, leaving almost the entire channel for the message itself.
+
+**Consider:**
+
+- **The Old Way:** *"I need to send a status update. I'll send a JSON object with metadata, timestamps, and user profile info (15KB)."*
+- **The Zen Way:** *"I need to send a status update. I'll send a single byte representing the state code. The context is already known."*
+
+This is of course optimization, but more importantly, *it is a form of respect*. Efficiency in a shared medium is an act of stewardship. By taking only what you need from the network, you leave room for others. The network listens to those who speak with purpose.
+
+Flow & Time
+-----------
+
+Scarcity also teaches us about time. We have become addicted to the *synchronous* now - the instant ping, the real-time stream. But Reticulum embraces *asynchronous* time.
+
+When links are intermittent and latency is measured in minutes or hours, "real-time" is an illusion. Reticulum doesn't encourage **Store and Forward** as a mere fallback, but as a primary mode of existence. You write a message, it propagates when it can, and it arrives when it arrives.
+
+This changes the psychological texture of communication. It removes the anxiety of the immediate response. It allows for contemplation. You are not demanding the recipient's attention *right now*; you are placing a gift in their path, to be found when they are ready.
+
+By designing for delay, you design for resilience. You are no longer building a house of cards that collapses when a single packet drops. You are building a stone arch that distributes the load *over time*.
+
+Liberation From Limits
+----------------------
+
+There is a strange optimism in scarcity. When you are forced to work within strict constraints, you are forced to prioritize. *You* must decide what truly matters. *That* is the real core of agency.
+
+In the infinite fantasy world of The Cloud, everything is urgent, so nothing is. In the economy of Reticulum, the cost of transmission forces you to weigh the value of your message. Do you really need to send that heart beat? Is that photo essential?
+
+When you strip away the noise, what remains is *signal*.
+
+This discipline creates a different kind of developer. It creates a craftsman who understands that the best code is the code you don't have to write. It creates a user who understands that the most powerful message is the one that is *understood*, not the one that is loudest. In the world of Reticulum, you are not a mere consumer of bandwidth; you are an architect of intent.
+
+
+Sovereignty Through Infrastructure
+==================================
+**Be Your Own Network**
+
+We live in an era of digital tenancy. We lease our connectivity from ISPs. We rent our storage from cloud providers. We even borrow our identity from social media platforms. We are tenants in a house we did not build, governed by rules we did not write, subject to eviction at the whim of a landlord who has never met us.
+
+The Zen of Reticulum is the realization that you *can* own the house.
+
+A Carrier-Grade Fallacy
+-----------------------
+
+For decades, we have been gaslit into believing that networking is really not just hard, but impossible. It is presented as a dark art reserved for telcos and billionaires, requiring millions of dollars of fiber optics, climate-controlled data centers, and armies of engineers. We are told that building reliable infrastructure is "too complex" for the individual or small organization.
+
+This is a big, fat lie.
+
+Physics is simple. A radio wave needs a transmitter and a receiver. A packet needs a path. The "complexity" of the modern internet is largely bureaucratic - a mountain of billing systems, regulatory capture, and legacy cruft designed to keep the gatekeepers in power.
+
+Reticulum strips away the bureaucracy. It runs on hardware that costs the price of a dinner. It runs on spectrum that is free to use. It demonstrates that a robust, planetary-scale network does not require a Fortune 500 company. It requires only the will to deploy, and the distributed, uncoordinated efforts of many individuals.
+
+Personal Infrastructure
+-----------------------
+
+This is where the rubber meets the road. You can read about Reticulum, you can understand the theory, but the insights only arrive when you plug in a radio and run a Transport Node. Suddenly, you are no longer a consumer. You're an operator.
+
+This shift is subtle but profound. When you run your own infrastructure, the network ceases to be a service that is provided *to* you. It becomes a space that you *inhabit*. You become responsible for the flow of information. You gain an intimate understanding of the medium - the way the weather affects the radio waves, the way the topology changes, the way the packets dance through the ether.
+
+There is a quiet competence that comes from this. You stop asking "Is the internet down?" and start asking "Is *my* links up?" You stop waiting for a technician and start checking the logs. This is a form of strength. To understand the system that carries your words is to be free from the mystery that keeps you dependent.
+
+The Ability To Disconnect
+-------------------------
+
+Why go to the trouble? Why buy the radio, write the config, and leave the Pi running in the corner?
+
+Because the old, centralized network is fragile. And because most of us doesn't even really want to be there anymore.
+
+The internet we rely on today is a chain of single points of failure. Cut the undersea cable, and a continent goes dark. Shut down the power grid, and the cloud evaporates. Deprioritize the "wrong" traffic, and the flow of information is strangled.
+
+Sovereignty is the ability to survive the cut, whether or not that cut was an accident or on purpose.
+
+When you build your own infrastructure, you build a lifeline. Reticulum is designed to function over media that the traditional internet cannot touch - bare wires, battery-powered radios, ad-hoc WiFi meshes. When the grid fails, or the censors arrive, or the bill goes unpaid, your Reticulum network continues to hum.
+
+This is not about "dropping out" of society. It is about building a substrate on which an actual *Society* can function.
+
+**Consider:**
+
+- **The Old Way:** "My connection is slow. I should call my ISP and complain."
+- **The Zen Way:** "The path is noisy. I will adjust the antenna or find a better route."
+
+By taking ownership of the infrastructure, you take ownership of your voice. You stop shouting into someone else's megaphone and start building your own. The network is no longer something that happens to you; it is something you make happen.
+
+
+Identity and Nomadism
+=====================
+**A Fluid Self**
+
+In the old world, you are defined by your coordinates. If you are at ``34.109.71.5``, you're *here*. If you unplug the cable and walk down the street, you vanish. Your digital self evaporates because it was tethered to the wall. You are a ghost in the endless machinations of gears, levers and transistors, bound to the hardware, and those that own it.
+
+This creates a subtle, constant anxiety. We are terrified of disconnecting because, in the architecture of the old web, disconnecting is a kind of death.
+
+The Zen of Reticulum offers a different way to be.
+
+Portable Existence
+------------------
+
+In Reticulum, your identity is not a location, or a username granted by a service. It is a cryptographic key - a complex, unique mathematical signature that exists independently of the physical world. You can carry it only in your mind, if you want to.
+
+Think of it less like a street address and more like a name. *A true name*.
+
+If you travel from Berlin to Tokyo, you do not change your name. You are still you. The people who know you can still recognize you. Reticulum applies this principle to the network layer. Your Destination Hash is **invariant**. It travels with you, stored securely on your device, *immutable as a stone*.
+
+This changes the relationship between you and the machine. You are not "logged into" the network via a specific gateway. You *are* the endpoint. The network does not connect to a place; *it converges on you*.
+
+Roaming Nodes
+-------------
+
+This freedom introduces a new concept of time and space: **Nomadism**.
+
+Because your identity is portable, your connectivity can be fluid. You can be sitting at a desk connected to a fiber backbone one moment, and walking through a field connected only to a long-range LoRa mesh the next. To the rest of the network, nothing has changed. Your friends do not need to update your contact info. The messages they send do not bounce back. The network senses the shift in the medium and reroutes the flow of data automatically.
+
+You are no longer a stationary node in a fixed grid. You are a wanderer in a fluid medium.
+
+The interfaces - whether it is WiFi, Ethernet, Packet Radio, or a physical wire - is merely the clothing your node wears. You change it to suit the environment. Underneath, you remain the same. This is the liberation of the protocol. It treats the physical medium as a transient circumstance, not a definition of self.
+
+**Consider:**
+
+- **The Old Way:** *"I lost connection. I have to reconnect to the VPN to tell them where I am now."*
+- **The Zen Way:** *"I moved. The network subtly bends to accomodate this new reality."*
+
+Announcing Presence
+-------------------
+
+How does the network find a wanderer? It listens.
+
+In the IP world, we query directories. We ask a server, "Where is Mark?" The server checks its database and gives us a coordinate. This means that someone, somewhere, is keeping track of you. It assumes and *requires* surveillance.
+
+Reticulum replaces surveillance with **Announces**.
+
+Instead of asking a central authority where you are, you simply state your presence. You broadcast a cryptographic proof: "I am here, and I am who I say I am". This ripples out through the mesh. Your neighbors hear it, update their path tables, and pass it on.
+
+This is a quiet, organic process. It is the digital equivalent of lighting lanterns in the dark. You do not need to chase the light; you let the light find you. It respects your autonomy. You choose when to announce, how often to speak, and to whom. You also choose when to disappear - for but a moment or perpetually.
+
+Anchor In The Flow
+------------------
+
+There is a deep peace in this nomadism. It teaches you that stability does not come from standing still. Stability comes from *internal coherence*.
+
+By holding your own private key, you hold your own center of gravity. The world around you; the infrastructure, the topography and the availability of links can all shift chaotically. Storms can knock out towers. Cables can be cut. The internet can go down.
+
+But as long as you possess your key, you possess your identity. The entire infrastructure can be destroyed and rebuilt, and you are still you. Nothing lasts, yet nothing is lost.
+
+You become a sovereign entity moving through the noise, connected not by the rigidity of cables, but by the fluidity of recognition. The network becomes a place you inhabit, rather than a utility you subscribe to: You are at home in the ether.
+
+
+Ethics Of The Tool
+==================
+**Technology With Conscience**
+
+You have unlearned the center. You have accepted the physics of trust. You have embraced the economy of scarcity and the freedom of unbound nomadism. You are standing in a new space. Now, look at the tool in your hand.
+
+In the old world, we were taught that technology is neutral. We are told that "guns don't kill people, people do", or that a component is just a component, indifferent to what its combinatorial potential is. This is a convenient lie. It serves only to allow the builders to wash their hands of responsibility.
+
+But we know better now. We know that **architecture is politics**, and *politics is control*. The way you build a system determines how it will be used. If you build a system optimized for mass surveillance, you *will* get a panopticon. If you build a system optimized for centralized control, you *will* get a dictatorship. If you build a system optimized for extraction, you *will* get a parasite.
+
+The Zen of Reticulum asserts that a tool is never neutral.
+
+On the very contrary: A tool is intent, **crystallized**.
+
+The Harm Principle
+------------------
+
+Why does the Reticulum License forbid the software from being used in systems designed to harm humans? Is it not just a restriction on freedom?
+
+It is a restriction on *license*, yes, but it is an expansion of *freedom*.
+
+Building powerful tools without a moral compass is in no way virtuous or commendable, it is plain and simple irresponsibility.
+
+A tool that can easily be used to oppress is a real danger to the user. If you build a network that can be turned against you by a tyrant, you are not free. You are merely waiting for the leash to tighten. By encoding the "Harm Principle" into the legal DNA of the reference implementation, we are building a safeguard. We are stating, clearly and immutably, that *this tool* is for **life**, not for death.
+
+This aligns the software with the interests of humanity. It cements that the network cannot be conscripted into a kill-system, a weaponized drone controller, or a torture device without breaking the license and the law. It is a line drawn in the sand - not by a government or external authority, but by the creators of the tool itself.
+
+**Consider:**
+
+- **The Old Way:** *"It's just software. How people use it is not my problem."*
+- **The Zen Way:** *"This software is a habitat. I will not allow it to be used to build a cage."*
+
+It is *your* choice whether to align with this - we are not forcing this stance on anyone. If you choose to align with life over death, with creativity over destruction, we grant you an immensely powerful tool, to own and build with as you please. If you do not, we deny it.
+
+If you do not like this, we most assuredly do not need you here, and you are on your own.
+
+Public Domain Protocol
+----------------------
+
+This leads to a vital distinction: The difference between the *idea* and the *implementation*.
+
+The protocol - the mathematical rules of how Reticulum works - is dedicated to the Public Domain. It belongs to humanity. **No one can own it**. Anyone can implement it, improve it, or adapt it. This is the core idea of free communication, which itself must be forever free.
+
+But the functional, deployed *reference implementation* - the Python code, the maintenance, the years of labor - has a conscience. This distinction is the engine of sustainability. It allows the protocol to be universal, while ensuring that the specific labor of the builders is not hijacked to undermine the foundational intent of the project itself. From this document, it should be very clear what this intent is.
+
+If you want to build a system with Reticulum that manipulates and damages users for profits or targets missiles, you can use the public domain protocol, and start from scratch. But you cannot take our work. You must do your own. This serves as a pillar of accountability. If you want to build a weapon, *you* go and forge the steel yourself, while the world observes. And when the blood is drawn - it is on **your** hands.
+
+Preserving Human Agency
+-----------------------
+
+We live in an era of predatory extraction. The open-source commons is being scraped, ingested, and regurgitated by machine learning algorithms, whose corporate owners seek to replace the very humans who built those commons. Our code, our words, and our creativity is being used to train systems that are specifically designed to make us obsolete, without offering anything else in return than serfdom and leashes.
+
+Reticulum stands against this.
+
+The license protects the software from being used to feed the beast. It draws a hard line: This tool is for *people*. It is for human-to-human connection. It is not a dataset to be strip-mined for the purpose of building a synthetic overlord, puppeteered by a miniscule conglomerate of controllers.
+
+This is a radical act of preservation. By protecting the code from AI appropriation, we are protecting space for human agency. We are ensuring that there remains a digital realm where the actors are flesh, blood and soul, where decisions are made by minds, not overlords hiding behind models.
+
+When you use Reticulum, you are using a tool that respects you. It does not see you as a product to be tracked. It does not see your data as fuel for an algorithm. It sees you as a sovereign, equal peer.
+
+This changes the foundational premise of using the technology. It restores dignity to the interaction. You are not the user of a service; you are a participant in a mutual covenant. The tool aligns with your autonomy, rather than eroding it.
+
+In this way, ethics is not a restriction, but a foundation. It is the foundation that helps ensure the network will still belong to you tomorrow.
+
+
+Design Patterns For Post-IP Systems
+===================================
+**Practical Philosophy for Developers**
+
+The philosophy is useless if it cannot be hammered into code. The metaphors we have explored - nomadism, scarcity, trust - are not just poetry, but real-world engineering constraints. When you sit down to write software for Reticulum, these concepts must shape the very structure of your application.
+
+We are now moving from the *why* to the *how*. This is where the abstract becomes concrete, and where you will see the true depth of the patterns we have been weaving.
+
+Store & Forward
+---------------
+
+The web has trained us to be impatient. We write synchronous code. We fire a request and we wait, blocking the UI, holding our breath. If the response doesn't come in 250 milliseconds, we show a spinner. If it doesn't come in five seconds, we show an error. We treat network connectivity as a binary state: either we are "online" or we are "broken".
+
+This is brittle. It is a rejection of reality.
+
+In Reticulum, connectivity is a spectrum, and presence is asynchronous. If at all applicable to your intent, you must design your applications to embrace **Store & Forward**.
+
+Instead of demanding an immediate answer, your application should act as a patient participant. You create a message for someone or something in the mesh. The network holds it. It carries it from node to node, perhaps over hours or days, waiting for the recipient to appear. When they finally surface, the message is delivered. This requires a shift from "request/response" to "event/handler". How exactly you do this is a challenge for you to solve intelligently within your problem domain, but Reticulum-based systems already exist that does this extremely well, and you can use them for inspiration.
+
+**Consider:**
+
+- **The Old Way:** ``Connect() -> Send() -> Wait() -> Crash if timeout.``
+- **The Zen Way:** ``Send() -> Continue living. -> Receive() when it arrives.``
+
+This changes the user experience profoundly. It removes the anxiety of the loading bar. It creates a sense of continuity. The user is not "waiting for the network"; they are interacting with a persistent log of communication that lives in the network itself.
+
+Naming Is Power
+---------------
+
+In the IP world, we are slaves to the Domain Name System. We rely on a hierarchy of registrars to map human-readable names to machine-readable addresses. This hierarchy is a choke point. If the registrar revokes your domain, or if the DNS server goes down, you vanish.
+
+Reticulum dissolves this hierarchy with **Hash-based Identity**.
+
+In this design pattern, a name is not a string you look up; it is a cryptographic destination you verify. When you design for Reticulum, you stop asking the user for a URL and start asking for a Destination or Identity Hash.
+
+This feels strange at first. A hash like ``<83b7328926fed0d2e6a10a7671f9e237>`` looks alien compared to ``myfriend.com``. But that alienness is the armor. It **cannot** be spoofed. It **cannot** be censored by a registrar. It is **absolute**.
+
+Designing for this means shifting your UI metaphors. You are no longer browsing a web of pages; you are managing a ledger of keys. You are building an "Address Book" that is actually a keyring. The names are given by the user, and the power stays with them. That hashes look complex is directly analogous to the strengths of the bonds formed by their use. It forces the user to engage in a moment of verification, an out-of-band handshake, which restores the human element of trust that SSL certificates stripped away.
+
+The Interface Is The Medium
+---------------------------
+
+One of the most liberating patterns in Reticulum is **Transport Agnosticism**.
+
+In traditional networking, your code is often littered with transport logic. "Am I on WiFi? Check bandwidth. Am I on Cellular? Check data plan. Am I on Ethernet?". You are constantly micromanaging the pipe.
+
+In Reticulum, you write to the API, and the API writes to the medium. You send a packet to a Destination. You do not care if that packet travels over a TCP tunnel, a LoRa radio wave, or a serial wire interface. That is the stack's concern.
+
+This allows you to write **Universal Applications**.
+Imagine a messaging app. You write it once. It works on a laptop connected to fiber. It works on a phone in the city using WiFi. And, without a single line of code changed, it works on a device in the wilderness, talking only to other devices via radio.
+
+The pattern is simple: **Never code to the hardware. Code to the intent.**
+
+**Consider:**
+
+- **The Old Way:** ``socket.connect(ip, port)``, and then a whole lot more
+- **The Zen Way:** ``RNS.Packet(destination, data).send()``
+
+By abstracting the medium, you make your software immortal to changes in infrastructure. The user might switch from a 4G hotspot to a HF modem tomorrow. Your software doesn't need to know. It simply continues the conversation.
+
+Emergent Patterns
+-----------------
+
+When you combine these patterns - *Store & Forward*, *Hash-based Identity*, and *Transport Agnosticism* - you create software that feels fundamentally different.
+
+It feels *grounded*. It doesn't flicker when the signal drops. It doesn't panic when the server is down. It has weight. It has persistence. It has *relevance*.
+
+You are no longer building a "client" that begs a "server" for attention. You are building an autonomous agent that exists within the mesh. It speaks when it needs to, listens when it can, and carries its identity with it wherever it goes.
+
+This is the culmination of the Zen. The code is not just a set of instructions: It is a behavioral envelope. It is a way of *being* in the network.
+
+
+Fabric Of The Independent
+=========================
+
+We have stripped away the illusions. We have seen that the center is empty, that trust *must* be hard, that resources are finite, and that we must own our infrastructure. We have seen that tools have ethics and that our identity can move fluidly.
+
+This is a reclaiming of the commons. For too long, we have allowed the most vital substrate of human society - *our ability to speak to one another* - to be colonized by entities that do not share our interests. We have allowed the architecture of our communication to be designed by accountants rather than architects.
+
+We are taking it back. Not by petitioning the masters, but by building the new world within, over, under and around the shell of the old.
+
+The Work Is Finished
+--------------------
+
+The heavy lifting is done.
+
+The protocol is in the public domain, a gift to humanity that can never be taken away. The software is written, tested, and running on devices scattered across the globe. The manual lies open before you. The source code for the reference implementation is now distributed on hundreds of thousands of devices across the planet. No one can delete or destroy it. The hardware is accessible and abundant.
+
+It was a hard road to get here, but we got here. Now, there is no roadmap committee waiting for approval. There is no venture capital dictating the user experience. There is no CEO to sign off on the next feature release.
+
+There is only you.
+
+The barrier to entry is no longer complexity: It is the mere habit of dependency. You were conditioned to wait. Wait for the app update. Wait for the ISP to fix the line. Wait for the platform to allow the post. Wait for the government to change the policies. Wait for the likes. Wait for the revolution to be televised.
+
+The revolution never was televised.
+
+It is packetized.
+
+Open Sky
+--------
+
+The future of this technology is a construction project.
+
+It looks like a single node on a windowsill, listening to the static. It looks like a message sent to a neighbor, bypassing the noise of the commercial web. It looks like a community mesh that grows, link by link, hop by hop, carried by hands that care more about connection than profit.
+
+You have the blueprints. You have the tools. You have the philosophy. The noise of the old world has fallen away, leaving you with the quiet clarity of the open spectrum.
+
+*Mark, early 2026*

docs/manual/_static/documentation_options.js

@@ -1,5 +1,5 @@
 const DOCUMENTATION_OPTIONS = {
-    VERSION: '1.0.3',
+    VERSION: '1.2.3',
     LANGUAGE: 'en',
     COLLAPSE_INDEX: false,
     BUILDER: 'html',

docs/manual/examples.html

@@ -3,11 +3,11 @@
   <head><meta charset="utf-8">
     <meta name="viewport" content="width=device-width,initial-scale=1">
     <meta name="color-scheme" content="light dark"><meta name="viewport" content="width=device-width, initial-scale=1" />
-<link rel="index" title="Index" href="genindex.html"><link rel="search" title="Search" href="search.html"><link rel="next" title="API Reference" href="reference.html"><link rel="prev" title="Support Reticulum" href="support.html">
+<link rel="index" title="Index" href="genindex.html"><link rel="search" title="Search" href="search.html"><link rel="next" title="Reticulum License" href="license.html"><link rel="prev" title="Support Reticulum" href="support.html">
         <link rel="prefetch" href="_static/rns_logo_512.png" as="image">
 
     <!-- Generated with Sphinx 8.2.3 and Furo 2025.09.25.dev1 -->
-        <title>Code Examples - Reticulum Network Stack 1.0.3 documentation</title>
+        <title>Code Examples - Reticulum Network Stack 1.2.3 documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d111a655" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=580074bf" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
@@ -180,7 +180,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 1.0.3 documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 1.2.3 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -204,7 +204,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 1.0.3 documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 1.2.3 documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@@ -215,13 +215,17 @@
   <ul class="current">
 <li class="toctree-l1"><a class="reference internal" href="whatis.html">What is Reticulum?</a></li>
 <li class="toctree-l1"><a class="reference internal" href="gettingstartedfast.html">Getting Started Fast</a></li>
+<li class="toctree-l1"><a class="reference internal" href="zen.html">Zen of Reticulum</a></li>
+<li class="toctree-l1"><a class="reference internal" href="software.html">Programs Using Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
 <li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
 <li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks</a></li>
+<li class="toctree-l1"><a class="reference internal" href="git.html">Git Over Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a></li>
 <li class="toctree-l1 current current-page"><a class="current reference internal" href="#">Code Examples</a></li>
+<li class="toctree-l1"><a class="reference internal" href="license.html">Reticulum License</a></li>
 </ul>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="reference.html">API Reference</a></li>
@@ -3588,12 +3592,12 @@ will be fully on-par with natively included interfaces, including all supported
       <footer>
         
         <div class="related-pages">
-          <a class="next-page" href="reference.html">
+          <a class="next-page" href="license.html">
               <div class="page-info">
                 <div class="context">
                   <span>Next</span>
                 </div>
-                <div class="title">API Reference</div>
+                <div class="title">Reticulum License</div>
               </div>
               <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
             </a>
@@ -3660,7 +3664,7 @@ will be fully on-par with natively included interfaces, including all supported
       
     </aside>
   </div>
-</div><script src="_static/documentation_options.js?v=baaebd52"></script>
+</div><script src="_static/documentation_options.js?v=590429e0"></script>
     <script src="_static/doctools.js?v=9bcbadda"></script>
     <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="_static/scripts/furo.js?v=46bd48cc"></script>

docs/manual/forhumans.html

@@ -7,7 +7,7 @@
         <link rel="prefetch" href="_static/rns_logo_512.png" as="image">
 
     <!-- Generated with Sphinx 8.2.3 and Furo 2025.09.25.dev1 -->
-        <title>An Explanation of Reticulum for Human Beings - Reticulum Network Stack 1.0.3 documentation</title>
+        <title>An Explanation of Reticulum for Human Beings - Reticulum Network Stack 1.2.3 documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d111a655" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=580074bf" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
@@ -180,7 +180,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 1.0.3 documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 1.2.3 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -204,7 +204,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 1.0.3 documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 1.2.3 documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@@ -215,13 +215,17 @@
   <ul>
 <li class="toctree-l1"><a class="reference internal" href="whatis.html">What is Reticulum?</a></li>
 <li class="toctree-l1"><a class="reference internal" href="gettingstartedfast.html">Getting Started Fast</a></li>
+<li class="toctree-l1"><a class="reference internal" href="zen.html">Zen of Reticulum</a></li>
+<li class="toctree-l1"><a class="reference internal" href="software.html">Programs Using Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
 <li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
 <li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks</a></li>
+<li class="toctree-l1"><a class="reference internal" href="git.html">Git Over Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a></li>
+<li class="toctree-l1"><a class="reference internal" href="license.html">Reticulum License</a></li>
 </ul>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="reference.html">API Reference</a></li>
@@ -291,7 +295,7 @@
       
     </aside>
   </div>
-</div><script src="_static/documentation_options.js?v=baaebd52"></script>
+</div><script src="_static/documentation_options.js?v=590429e0"></script>
     <script src="_static/doctools.js?v=9bcbadda"></script>
     <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="_static/scripts/furo.js?v=46bd48cc"></script>

docs/manual/genindex.html

@@ -5,7 +5,7 @@
     <meta name="color-scheme" content="light dark"><link rel="index" title="Index" href="#"><link rel="search" title="Search" href="search.html">
         <link rel="prefetch" href="_static/rns_logo_512.png" as="image">
 
-    <!-- Generated with Sphinx 8.2.3 and Furo 2025.09.25.dev1 --><title>Index - Reticulum Network Stack 1.0.3 documentation</title>
+    <!-- Generated with Sphinx 8.2.3 and Furo 2025.09.25.dev1 --><title>Index - Reticulum Network Stack 1.2.3 documentation</title>
 <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d111a655" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=580074bf" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
@@ -178,7 +178,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 1.0.3 documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 1.2.3 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -202,7 +202,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 1.0.3 documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 1.2.3 documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@@ -213,13 +213,17 @@
   <ul>
 <li class="toctree-l1"><a class="reference internal" href="whatis.html">What is Reticulum?</a></li>
 <li class="toctree-l1"><a class="reference internal" href="gettingstartedfast.html">Getting Started Fast</a></li>
+<li class="toctree-l1"><a class="reference internal" href="zen.html">Zen of Reticulum</a></li>
+<li class="toctree-l1"><a class="reference internal" href="software.html">Programs Using Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
 <li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
 <li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks</a></li>
+<li class="toctree-l1"><a class="reference internal" href="git.html">Git Over Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a></li>
+<li class="toctree-l1"><a class="reference internal" href="license.html">Reticulum License</a></li>
 </ul>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="reference.html">API Reference</a></li>
@@ -284,15 +288,17 @@
 </li>
         <li><a href="reference.html#RNS.RawChannelReader.add_ready_callback">add_ready_callback() (RNS.RawChannelReader method)</a>
 </li>
-    </ul></td>
-    <td style="width: 33%; vertical-align: top;"><ul>
         <li><a href="reference.html#RNS.Resource.advertise">advertise() (RNS.Resource method)</a>
 </li>
+    </ul></td>
+    <td style="width: 33%; vertical-align: top;"><ul>
         <li><a href="reference.html#RNS.Destination.announce">announce() (RNS.Destination method)</a>
 </li>
         <li><a href="reference.html#RNS.Reticulum.ANNOUNCE_CAP">ANNOUNCE_CAP (RNS.Reticulum attribute)</a>
 </li>
         <li><a href="reference.html#RNS.Destination.app_and_aspects_from_name">app_and_aspects_from_name() (RNS.Destination static method)</a>
+</li>
+        <li><a href="reference.html#RNS.Transport.await_path">await_path() (RNS.Transport static method)</a>
 </li>
     </ul></td>
   </tr></table>
@@ -301,6 +307,10 @@
 <section id="B" class="genindex-section">
   <h2>B</h2>
   <table style="width: 100%" class="indextable genindextable"><tr>
+    <td style="width: 33%; vertical-align: top;"><ul>
+        <li><a href="reference.html#RNS.Reticulum.blackhole_sources">blackhole_sources() (RNS.Reticulum static method)</a>
+</li>
+    </ul></td>
     <td style="width: 33%; vertical-align: top;"><ul>
         <li><a href="reference.html#RNS.Buffer">Buffer (class in RNS)</a>
 </li>
@@ -352,13 +362,15 @@
           <li><a href="reference.html#RNS.Identity.decrypt">(RNS.Identity method)</a>
 </li>
         </ul></li>
-    </ul></td>
-    <td style="width: 33%; vertical-align: top;"><ul>
         <li><a href="reference.html#RNS.Transport.deregister_announce_handler">deregister_announce_handler() (RNS.Transport static method)</a>
 </li>
+    </ul></td>
+    <td style="width: 33%; vertical-align: top;"><ul>
         <li><a href="reference.html#RNS.Destination.deregister_request_handler">deregister_request_handler() (RNS.Destination method)</a>
 </li>
         <li><a href="reference.html#RNS.Destination">Destination (class in RNS)</a>
+</li>
+        <li><a href="reference.html#RNS.Reticulum.discovered_interfaces">discovered_interfaces() (RNS.Reticulum static method)</a>
 </li>
     </ul></td>
   </tr></table>
@@ -517,10 +529,12 @@
         <li><a href="reference.html#RNS.Link.identify">identify() (RNS.Link method)</a>
 </li>
         <li><a href="reference.html#RNS.Identity">Identity (class in RNS)</a>
+</li>
+        <li><a href="reference.html#RNS.Link.inactive_for">inactive_for() (RNS.Link method)</a>
 </li>
     </ul></td>
     <td style="width: 33%; vertical-align: top;"><ul>
-        <li><a href="reference.html#RNS.Link.inactive_for">inactive_for() (RNS.Link method)</a>
+        <li><a href="reference.html#RNS.Reticulum.interface_discovery_sources">interface_discovery_sources() (RNS.Reticulum static method)</a>
 </li>
         <li><a href="reference.html#RNS.Resource.is_compressed">is_compressed() (RNS.Resource method)</a>
 </li>
@@ -618,13 +632,15 @@
 </li>
         <li><a href="reference.html#RNS.Packet">Packet (class in RNS)</a>
 </li>
-    </ul></td>
-    <td style="width: 33%; vertical-align: top;"><ul>
         <li><a href="reference.html#RNS.PacketReceipt">PacketReceipt (class in RNS)</a>
 </li>
+    </ul></td>
+    <td style="width: 33%; vertical-align: top;"><ul>
         <li><a href="reference.html#RNS.Transport.PATHFINDER_M">PATHFINDER_M (RNS.Transport attribute)</a>
 </li>
         <li><a href="reference.html#RNS.Packet.PLAIN_MDU">PLAIN_MDU (RNS.Packet attribute)</a>
+</li>
+        <li><a href="reference.html#RNS.Reticulum.publish_blackhole_enabled">publish_blackhole_enabled() (RNS.Reticulum static method)</a>
 </li>
     </ul></td>
   </tr></table>
@@ -669,6 +685,8 @@
         <li><a href="reference.html#RNS.Transport.request_path">request_path() (RNS.Transport static method)</a>
 </li>
         <li><a href="reference.html#RNS.RequestReceipt">RequestReceipt (class in RNS)</a>
+</li>
+        <li><a href="reference.html#RNS.Reticulum.required_discovery_value">required_discovery_value() (RNS.Reticulum static method)</a>
 </li>
         <li><a href="reference.html#RNS.Packet.resend">resend() (RNS.Packet method)</a>
 </li>
@@ -819,7 +837,7 @@
       
     </aside>
   </div>
-</div><script src="_static/documentation_options.js?v=baaebd52"></script>
+</div><script src="_static/documentation_options.js?v=590429e0"></script>
     <script src="_static/doctools.js?v=9bcbadda"></script>
     <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="_static/scripts/furo.js?v=46bd48cc"></script>

docs/manual/gettingstartedfast.html

@@ -3,11 +3,11 @@
   <head><meta charset="utf-8">
     <meta name="viewport" content="width=device-width,initial-scale=1">
     <meta name="color-scheme" content="light dark"><meta name="viewport" content="width=device-width, initial-scale=1" />
-<link rel="index" title="Index" href="genindex.html"><link rel="search" title="Search" href="search.html"><link rel="next" title="Using Reticulum on Your System" href="using.html"><link rel="prev" title="What is Reticulum?" href="whatis.html">
+<link rel="index" title="Index" href="genindex.html"><link rel="search" title="Search" href="search.html"><link rel="next" title="Zen of Reticulum" href="zen.html"><link rel="prev" title="What is Reticulum?" href="whatis.html">
         <link rel="prefetch" href="_static/rns_logo_512.png" as="image">
 
     <!-- Generated with Sphinx 8.2.3 and Furo 2025.09.25.dev1 -->
-        <title>Getting Started Fast - Reticulum Network Stack 1.0.3 documentation</title>
+        <title>Getting Started Fast - Reticulum Network Stack 1.2.3 documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d111a655" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=580074bf" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
@@ -180,7 +180,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 1.0.3 documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 1.2.3 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -204,7 +204,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 1.0.3 documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 1.2.3 documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@@ -215,13 +215,17 @@
   <ul class="current">
 <li class="toctree-l1"><a class="reference internal" href="whatis.html">What is Reticulum?</a></li>
 <li class="toctree-l1 current current-page"><a class="current reference internal" href="#">Getting Started Fast</a></li>
+<li class="toctree-l1"><a class="reference internal" href="zen.html">Zen of Reticulum</a></li>
+<li class="toctree-l1"><a class="reference internal" href="software.html">Programs Using Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
 <li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
 <li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks</a></li>
+<li class="toctree-l1"><a class="reference internal" href="git.html">Git Over Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a></li>
+<li class="toctree-l1"><a class="reference internal" href="license.html">Reticulum License</a></li>
 </ul>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="reference.html">API Reference</a></li>
@@ -274,7 +278,7 @@ of your system with a command like <code class="docutils literal notranslate"><s
 <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.0.2-py3-none-any.whl
+<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
@@ -310,75 +314,9 @@ compiled packages available.</p>
 </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 few different
-programs exist that allow basic communication and a range of other useful functions,
+<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>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 over fast
-links, such as local WiFi, wired Ethernet, the Internet, or any combination.</p>
-<p>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.</p>
-<section id="remote-shell">
-<h3>Remote Shell<a class="headerlink" href="#remote-shell" title="Link to this heading">¶</a></h3>
-<p>The <a class="reference external" href="https://github.com/acehoss/rnsh">rnsh</a> program lets you establish fully interactive
-remote shell sessions over Reticulum. It also allows you to pipe any program to or from a
-remote system, and is similar to how <code class="docutils literal notranslate"><span class="pre">ssh</span></code> works. The <code class="docutils literal notranslate"><span class="pre">rnsh</span></code> is very efficient, and
-can facilitate fully interactive shell sessions, even over extremely low-bandwidth links,
-such as LoRa or packet radio.</p>
-</section>
-<section id="nomad-network">
-<h3>Nomad Network<a class="headerlink" href="#nomad-network" title="Link to this heading">¶</a></h3>
-<p>The terminal-based program <a class="reference external" href="https://github.com/markqvist/nomadnet">Nomad Network</a>
-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.</p>
-<a class="reference external image-reference" href="_images/nomadnet_3.png"><img alt="_images/nomadnet_3.png" src="_images/nomadnet_3.png" />
-</a>
-<p><a class="reference external" href="https://github.com/markqvist/nomadnet">Nomad Network</a> is a user-facing client
-for the messaging and information-sharing protocol
-<a class="reference external" href="https://github.com/markqvist/lxmf">LXMF</a>, another project built with Reticulum.</p>
-<p>You can install Nomad Network via pip:</p>
-<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install ...</span>
-<span class="n">pip</span> <span class="n">install</span> <span class="n">nomadnet</span>
-
-<span class="c1"># ... and run</span>
-<span class="n">nomadnet</span>
-</pre></div>
-</div>
-<div class="admonition note">
-<p class="admonition-title">Note</p>
-<p>If this is the very first time you use <code class="docutils literal notranslate"><span class="pre">pip</span></code> 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. In some cases, you may even need to
-manually add the <code class="docutils literal notranslate"><span class="pre">pip</span></code> install path to your <code class="docutils literal notranslate"><span class="pre">PATH</span></code> environment variable.</p>
-</div>
-</section>
-<section id="sideband">
-<h3>Sideband<a class="headerlink" href="#sideband" title="Link to this heading">¶</a></h3>
-<p>If you would rather use a program with a graphical user interface, you can take
-a look at <a class="reference external" href="https://unsigned.io/sideband">Sideband</a>, which is available for Android,
-Linux, macOS and Windows.</p>
-<a class="reference external image-reference" href="_images/sideband_devices.webp"><img alt="_images/sideband_devices.webp" class="align-center" src="_images/sideband_devices.webp" />
-</a>
-<p>Sideband allows you to communicate with other people or LXMF-compatible
-systems over Reticulum networks using LoRa, Packet Radio, WiFi, I2P, Encrypted QR
-Paper Messages, or anything else Reticulum supports. It also interoperates with
-the Nomad Network program.</p>
-</section>
-<section id="meshchat">
-<h3>MeshChat<a class="headerlink" href="#meshchat" title="Link to this heading">¶</a></h3>
-<p>The <a class="reference external" href="https://github.com/liamcottle/reticulum-meshchat">Reticulum MeshChat</a> application
-is a user-friendly LXMF client for Linux, macOS and Windows, that also includes a Nomad Network
-page browser and other interesting functionality.</p>
-<a class="reference external image-reference" href="_images/meshchat_1.webp"><img alt="_images/meshchat_1.webp" class="align-center" src="_images/meshchat_1.webp" />
-</a>
-<p>Reticulum MeshChat is of course also compatible with Sideband and Nomad Network, or
-any other LXMF client.</p>
-</section>
 </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>
@@ -418,81 +356,77 @@ other device on your local WiFi will then be able to connect to this wider Retic
 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.</p>
+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="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 many hundreds 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>
-</section>
-<section id="connect-to-the-public-testnet">
-<h2>Connect to the Public Testnet<a class="headerlink" href="#connect-to-the-public-testnet" title="Link to this heading">¶</a></h2>
-<p>An experimental public testnet has been made accessible by volunteers in the community. You
-can find interface definitions for adding to your <code class="docutils literal notranslate"><span class="pre">.reticulum/config</span></code> file on the
-<a class="reference external" href="https://reticulum.network/connect.html">Reticulum Website</a> or the
-<a class="reference external" href="https://github.com/markqvist/Reticulum/wiki/Community-Node-List">Community Wiki</a></p>
-<p>You can connect your devices or instances to one or more of these to gain access to any
-Reticulum networks they are physically connected to. Simply add one or more interface
-snippets to your config file in the <code class="docutils literal notranslate"><span class="pre">[interface]</span></code> section, like in the example below:</p>
-<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="c1"># TCP/IP interface to the BetweenTheBorders Hub (community-provided)</span>
-<span class="k">[[RNS Testnet BetweenTheBorders]]</span>
-<span class="w">  </span><span class="na">type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">TCPClientInterface</span>
-<span class="w">  </span><span class="na">enabled</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span>
-<span class="w">  </span><span class="na">target_host</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">reticulum.betweentheborders.com</span>
-<span class="w">  </span><span class="na">target_port</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">4242</span>
-</pre></div>
+<section id="bootstrapping-connectivity">
+<span id="id1"></span><h2>Bootstrapping Connectivity<a class="headerlink" href="#bootstrapping-connectivity" title="Link to this heading">¶</a></h2>
+<p>Reticulum is not a service you subscribe to, nor is it a single global network you “join”. It is a <em>networking stack</em>; a toolkit for building communications systems that align with your specific values, requirements, and operational environment. The way you choose to connect to other Reticulum peers is entirely your own choice.</p>
+<p>One of the most powerful aspects of Reticulum is that it provides a multitude of tools to establish, maintain, and optimize connectivity. You can use these tools in isolation or combine them in complex configurations to achieve a vast array of goals.</p>
+<p>Whether your aim is to create a completely private, air-gapped network for your family; to build a resilient community mesh that survives infrastructure collapse; to connect far and wide to as many nodes as possible; or simply to maintain a reliable, encrypted link to a specific organization you care about, Reticulum provides the mechanisms to make it happen.</p>
+<p>There is no “right” or “wrong” way to build a Reticulum network, and you don’t need to be a network engineer just to get started. If the information flows in the way you intend, and your privacy and security requirements are met, your configuration is a success. Reticulum is designed to make the most challenging and difficult scenarios attainable, even when other networking technologies fail.</p>
+<section id="finding-your-way">
+<h3>Finding Your Way<a class="headerlink" href="#finding-your-way" title="Link to this heading">¶</a></h3>
+<p>When you first start using Reticulum, you need a way to obtain connectivity with the peers you want to communicate with - the process of <em>bootstrapping connectivity</em>.</p>
+<div class="admonition important">
+<p class="admonition-title">Important</p>
+<p>A common mistake in modern networking is the reliance on a few centralized, hard-coded entrypoints. If every user simply connects to the same list of public IP addresses found on a website, the network becomes brittle, centralized, and ultimately fails to deliver on the promise of decentralization and resilience. You have a responsibility here.</p>
 </div>
+<p>Reticulum encourages the approach of <em>organic growth</em>. Instead of relying on permanent static connections to distant servers, you can use temporary bootstrap connections to continously <em>discover</em> more relevant or local infrastructure. Once discovered, your system can automatically form stronger, more direct links to these peers, and discard the temporary bootstrap links. This results in a web of connections that are geographically relevant, resilient and efficient.</p>
+<p>It <em>is</em> possible to simply add a few public entrypoints to the <code class="docutils literal notranslate"><span class="pre">[interfaces]</span></code> section of your Reticulum configuration and be connected, but a better option is to enable <a class="reference internal" href="using.html#using-interface-discovery"><span class="std std-ref">interface discovery</span></a> and either manually select relevant, local interfaces, or enable discovered interface auto-connection.</p>
+<p>A relevant option in this context is the <a class="reference internal" href="interfaces.html#interfaces-options"><span class="std std-ref">bootstrap only</span></a> interface option. This is an automated tool for better distributing connectivity. By enabling interface discovery and auto-connection, and marking an interface as <code class="docutils literal notranslate"><span class="pre">bootstrap_only</span></code>, you tell Reticulum to use that interface primarliy to find connectivity options, and then disconnect it once sufficient entrypoints have been discovered. This helps create a network topology that favors locality and resilience over the simple centralization caused by using only a few static entrypoints.</p>
+<p>Good places to find interface definitions for bootstrapping connectivity are websites like
+<a class="reference external" href="https://directory.rns.recipes/">directory.rns.recipes</a> and <a class="reference external" href="https://rmap.world/">rmap.world</a>.</p>
+</section>
+<section id="build-personal-infrastructure">
+<h3>Build Personal Infrastructure<a class="headerlink" href="#build-personal-infrastructure" title="Link to this heading">¶</a></h3>
+<p>You do not need a datacenter to be a meaningful part of the Reticulum ecosystem. In fact, the most important nodes in the network are often the smallest ones.</p>
+<p>We strongly encourage everyone, even home users, to think in terms of building <strong>personal infrastructure</strong>. Don’t connect every phone, tablet, and computer in your house directly to a public internet gateway. Instead, repurpose an old computer, a Raspberry Pi, or a supported router to act as your own, personal <strong>Transport Node</strong>:</p>
+<ul class="simple">
+<li><p>Your local Transport Node sits in your home, connected to your WiFi and perhaps a radio interface (like an RNode).</p></li>
+<li><p>You configure this node with a <code class="docutils literal notranslate"><span class="pre">bootstrap_only</span></code> interface (perhaps a TCP tunnel to a wider network) and enable interface discovery.</p></li>
+<li><p>While you sleep, work, or cook, your node listens to the network. It discovers other local community members, validates their Network Identities, and automatically establishes direct links.</p></li>
+<li><p>Your personal devices now connect to your <em>local</em> node, which is integrated into a living, breathing local mesh. Your traffic flows through local paths provided by other real people in the community rather than bouncing off a distant server.</p></li>
+</ul>
+<p><strong>Don’t wait for others to build the networks you want to see</strong>. Every network is important, perhaps even most so those that support individual families and persons. Once enough of this personal, local infrastructure exist, connecting them directly to each other, without traversing the public Internet, becomes inevitable.</p>
+</section>
+<section id="mixing-strategies">
+<h3>Mixing Strategies<a class="headerlink" href="#mixing-strategies" title="Link to this heading">¶</a></h3>
+<p>There is no requirement to commit to a single strategy. The most robust setups often mix static, dynamic, and discovered interfaces.</p>
+<ul class="simple">
+<li><p><strong>Static Interfaces:</strong> You maintain a permanent interface to a trusted friend or organization using a static configuration.</p></li>
+<li><p><strong>Bootstrap Links:</strong> You connect a <code class="docutils literal notranslate"><span class="pre">bootstrap_only</span></code> interface to a public gateway on the Internet to scan for new connectable peers or to regain connectivity if your other interfaces fail.</p></li>
+<li><p><strong>Local Wide-Area Connectivity:</strong> You run a <code class="docutils literal notranslate"><span class="pre">RNodeInterface</span></code> on a shared frequency, giving you completely self-sovereign and private wide-area access to both your own network and other Reticulum peers globally, without any “service providers” being able to control or monitor how you interact with people.</p></li>
+</ul>
+<p>By combining these methods, you create a system that is secure against single points of failure, adaptable to changing network conditions, and better integrated into your physical and social reality.</p>
+</section>
+<section id="network-health-responsibility">
+<h3>Network Health &amp; Responsibility<a class="headerlink" href="#network-health-responsibility" title="Link to this heading">¶</a></h3>
+<p>As you participate in the wider networks you discover and build, you will inevitably encounter peers that are misconfigured, malicious, or simply broken. To protect your resources and those of your local peers, you can utilize the <a class="reference internal" href="using.html#using-blackhole-management"><span class="std std-ref">Blackhole Management</span></a> system.</p>
+<p>Whether you manually block a spamming identity or subscribe to a blackhole list maintained by a trusted Network Identity, these tools help ensure that <em>your</em> transport capacity is used for what <em>you</em> consider legitimate communication. This keeps your local segment efficient and contributes to the health of the wider network.</p>
+</section>
+<section id="contributing-to-the-global-ret">
+<h3>Contributing to the Global Ret<a class="headerlink" href="#contributing-to-the-global-ret" title="Link to this heading">¶</a></h3>
+<p>If you have the means to host a stable node with a public IP address, consider becoming a <a class="reference internal" href="#hosting-entrypoints"><span class="std std-ref">Public Entrypoint</span></a>. By <a class="reference internal" href="interfaces.html#interfaces-discoverable"><span class="std std-ref">publishing your interface as discoverable</span></a>, you provide a potential connection point for others, helping the network grow and reach new areas.</p>
+<p>For guidelines on how to properly configure a public entrypoint, refer to the <a class="reference internal" href="#hosting-entrypoints"><span class="std std-ref">Hosting Public Entrypoints</span></a> section.</p>
+</section>
+</section>
+<section id="connect-to-the-distributed-backbone">
+<h2>Connect to the Distributed Backbone<a class="headerlink" href="#connect-to-the-distributed-backbone" title="Link to this heading">¶</a></h2>
+<p>A global, distributed backbone of Reticulum Transport Nodes is being run by volunteers from around the world. This network constitutes a heterogenous collection of both public and private nodes that form an uncoordinated, voluntary inter-networking backbone that currently provides global transport and internetworking capabilities for Reticulum.</p>
+<p>As a good starting point, you can find interface definitions for connecting your own networks to this backbone on websites such as <a class="reference external" href="https://directory.rns.recipes/">directory.rns.recipes</a> and <a class="reference external" href="https://rmap.world/">rmap.world</a>.</p>
 <div class="admonition tip">
 <p class="admonition-title">Tip</p>
-<p>Ideally, set up a Reticulum Transport Node that your own devices can reach locally, and then
-connect that transport node to a couple of public entrypoints. This will provide efficient
-connections and redundancy in case any of them go down.</p>
-</div>
-<p>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.
-Expect weird things to happen on this network, as people experiment and try out things.</p>
-<div class="admonition warning">
-<p class="admonition-title">Warning</p>
-<p>It probably goes without saying, but <em>don’t use the testnet entry-points as
-hardcoded or default interfaces in any applications you ship to users</em>. When
-shipping applications, the best practice is to provide your own default
-connectivity solutions, if needed and applicable, or in most cases, simply
-leave it up to the user which networks to connect to, and how.</p>
+<p>Don’t rely on just a single connection to the distributed backbone for everyday use. It is much better to have several redundant connections configured, and enable the interface discovery options, so your nodes can continously discover peering opportunities as the network evolves. Refer to the <a class="reference internal" href="#bootstrapping-connectivity"><span class="std std-ref">Bootstrapping Connectivity</span></a> section to understand the options.</p>
 </div>
 </section>
 <section id="hosting-public-entrypoints">
-<h2>Hosting Public Entrypoints<a class="headerlink" href="#hosting-public-entrypoints" title="Link to this heading">¶</a></h2>
-<p>If you want to host a public (or private) entry-point to a Reticulum network over the
-Internet, this section offers some helpful pointers. You will need a machine, physical or
-virtual with a public IP address, that can be reached by other devices on the Internet.</p>
+<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>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
@@ -511,6 +445,13 @@ to your entry-point.</p>
 <span class="w">  </span><span class="na">mode</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">gateway</span>
 <span class="w">  </span><span class="na">listen_on</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">0.0.0.0</span>
 <span class="w">  </span><span class="na">port</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">4242</span>
+
+<span class="w">  </span><span class="c1"># On publicly available interfaces, it can be</span>
+<span class="w">  </span><span class="c1"># a good idea to configure sensible announce</span>
+<span class="w">  </span><span class="c1"># rate targets.</span>
+<span class="w">  </span><span class="na">announce_rate_target</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">3600</span>
+<span class="w">  </span><span class="na">announce_rate_penalty</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">3600</span>
+<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">12</span>
 </pre></div>
 </div>
 <p>If instead you want to make a private entry-point from the Internet, you can use the
@@ -532,6 +473,37 @@ to your entry-point.</p>
 <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>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>
+</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
@@ -543,20 +515,16 @@ work with Reticulum. For information on how to configure this, see the
 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. 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>. For more information on RNode, you can also
-refer to these additional external resources:</p>
-<ul class="simple">
-<li><p><a class="reference external" href="https://unsigned.io/how-to-make-your-own-rnodes/">How To Make Your Own RNodes</a></p></li>
-<li><p><a class="reference external" href="https://unsigned.io/installing-rnode-firmware-on-supported-devices/">Installing RNode Firmware on Compatible LoRa Devices</a></p></li>
-<li><p><a class="reference external" href="https://unsigned.io/private-messaging-over-lora/">Private, Secure and Uncensorable Messaging Over a LoRa Mesh</a></p></li>
-<li><p><a class="reference external" href="https://github.com/markqvist/RNode_Firmware/">RNode Firmware</a></p></li>
-</ul>
+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>, but you think would be suitable for use with Reticulum,
-you are welcome to head over to the <a class="reference external" href="https://github.com/markqvist/Reticulum/discussions">GitHub discussion pages</a>
-and propose adding an interface for the hardware.</p>
+<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>
@@ -579,50 +547,8 @@ started is to install the latest release of Reticulum via pip:</p>
 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.</p>
-</section>
-<section id="participate-in-reticulum-development">
-<h2>Participate in Reticulum Development<a class="headerlink" href="#participate-in-reticulum-development" title="Link to this heading">¶</a></h2>
-<p>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:</p>
-<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install dependencies</span>
-pip<span class="w"> </span>install<span class="w"> </span>cryptography<span class="w"> </span>pyserial
-
-<span class="c1"># Clone repository</span>
-git<span class="w"> </span>clone<span class="w"> </span>https://github.com/markqvist/Reticulum.git
-
-<span class="c1"># Move into Reticulum folder and symlink library to examples folder</span>
-<span class="nb">cd</span><span class="w"> </span>Reticulum
-ln<span class="w"> </span>-s<span class="w"> </span>../RNS<span class="w"> </span>./Examples/
-
-<span class="c1"># Run an example</span>
-python<span class="w"> </span>Examples/Echo.py<span class="w"> </span>-s
-
-<span class="c1"># Unless you&#39;ve manually created a config file, Reticulum will do so now,</span>
-<span class="c1"># and immediately exit. Make any necessary changes to the file:</span>
-nano<span class="w"> </span>~/.reticulum/config
-
-<span class="c1"># ... and launch the example again.</span>
-python<span class="w"> </span>Examples/Echo.py<span class="w"> </span>-s
-
-<span class="c1"># You can now repeat the process on another computer,</span>
-<span class="c1"># and run the same example with -h to get command line options.</span>
-python<span class="w"> </span>Examples/Echo.py<span class="w"> </span>-h
-
-<span class="c1"># Run the example in client mode to &quot;ping&quot; the server.</span>
-<span class="c1"># Replace the hash below with the actual destination hash of your server.</span>
-python<span class="w"> </span>Examples/Echo.py<span class="w"> </span>174a64852a75682259ad8b921b8bf416
-
-<span class="c1"># Have a look at another example</span>
-python<span class="w"> </span>Examples/Filetransfer.py<span class="w"> </span>-h
-</pre></div>
-</div>
-<p>When you have experimented with the basic examples, it’s time to go read the
-<a class="reference internal" href="understanding.html#understanding-main"><span class="std std-ref">Understanding Reticulum</span></a> chapter. Before submitting
-your first pull request, it is probably a good idea to introduce yourself on
-the <a class="reference external" href="https://github.com/markqvist/Reticulum/discussions">disucssion forum on GitHub</a>,
-or ask one of the developers or maintainers for a good place to start.</p>
+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>
@@ -946,12 +872,12 @@ All other available modules will still be loaded when needed.</p>
       <footer>
         
         <div class="related-pages">
-          <a class="next-page" href="using.html">
+          <a class="next-page" href="zen.html">
               <div class="page-info">
                 <div class="context">
                   <span>Next</span>
                 </div>
-                <div class="title">Using Reticulum on Your System</div>
+                <div class="title">Zen of Reticulum</div>
               </div>
               <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
             </a>
@@ -1000,22 +926,23 @@ All other available modules will still be loaded when needed.</p>
 <li><a class="reference internal" href="#resolving-dependency-installation-issues">Resolving Dependency &amp; Installation Issues</a></li>
 </ul>
 </li>
-<li><a class="reference internal" href="#try-using-a-reticulum-based-program">Try Using a Reticulum-based Program</a><ul>
-<li><a class="reference internal" href="#remote-shell">Remote Shell</a></li>
-<li><a class="reference internal" href="#nomad-network">Nomad Network</a></li>
-<li><a class="reference internal" href="#sideband">Sideband</a></li>
-<li><a class="reference internal" href="#meshchat">MeshChat</a></li>
-</ul>
-</li>
+<li><a class="reference internal" href="#try-using-a-reticulum-based-program">Try Using a Reticulum-based Program</a></li>
 <li><a class="reference internal" href="#using-the-included-utilities">Using the Included Utilities</a></li>
 <li><a class="reference internal" href="#creating-a-network-with-reticulum">Creating a Network With Reticulum</a></li>
-<li><a class="reference internal" href="#connecting-reticulum-instances-over-the-internet">Connecting Reticulum Instances Over the Internet</a></li>
-<li><a class="reference internal" href="#connect-to-the-public-testnet">Connect to the Public Testnet</a></li>
+<li><a class="reference internal" href="#bootstrapping-connectivity">Bootstrapping Connectivity</a><ul>
+<li><a class="reference internal" href="#finding-your-way">Finding Your Way</a></li>
+<li><a class="reference internal" href="#build-personal-infrastructure">Build Personal Infrastructure</a></li>
+<li><a class="reference internal" href="#mixing-strategies">Mixing Strategies</a></li>
+<li><a class="reference internal" href="#network-health-responsibility">Network Health &amp; Responsibility</a></li>
+<li><a class="reference internal" href="#contributing-to-the-global-ret">Contributing to the Global Ret</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#connect-to-the-distributed-backbone">Connect to the Distributed Backbone</a></li>
 <li><a class="reference internal" href="#hosting-public-entrypoints">Hosting Public Entrypoints</a></li>
+<li><a class="reference internal" href="#connecting-reticulum-instances-over-the-internet">Connecting Reticulum Instances Over the Internet</a></li>
 <li><a class="reference internal" href="#adding-radio-interfaces">Adding Radio Interfaces</a></li>
 <li><a class="reference internal" href="#creating-and-using-custom-interfaces">Creating and Using Custom Interfaces</a></li>
 <li><a class="reference internal" href="#develop-a-program-with-reticulum">Develop a Program with Reticulum</a></li>
-<li><a class="reference internal" href="#participate-in-reticulum-development">Participate in Reticulum Development</a></li>
 <li><a class="reference internal" href="#platform-specific-install-notes">Platform-Specific Install Notes</a><ul>
 <li><a class="reference internal" href="#android">Android</a></li>
 <li><a class="reference internal" href="#arm64">ARM64</a></li>
@@ -1040,7 +967,7 @@ All other available modules will still be loaded when needed.</p>
       
     </aside>
   </div>
-</div><script src="_static/documentation_options.js?v=baaebd52"></script>
+</div><script src="_static/documentation_options.js?v=590429e0"></script>
     <script src="_static/doctools.js?v=9bcbadda"></script>
     <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="_static/scripts/furo.js?v=46bd48cc"></script>

docs/manual/git.html

@@ -0,0 +1,792 @@
+<!doctype html>
+<html class="no-js" lang="en" data-content_root="./">
+  <head><meta charset="utf-8">
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+    <meta name="color-scheme" content="light dark"><meta name="viewport" content="width=device-width, initial-scale=1" />
+<link rel="index" title="Index" href="genindex.html"><link rel="search" title="Search" href="search.html"><link rel="next" title="Support Reticulum" href="support.html"><link rel="prev" title="Building Networks" href="networks.html">
+        <link rel="prefetch" href="_static/rns_logo_512.png" as="image">
+
+    <!-- Generated with Sphinx 8.2.3 and Furo 2025.09.25.dev1 -->
+        <title>Git Over Reticulum - Reticulum Network Stack 1.2.3 documentation</title>
+      <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d111a655" />
+    <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=580074bf" />
+    <link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
+    <link rel="stylesheet" type="text/css" href="_static/styles/furo-extensions.css?v=8dab3a3b" />
+    <link rel="stylesheet" type="text/css" href="_static/custom.css?v=bb3cebc5" />
+    
+    
+
+
+<style>
+  body {
+    --color-code-background: #f2f2f2;
+  --color-code-foreground: #1e1e1e;
+  
+  }
+  @media not print {
+    body[data-theme="dark"] {
+      --color-code-background: #202020;
+  --color-code-foreground: #d0d0d0;
+  --color-background-primary: #202b38;
+  --color-background-secondary: #161f27;
+  --color-foreground-primary: #dbdbdb;
+  --color-foreground-secondary: #a9b1ba;
+  --color-brand-primary: #41adff;
+  --color-background-hover: #161f27;
+  --color-api-name: #ffbe85;
+  --color-api-pre-name: #efae75;
+  
+    }
+    @media (prefers-color-scheme: dark) {
+      body:not([data-theme="light"]) {
+        --color-code-background: #202020;
+  --color-code-foreground: #d0d0d0;
+  --color-background-primary: #202b38;
+  --color-background-secondary: #161f27;
+  --color-foreground-primary: #dbdbdb;
+  --color-foreground-secondary: #a9b1ba;
+  --color-brand-primary: #41adff;
+  --color-background-hover: #161f27;
+  --color-api-name: #ffbe85;
+  --color-api-pre-name: #efae75;
+  
+      }
+    }
+  }
+</style></head>
+  <body>
+    
+    <script>
+      document.body.dataset.theme = localStorage.getItem("theme") || "auto";
+    </script>
+    
+
+<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
+  <symbol id="svg-toc" viewBox="0 0 24 24">
+    <title>Contents</title>
+    <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 1024 1024">
+      <path d="M408 442h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8zm-8 204c0 4.4 3.6 8 8 8h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56zm504-486H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zm0 632H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zM115.4 518.9L271.7 642c5.8 4.6 14.4.5 14.4-6.9V388.9c0-7.4-8.5-11.5-14.4-6.9L115.4 505.1a8.74 8.74 0 0 0 0 13.8z"/>
+    </svg>
+  </symbol>
+  <symbol id="svg-menu" viewBox="0 0 24 24">
+    <title>Menu</title>
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+      stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-menu">
+      <line x1="3" y1="12" x2="21" y2="12"></line>
+      <line x1="3" y1="6" x2="21" y2="6"></line>
+      <line x1="3" y1="18" x2="21" y2="18"></line>
+    </svg>
+  </symbol>
+  <symbol id="svg-arrow-right" viewBox="0 0 24 24">
+    <title>Expand</title>
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+      stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-chevron-right">
+      <polyline points="9 18 15 12 9 6"></polyline>
+    </svg>
+  </symbol>
+  <symbol id="svg-sun" viewBox="0 0 24 24">
+    <title>Light mode</title>
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+      stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="feather-sun">
+      <circle cx="12" cy="12" r="5"></circle>
+      <line x1="12" y1="1" x2="12" y2="3"></line>
+      <line x1="12" y1="21" x2="12" y2="23"></line>
+      <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line>
+      <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line>
+      <line x1="1" y1="12" x2="3" y2="12"></line>
+      <line x1="21" y1="12" x2="23" y2="12"></line>
+      <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line>
+      <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line>
+    </svg>
+  </symbol>
+  <symbol id="svg-moon" viewBox="0 0 24 24">
+    <title>Dark mode</title>
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+      stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-moon">
+      <path stroke="none" d="M0 0h24v24H0z" fill="none" />
+      <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z" />
+    </svg>
+  </symbol>
+  <symbol id="svg-sun-with-moon" viewBox="0 0 24 24">
+    <title>Auto light/dark, in light mode</title>
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+      stroke-width="1" stroke-linecap="round" stroke-linejoin="round"
+      class="icon-custom-derived-from-feather-sun-and-tabler-moon">
+      <path style="opacity: 50%" d="M 5.411 14.504 C 5.471 14.504 5.532 14.504 5.591 14.504 C 3.639 16.319 4.383 19.569 6.931 20.352 C 7.693 20.586 8.512 20.551 9.25 20.252 C 8.023 23.207 4.056 23.725 2.11 21.184 C 0.166 18.642 1.702 14.949 4.874 14.536 C 5.051 14.512 5.231 14.5 5.411 14.5 L 5.411 14.504 Z"/>
+      <line x1="14.5" y1="3.25" x2="14.5" y2="1.25"/>
+      <line x1="14.5" y1="15.85" x2="14.5" y2="17.85"/>
+      <line x1="10.044" y1="5.094" x2="8.63" y2="3.68"/>
+      <line x1="19" y1="14.05" x2="20.414" y2="15.464"/>
+      <line x1="8.2" y1="9.55" x2="6.2" y2="9.55"/>
+      <line x1="20.8" y1="9.55" x2="22.8" y2="9.55"/>
+      <line x1="10.044" y1="14.006" x2="8.63" y2="15.42"/>
+      <line x1="19" y1="5.05" x2="20.414" y2="3.636"/>
+      <circle cx="14.5" cy="9.55" r="3.6"/>
+    </svg>
+  </symbol>
+  <symbol id="svg-moon-with-sun" viewBox="0 0 24 24">
+    <title>Auto light/dark, in dark mode</title>
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+      stroke-width="1" stroke-linecap="round" stroke-linejoin="round"
+      class="icon-custom-derived-from-feather-sun-and-tabler-moon">
+      <path d="M 8.282 7.007 C 8.385 7.007 8.494 7.007 8.595 7.007 C 5.18 10.184 6.481 15.869 10.942 17.24 C 12.275 17.648 13.706 17.589 15 17.066 C 12.851 22.236 5.91 23.143 2.505 18.696 C -0.897 14.249 1.791 7.786 7.342 7.063 C 7.652 7.021 7.965 7 8.282 7 L 8.282 7.007 Z"/>
+      <line style="opacity: 50%" x1="18" y1="3.705" x2="18" y2="2.5"/>
+      <line style="opacity: 50%" x1="18" y1="11.295" x2="18" y2="12.5"/>
+      <line style="opacity: 50%" x1="15.316" y1="4.816" x2="14.464" y2="3.964"/>
+      <line style="opacity: 50%" x1="20.711" y1="10.212" x2="21.563" y2="11.063"/>
+      <line style="opacity: 50%" x1="14.205" y1="7.5" x2="13.001" y2="7.5"/>
+      <line style="opacity: 50%" x1="21.795" y1="7.5" x2="23" y2="7.5"/>
+      <line style="opacity: 50%" x1="15.316" y1="10.184" x2="14.464" y2="11.036"/>
+      <line style="opacity: 50%" x1="20.711" y1="4.789" x2="21.563" y2="3.937"/>
+      <circle style="opacity: 50%" cx="18" cy="7.5" r="2.169"/>
+    </svg>
+  </symbol>
+  <symbol id="svg-pencil" viewBox="0 0 24 24">
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+      stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-pencil-code">
+      <path d="M4 20h4l10.5 -10.5a2.828 2.828 0 1 0 -4 -4l-10.5 10.5v4" />
+      <path d="M13.5 6.5l4 4" />
+      <path d="M20 21l2 -2l-2 -2" />
+      <path d="M17 17l-2 2l2 2" />
+    </svg>
+  </symbol>
+  <symbol id="svg-eye" viewBox="0 0 24 24">
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+      stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-eye-code">
+      <path stroke="none" d="M0 0h24v24H0z" fill="none" />
+      <path d="M10 12a2 2 0 1 0 4 0a2 2 0 0 0 -4 0" />
+      <path
+        d="M11.11 17.958c-3.209 -.307 -5.91 -2.293 -8.11 -5.958c2.4 -4 5.4 -6 9 -6c3.6 0 6.6 2 9 6c-.21 .352 -.427 .688 -.647 1.008" />
+      <path d="M20 21l2 -2l-2 -2" />
+      <path d="M17 17l-2 2l2 2" />
+    </svg>
+  </symbol>
+</svg>
+
+<input type="checkbox" class="sidebar-toggle" name="__navigation" id="__navigation" aria-label="Toggle site navigation sidebar">
+<input type="checkbox" class="sidebar-toggle" name="__toc" id="__toc" aria-label="Toggle table of contents sidebar">
+<label class="overlay sidebar-overlay" for="__navigation"></label>
+<label class="overlay toc-overlay" for="__toc"></label>
+
+<a class="skip-to-content muted-link" href="#furo-main-content">Skip to content</a>
+
+
+
+<div class="page">
+  <header class="mobile-header">
+    <div class="header-left">
+      <label class="nav-overlay-icon" for="__navigation">
+        <span class="icon"><svg><use href="#svg-menu"></use></svg></span>
+      </label>
+    </div>
+    <div class="header-center">
+      <a href="index.html"><div class="brand">Reticulum Network Stack 1.2.3 documentation</div></a>
+    </div>
+    <div class="header-right">
+      <div class="theme-toggle-container theme-toggle-header">
+        <button class="theme-toggle" aria-label="Toggle Light / Dark / Auto color theme">
+          <svg class="theme-icon-when-auto-light"><use href="#svg-sun-with-moon"></use></svg>
+          <svg class="theme-icon-when-auto-dark"><use href="#svg-moon-with-sun"></use></svg>
+          <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg>
+          <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg>
+        </button>
+      </div>
+      <label class="toc-overlay-icon toc-header-icon" for="__toc">
+        <span class="icon"><svg><use href="#svg-toc"></use></svg></span>
+      </label>
+    </div>
+  </header>
+  <aside class="sidebar-drawer">
+    <div class="sidebar-container">
+      
+      <div class="sidebar-sticky"><a class="sidebar-brand" href="index.html">
+  <div class="sidebar-logo-container">
+    <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
+  </div>
+  
+  <span class="sidebar-brand-text">Reticulum Network Stack 1.2.3 documentation</span>
+  
+</a><form class="sidebar-search-container" method="get" action="search.html" role="search">
+  <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
+  <input type="hidden" name="check_keywords" value="yes">
+  <input type="hidden" name="area" value="default">
+</form>
+<div id="searchbox"></div><div class="sidebar-scroll"><div class="sidebar-tree">
+  <ul class="current">
+<li class="toctree-l1"><a class="reference internal" href="whatis.html">What is Reticulum?</a></li>
+<li class="toctree-l1"><a class="reference internal" href="gettingstartedfast.html">Getting Started Fast</a></li>
+<li class="toctree-l1"><a class="reference internal" href="zen.html">Zen of Reticulum</a></li>
+<li class="toctree-l1"><a class="reference internal" href="software.html">Programs Using Reticulum</a></li>
+<li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
+<li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
+<li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
+<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
+<li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks</a></li>
+<li class="toctree-l1 current current-page"><a class="current reference internal" href="#">Git Over Reticulum</a></li>
+<li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a></li>
+<li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a></li>
+<li class="toctree-l1"><a class="reference internal" href="license.html">Reticulum License</a></li>
+</ul>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="reference.html">API Reference</a></li>
+</ul>
+
+</div>
+</div>
+
+      </div>
+      
+    </div>
+  </aside>
+  <div class="main">
+    <div class="content">
+      <div class="article-container">
+        <a href="#" class="back-to-top muted-link">
+          <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
+            <path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8v12z"></path>
+          </svg>
+          <span>Back to top</span>
+        </a>
+        <div class="content-icon-container">
+          <div class="theme-toggle-container theme-toggle-content">
+            <button class="theme-toggle" aria-label="Toggle Light / Dark / Auto color theme">
+              <svg class="theme-icon-when-auto-light"><use href="#svg-sun-with-moon"></use></svg>
+              <svg class="theme-icon-when-auto-dark"><use href="#svg-moon-with-sun"></use></svg>
+              <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg>
+              <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg>
+            </button>
+          </div>
+          <label class="toc-overlay-icon toc-content-icon" for="__toc">
+            <span class="icon"><svg><use href="#svg-toc"></use></svg></span>
+          </label>
+        </div>
+        <article role="main" id="furo-main-content">
+          <section id="git-over-reticulum">
+<span id="git-main"></span><h1>Git Over Reticulum<a class="headerlink" href="#git-over-reticulum" title="Link to this heading">¶</a></h1>
+<p>A set of utilities for distributed collaborative software development and publishing is included in RNS.</p>
+<p>The system consists of two parts: The <code class="docutils literal notranslate"><span class="pre">rngit</span></code> node that hosts repositories, and the <code class="docutils literal notranslate"><span class="pre">git-remote-rns</span></code> helper that enables Git to communicate with rngit nodes. As soon as you have RNS installed on your system, you can transparently use Git with Reticulum-hosted repositories just like any other type of remote. Git over Reticulum uses URLs in the following format: <code class="docutils literal notranslate"><span class="pre">rns://DESTINATION_HASH/group/repo</span></code>.</p>
+<p>If you set a branch to track a Reticulum remote as the default upstream, you can simply use <code class="docutils literal notranslate"><span class="pre">git</span></code> as you normally would; all commands work transparently and as expected.</p>
+<div class="admonition warning">
+<p class="admonition-title">Warning</p>
+<p><strong>The rngit program is a new addition to RNS!</strong> This functionality was introduced in RNS 1.2.0. While great care has been taken to design a secure, but highly configurable and flexible permission system for allowing many users to interact with many different repositories on a single node, <code class="docutils literal notranslate"><span class="pre">rngit</span></code> has not been tested extensively in the wild! Be careful when hosting repositories, especially if they are public or semi-public.</p>
+</div>
+<section id="the-rngit-utility">
+<h2>The rngit Utility<a class="headerlink" href="#the-rngit-utility" title="Link to this heading">¶</a></h2>
+<p>The <code class="docutils literal notranslate"><span class="pre">rngit</span></code> utility provides full Git repository hosting and interaction over Reticulum. It allows you to host and manage Git repositories and releases on Reticulum nodes, and to interact with remote repositories using standard Git commands through the <code class="docutils literal notranslate"><span class="pre">rns://</span></code> URL scheme.</p>
+<p><strong>Usage Examples</strong></p>
+<p>Run <code class="docutils literal notranslate"><span class="pre">rngit</span></code> to start a repository node:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rngit
+
+[Notice] Starting Reticulum Git Node...
+[Notice] Reticulum Git Node listening on &lt;0d7334d411d00120cbad24edf355fdd2&gt;
+</pre></div>
+</div>
+<p>On the first run, <code class="docutils literal notranslate"><span class="pre">rngit</span></code> will create a default configuration file. You will then need to edit this, to point to your repository locations, configure access permissions, and perform any other necessary configuration.</p>
+<p>View your identity and destination hashes:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rngit --print-identity
+
+Git Peer Identity         : &lt;959e10e5efc1bd9d97a4083babe51dea&gt;
+Repository Node Identity  : &lt;153cb870b4665b8c1c348896292b0bad&gt;
+Repositories Destination  : &lt;0d7334d411d00120cbad24edf355fdd2&gt;
+</pre></div>
+</div>
+<p>If the page node is enabled, the output will also include the Nomad Network destination hash.</p>
+<p>You can run <code class="docutils literal notranslate"><span class="pre">rngit</span></code> in service mode with logging to file:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rngit -s
+</pre></div>
+</div>
+<p>Clone a repository from a remote <code class="docutils literal notranslate"><span class="pre">rngit</span></code> node:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ git clone rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo
+</pre></div>
+</div>
+<p>Add a Reticulum remote to an existing repository:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ git remote add some_remote rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo
+</pre></div>
+</div>
+<p>Push changes to the Reticulum remote:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ git push some_remote master
+</pre></div>
+</div>
+<p>Get changes from a remote repository:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ git pull rns_remote master
+</pre></div>
+</div>
+<p><strong>All Command-Line Options (rngit)</strong></p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rngit.py [-h] [--config CONFIG] [--rnsconfig RNSCONFIG] [-s] [-i] [-v]
+                [-q] [--version]
+
+Reticulum Git Repository Node
+
+options:
+  -h, --help            show this help message and exit
+  --config CONFIG       path to alternative config directory
+  --rnsconfig RNSCONFIG
+                        path to alternative Reticulum config directory
+  -p, --print-identity  print identity and destination info and exit
+  -s, --service         rngit is running as a service and should log to file
+  -i, --interactive     drop into interactive shell after initialisation
+  -v, --verbose         increase verbosity
+  -q, --quiet           decrease verbosity
+  --version             show program&#39;s version number and exit
+</pre></div>
+</div>
+<p><strong>All Command-Line Options (git-remote-rns)</strong></p>
+<p>The <code class="docutils literal notranslate"><span class="pre">git-remote-rns</span></code> helper is automatically invoked by Git when interacting with <code class="docutils literal notranslate"><span class="pre">rns://</span></code> URLs. It is not typically run directly by users, but accepts the following environment variables for configuration:</p>
+<ul class="simple">
+<li><p><code class="docutils literal notranslate"><span class="pre">RNGIT_CONFIG</span></code> - Path to alternative client configuration directory</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">RNS_CONFIG</span></code> - Path to alternative Reticulum configuration directory</p></li>
+</ul>
+<p>The client configuration file is located at <code class="docutils literal notranslate"><span class="pre">~/.rngit/client_config</span></code> and allows adjusting parameters such as the reference batch size for transfers.</p>
+</section>
+<section id="repository-structure">
+<h2>Repository Structure<a class="headerlink" href="#repository-structure" title="Link to this heading">¶</a></h2>
+<p>The <code class="docutils literal notranslate"><span class="pre">rngit</span></code> node organizes repositories into groups. Each group is a directory containing bare Git repositories. The repository path format is <code class="docutils literal notranslate"><span class="pre">group_name/repo_name</span></code>. For example, a repository at <code class="docutils literal notranslate"><span class="pre">/var/git/public/myrepo</span></code> would be accessible as <code class="docutils literal notranslate"><span class="pre">public/myrepo</span></code> via the URL <code class="docutils literal notranslate"><span class="pre">rns://DESTINATION_HASH/public/myrepo</span></code>.</p>
+<p><strong>Configuration</strong></p>
+<p>The <code class="docutils literal notranslate"><span class="pre">rngit</span></code> node configuration file is located at <code class="docutils literal notranslate"><span class="pre">~/.rngit/config</span></code> (or <code class="docutils literal notranslate"><span class="pre">/etc/rngit/config</span></code> for system-wide installations). The default configuration includes:</p>
+<ul class="simple">
+<li><p>Repository group paths defining where to find bare repositories</p></li>
+<li><p>Access permissions for groups and individual repositories</p></li>
+<li><p>Announce intervals for network visibility</p></li>
+<li><p>Optional statistics recording for repository activity</p></li>
+</ul>
+<p>Access permissions can be configured at the group level in the config file, or per-repository using <code class="docutils literal notranslate"><span class="pre">.allowed</span></code> files. Permissions use the format <code class="docutils literal notranslate"><span class="pre">permission:target</span></code> where permission is <code class="docutils literal notranslate"><span class="pre">r</span></code> (read), <code class="docutils literal notranslate"><span class="pre">w</span></code> (write), <code class="docutils literal notranslate"><span class="pre">rw</span></code> (read/write), <code class="docutils literal notranslate"><span class="pre">c</span></code> (create) or <code class="docutils literal notranslate"><span class="pre">s</span></code> (stats) and target is <code class="docutils literal notranslate"><span class="pre">all</span></code>, <code class="docutils literal notranslate"><span class="pre">none</span></code>, or a specific identity hash.</p>
+<p>The <code class="docutils literal notranslate"><span class="pre">s</span></code> (stats) permission allows viewing repository activity statistics, including views, fetches and pushes over time. To enable statistics recording, set <code class="docutils literal notranslate"><span class="pre">record_stats</span> <span class="pre">=</span> <span class="pre">yes</span></code> in the <code class="docutils literal notranslate"><span class="pre">[rngit]</span></code> section of the configuration file. You can also exclude specific identities from statistics by adding their hashes to <code class="docutils literal notranslate"><span class="pre">stats_ignore_identities</span></code>.</p>
+<p>Repository-specific <code class="docutils literal notranslate"><span class="pre">.allowed</span></code> files can be static text files or executable scripts that output permission rules to stdout. A <code class="docutils literal notranslate"><span class="pre">group.allowed</span></code> file in a repository group directory applies to all repositories within that group.</p>
+</section>
+<section id="serving-pages-over-nomad-network">
+<h2>Serving Pages Over Nomad Network<a class="headerlink" href="#serving-pages-over-nomad-network" title="Link to this heading">¶</a></h2>
+<p>In addition to providing Git repository access via the Git remote helper protocol, <code class="docutils literal notranslate"><span class="pre">rngit</span></code> can also run a <a class="reference external" href="https://github.com/markqvist/nomadnet">Nomad Network</a> compatible page node. This allows users to browse repository information, view file contents, inspect commit history and access repository statistics through any Nomad Network client.</p>
+<p>When enabled, the page node provides a complete interface to your repositories, with automatic Markdown to Micron conversion, syntax-highlighted code browsing, and detailed commit, diff and statistics views.</p>
+<p><strong>Enabling the Git Page Node</strong></p>
+<p>To enable the page node, add the following to your <code class="docutils literal notranslate"><span class="pre">~/.rngit/config</span></code> file:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>[pages]
+serve_nomadnet = yes
+</pre></div>
+</div>
+<p>When the page node is enabled, <code class="docutils literal notranslate"><span class="pre">rngit</span></code> will listen on a Nomad Network node destination in addition to the Git repository destination. You can view the destination hash by running:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rngit --print-identity
+
+Git Peer Identity         : &lt;959e10e5efc1bd9d97a4083babe51dea&gt;
+Repository Node Identity  : &lt;153cb870b4665b8c1c348896292b0bad&gt;
+Repositories Destination  : &lt;0d7334d411d00120cbad24edf355fdd2&gt;
+Nomad Network Destination : &lt;50824b711717f97c2fb1166ceddd5ea9&gt;
+</pre></div>
+</div>
+<p><strong>Accessing Repository Pages</strong></p>
+<p>Once the page node is running, you can access it from any Nomad Network client by connecting to the Nomad Network destination. The page node provides the following views:</p>
+<ul class="simple">
+<li><p><strong>Front Page</strong> - Lists all repository groups accessible to your identity</p></li>
+<li><p><strong>Group Page</strong> - Shows all repositories within a group</p></li>
+<li><p><strong>Repository Page</strong> - Displays repository overview, description and README</p></li>
+<li><p><strong>Releases</strong> - List of releases for the repository, with information and downloads</p></li>
+<li><p><strong>File Browser</strong> - Browse directory trees and view and download file contents</p></li>
+<li><p><strong>Commits View</strong> - View commit history with pagination</p></li>
+<li><p><strong>Commit Details</strong> - Detailed commit information with file changes and diffs</p></li>
+<li><p><strong>Refs View</strong> - List branches and tags</p></li>
+<li><p><strong>Statistics</strong> - Activity charts showing views, fetches and pushes over time</p></li>
+</ul>
+<p>All pages respect the same permission system used for Git access. If an identity does not have read access to a repository, they will not be able to view its pages.</p>
+</section>
+<section id="formatting-syntax-highlighting">
+<h2>Formatting &amp; Syntax Highlighting<a class="headerlink" href="#formatting-syntax-highlighting" title="Link to this heading">¶</a></h2>
+<p>If the <code class="docutils literal notranslate"><span class="pre">pygments</span></code> Python module is installed on your system, the page node will automatically apply syntax highlighting to code files. The highlighting supports a wide range of programming languages and uses a color theme optimized for terminal display.</p>
+<p>To enable syntax highlighting, install pygments:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>pip install pygments
+</pre></div>
+</div>
+<p><strong>Markdown &amp; Micron Support</strong></p>
+<p>README files and other Markdown documents are automatically converted to Micron markup for display in Nomad Network clients. You can also write your README files directly in Micron, in which case they will display and render as such in any Nomad Network client. The file browser also supports viewing both rendered and raw Markdown and Micron documents.</p>
+<p>Code blocks in Markdown can include language hints for syntax highlighting:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>```python
+def hello_world():
+    print(&quot;Hello, Reticulum!&quot;)
+```
+</pre></div>
+</div>
+</section>
+<section id="customizing-templates">
+<h2>Customizing Templates<a class="headerlink" href="#customizing-templates" title="Link to this heading">¶</a></h2>
+<p>The page node uses a template system that allows complete customization of the generated pages. Templates are stored in the <code class="docutils literal notranslate"><span class="pre">~/.rngit/templates/</span></code> directory as Micron files.</p>
+<p>The following template files are supported:</p>
+<ul class="simple">
+<li><p><code class="docutils literal notranslate"><span class="pre">base.mu</span></code> - Base template wrapping all pages</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">front.mu</span></code> - Front page listing all groups</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">group.mu</span></code> - Group page listing repositories</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">repo.mu</span></code> - Repository overview page</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">releases.mu</span></code> - Release list page</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">release.mu</span></code> - Release details page</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">tree.mu</span></code> - File browser pages</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">blob.mu</span></code> - File content display</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">commits.mu</span></code> - Commit history listing</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">commit.mu</span></code> - Individual commit detail page</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">refs.mu</span></code> - Branches and tags listing</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">stats.mu</span></code> - Statistics page</p></li>
+</ul>
+<p>Templates can include the following variables:</p>
+<ul class="simple">
+<li><p><code class="docutils literal notranslate"><span class="pre">{PAGE_CONTENT}</span></code> - The main content of the page (required)</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">{NODE_NAME}</span></code> - The configured node name</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">{NAVIGATION}</span></code> - Breadcrumb navigation links</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">{VERSION}</span></code> - The rngit version number</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">{GEN_TIME}</span></code> - Page generation time</p></li>
+</ul>
+<p><strong>Dynamic Templates</strong></p>
+<p>Templates can be made executable to generate dynamic content. If a template file has the executable bit set, it will be executed and its stdout used as the template content.</p>
+<p><strong>Icon Sets</strong></p>
+<p>By default, the page node uses Nerd Font icons. If you prefer simpler icons or your terminal does not support Nerd Fonts, you can enable Unicode icons instead:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>[pages]
+serve_nomadnet = yes
+unicode_icons = yes
+</pre></div>
+</div>
+<p><strong>Repository Statistics</strong></p>
+<p>When statistics recording is enabled (see the <code class="docutils literal notranslate"><span class="pre">record_stats</span></code> configuration option), the page node can display activity charts for each repository. The statistics page shows:</p>
+<ul class="simple">
+<li><p>Total and peak views, fetches and pushes</p></li>
+<li><p>Daily activity charts over a 90-day period</p></li>
+<li><p>Combined activity visualization</p></li>
+</ul>
+<p>To view statistics, a user must have the <code class="docutils literal notranslate"><span class="pre">s</span></code> (stats) permission for the repository. See the Access Configuration section for details on setting permissions.</p>
+<p><strong>Repository Thanks</strong></p>
+<p>The page node includes a “Thanks” feature that allows users to express appreciation for a repository. On each repository page, a “Thanks” link is displayed showing the current thanks count. Clicking this link registers a thank you for the repository.</p>
+<p><strong>Configuration Example</strong></p>
+<p>A complete page node configuration might look like this:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>[rngit]
+node_name = My Git Node
+announce_interval = 360
+record_stats = yes
+
+[repositories]
+public = /var/git/public
+internal = /var/git/internal
+
+[access]
+public = r:all
+internal = rw:9710b86ba12c42d1d8f30f74fe509286
+
+[pages]
+serve_nomadnet = yes
+unicode_icons = no
+</pre></div>
+</div>
+</section>
+<section id="release-management">
+<h2>Release Management<a class="headerlink" href="#release-management" title="Link to this heading">¶</a></h2>
+<p>In addition to hosting Git repositories, <code class="docutils literal notranslate"><span class="pre">rngit</span></code> provides a complete release management system. This allows you to publish versioned releases with associated artifacts, release notes and metadata. Releases are managed through the <code class="docutils literal notranslate"><span class="pre">rngit</span> <span class="pre">release</span></code> subcommand, and are also viewable through the Nomad Network page interface.</p>
+<p><strong>The Release Workflow</strong></p>
+<p>Creating a release involves specifying a Git tag and a directory containing build artifacts or other files to distribute. The <code class="docutils literal notranslate"><span class="pre">rngit</span></code> client will open your configured <code class="docutils literal notranslate"><span class="pre">$EDITOR</span></code> to compose release notes, then upload all artifacts to the remote repository node.</p>
+<p>To create a release, specify the tag name and path to artifacts:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rngit release rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo create v1.2.0:./dist
+</pre></div>
+</div>
+<p>This will:</p>
+<ol class="arabic simple">
+<li><p>Verify that the tag <code class="docutils literal notranslate"><span class="pre">v1.2.0</span></code> exists in the repository</p></li>
+<li><p>Open your editor to write release notes</p></li>
+<li><p>Upload all files from the <code class="docutils literal notranslate"><span class="pre">./dist</span></code> directory</p></li>
+<li><p>Publish the release</p></li>
+</ol>
+<p>If no <code class="docutils literal notranslate"><span class="pre">$EDITOR</span></code> environment variable is set, <code class="docutils literal notranslate"><span class="pre">rngit</span></code> will try to use <code class="docutils literal notranslate"><span class="pre">nano</span></code>, <code class="docutils literal notranslate"><span class="pre">vim</span></code> or <code class="docutils literal notranslate"><span class="pre">vi</span></code>. The editor will show a template with instructions. Lines starting with <code class="docutils literal notranslate"><span class="pre">#</span></code> will be ignored, and if the remaining content is empty after stripping comments, the release creation will be cancelled.</p>
+<p><strong>Release Storage &amp; Structure</strong></p>
+<p>Releases are stored on the node in a directory named <code class="docutils literal notranslate"><span class="pre">repo_name.releases</span></code> next to the bare repository. Each release is a subdirectory containing:</p>
+<ul class="simple">
+<li><p><code class="docutils literal notranslate"><span class="pre">META</span></code> - Release metadata in ConfigObj format</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">RELEASE.md</span></code> or <code class="docutils literal notranslate"><span class="pre">RELEASE.mu</span></code> - Release notes</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">artifacts/</span></code> - All uploaded files</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">THANKS</span></code> - Appreciation count from users</p></li>
+</ul>
+<p><strong>Listing Releases</strong></p>
+<p>To view all releases for a repository:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rngit release rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo list
+
+Tag          Status     Created              Objs  Notes
+------------------------------------------------------------------
+v1.2.0       published  2025-01-15 14:32     3     Another release
+v1.1.0       published  2024-12-03 09:15     2     Bug fix release
+v1.0.0       published  2024-10-20 16:45     2     Initial release
+</pre></div>
+</div>
+<p><strong>Viewing Release Details</strong></p>
+<p>To see full information about a specific release:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rngit release rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo view v1.2.0
+
+Release : 0.9.2
+Status  : published
+Created : 2026-05-04 23:53:09
+Thanks  : 5
+
+Release Notes
+=============
+
+Version 1.2.0 release notes...
+
+Artifacts (4)
+=============
+  - myapp-1.2.0.tar.gz (1.5 MB)
+  - myapp-1.2.0.zip (1.6 MB)
+  - checksums.txt (256 B)
+</pre></div>
+</div>
+<p><strong>Deleting Releases</strong></p>
+<p>To remove a release:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rngit release rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo delete v1.2.0
+
+Are you sure you want to delete release &#39;v1.2.0&#39;? [y/N]: y
+Release v1.2.0 deleted
+</pre></div>
+</div>
+<p><strong>Requirements &amp; Validation</strong></p>
+<ul class="simple">
+<li><p>The specified tag must exist in the remote repository</p></li>
+<li><p>You must have <code class="docutils literal notranslate"><span class="pre">release</span></code> permission for the repository</p></li>
+<li><p>The target artifacts directory must exist and contain at least one file</p></li>
+<li><p>Release notes cannot be empty</p></li>
+</ul>
+<p><strong>Permissions</strong></p>
+<p>Release management requires the <code class="docutils literal notranslate"><span class="pre">release</span></code> permission, configured the same way as other repository permissions. In the config file or <code class="docutils literal notranslate"><span class="pre">.allowed</span></code> files, use <code class="docutils literal notranslate"><span class="pre">rel:target</span></code> to grant release management rights:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span># In .allowed file or config
+rel:all          # Allow everyone
+rel:9710b86...   # Allow specific identity
+rel:none         # Deny everyone
+</pre></div>
+</div>
+<p><strong>Nomad Network Interface</strong></p>
+<p>When the Nomad Network page node is enabled, releases are displayed on a dedicated releases page for each repository. Each release is listed with its tag, creation date, artifact count and a preview of the release notes. Clicking a release shows the full details including formatted release notes and a listing of all artifacts with their sizes.</p>
+<p>Only releases with <code class="docutils literal notranslate"><span class="pre">published</span></code> status are visible through the Nomad Network interface. Draft releases (if supported in future implementations) would only be visible through the command-line interface.</p>
+<p><strong>All Command-Line Options (rngit release)</strong></p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rngit release [-h] [--config CONFIG] [--rnsconfig RNSCONFIG]
+                     [-i PATH] [-v] [-q] [--version]
+                     [repository] [operation] [target]
+
+Reticulum Git Release Manager
+
+positional arguments:
+  repository            URL of remote repository
+  operation             list, view, create or delete
+  target                tag and path to release artifacts directory
+
+options:
+  -h, --help            show this help message and exit
+  --config CONFIG       path to alternative config directory
+  --rnsconfig RNSCONFIG
+                        path to alternative Reticulum config directory
+  -i, --identity PATH   path to release identity
+  -v, --verbose
+  -q, --quiet
+  --version             show program&#39;s version number and exit
+</pre></div>
+</div>
+</section>
+<section id="work-documents">
+<h2>Work Documents<a class="headerlink" href="#work-documents" title="Link to this heading">¶</a></h2>
+<p>In addition to releases, <code class="docutils literal notranslate"><span class="pre">rngit</span></code> provides a work document management system for tracking tasks, investigations, issues and progress related to repositories. Work documents are stored as structured msgpack data and support threaded updates and comments.</p>
+<p><strong>Listing Work Documents</strong></p>
+<p>To view work documents for a repository:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rngit work rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo list
+
+Active documents
+=================
+
+ID   Title                    Author             Created           Comments
+---------------------------------------------------------------------------
+1    Implemented new feature  9710b86ba12c4f2e…  2025-01-15 14:32         3
+2    Fixed bug in parser      8f3a21c9d84e927b…  2025-01-14 09:15         1
+</pre></div>
+</div>
+<p>Use <code class="docutils literal notranslate"><span class="pre">--scope</span> <span class="pre">completed</span></code> to view completed work documents, or <code class="docutils literal notranslate"><span class="pre">--scope</span> <span class="pre">all</span></code> to see both active and completed.</p>
+<p><strong>Viewing a Work Document</strong></p>
+<p>To view a specific work document with all its comments:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rngit work rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo view -d 1
+
+Implement new feature (active #1)
+=================================
+Author   : 9710b86ba12c42d1d8f30f74fe509286
+Status   : active
+Created  : 2026-05-05 15:11:11
+Edited   : 2026-05-05 18:22:11
+Format   : markdown
+Updates  : 0
+
+This work document tracks the implementation of the new feature...
+
+Updates
+=======
+
+#1 by 9710b86ba12c42d1d8f30f74fe509286 at 2026-05-05 15:38:37
+-------------------------------------------------------------
+Initial analysis complete
+</pre></div>
+</div>
+<p><strong>Creating Work Documents</strong></p>
+<p>To create a new work document:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rngit work rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo create --title &quot;Investigate performance issue&quot;
+</pre></div>
+</div>
+<p>This will open your configured <code class="docutils literal notranslate"><span class="pre">$EDITOR</span></code> to compose the document content. Save and exit to create the document, or save an empty document to cancel.</p>
+<p><strong>Editing Work Documents</strong></p>
+<p>To edit an existing work document:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rngit work rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo edit -d 1
+</pre></div>
+</div>
+<p>This fetches the current content, opens it in your editor, and sends any changes back to the node.</p>
+<p><strong>Adding Comments</strong></p>
+<p>To add an update to a work document:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rngit work rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo update -d 1
+</pre></div>
+</div>
+<p>This opens your editor to compose the update.</p>
+<p><strong>Completing Work Documents</strong></p>
+<p>To mark a work document as completed (moving it from <code class="docutils literal notranslate"><span class="pre">active</span></code> to <code class="docutils literal notranslate"><span class="pre">completed</span></code>):</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rngit work rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo complete -d 1
+
+Work document #1 completed
+</pre></div>
+</div>
+<p><strong>Activating Work Documents</strong></p>
+<p>To mark a work document as active (moving it from <code class="docutils literal notranslate"><span class="pre">completed</span></code> to <code class="docutils literal notranslate"><span class="pre">active</span></code>):</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rngit work rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo activate -d 1
+
+Work document #1 activated
+</pre></div>
+</div>
+<p><strong>Deleting Work Documents</strong></p>
+<p>To delete a work document and all its comments:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rngit work rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo delete -id 1
+
+Are you sure you want to delete active work document #1? [y/N]: y
+Work document #1 deleted
+</pre></div>
+</div>
+<p><strong>Permissions</strong></p>
+<p>Users can view work documents and updates if the have <code class="docutils literal notranslate"><span class="pre">read</span></code> permission for the repository. If users have <code class="docutils literal notranslate"><span class="pre">read</span></code> and <code class="docutils literal notranslate"><span class="pre">interact</span></code>, they can also post updates/comments on existing work documents. Work document management requires having <code class="docutils literal notranslate"><span class="pre">write</span></code> and <code class="docutils literal notranslate"><span class="pre">interact</span></code> permission to the repository. These permissions are configured the same way as any other repository permissions. In the config file or <code class="docutils literal notranslate"><span class="pre">.allowed</span></code> files, use <code class="docutils literal notranslate"><span class="pre">i:target</span></code> to grant work document interaction rights:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span># In .allowed file or config
+i:all          # Allow everyone
+i:9710b86...   # Allow specific identity
+i:none         # Deny everyone
+</pre></div>
+</div>
+<p><strong>Author Verification</strong></p>
+<p>Users can only edit or delete work documents and updates they created. The author is cryptographically verified from the interacting link’s <code class="docutils literal notranslate"><span class="pre">remote_identity</span></code>.</p>
+<p><strong>Storage Format</strong></p>
+<p>Work documents are stored in a <code class="docutils literal notranslate"><span class="pre">repo_name.work</span></code> directory next to the repository, containing:</p>
+<ul class="simple">
+<li><p><code class="docutils literal notranslate"><span class="pre">active/</span></code> - Active work documents</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">completed/</span></code> - Completed work documents</p></li>
+</ul>
+<p>Each document is a numbered directory containing:</p>
+<ul class="simple">
+<li><p><code class="docutils literal notranslate"><span class="pre">root</span></code> - The work document content and metadata (msgpack format)</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">N</span></code> - Numbered comment files (msgpack format)</p></li>
+</ul>
+<p><strong>Nomad Network Interface</strong></p>
+<p>When the Nomad Network page node is enabled, work documents are viewable through the web interface. The work page lists all documents with their status, and clicking a document shows its full content and updates.</p>
+<p><strong>All Command-Line Options (rngit work)</strong></p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rngit work [-h] [--config CONFIG] [--rnsconfig RNSCONFIG]
+                  [-i PATH] [--scope SCOPE] [-t TITLE] [-d ID] [-v]
+                  [-q] [--version]
+                  [repository] [operation]
+
+Reticulum Git Work Document Manager
+
+positional arguments:
+  repository            URL of remote repository
+  operation             list, view, create, edit, delete, update or complete
+
+options:
+  -h, --help            show this help message and exit
+  --config CONFIG       path to alternative config directory
+  --rnsconfig RNSCONFIG
+                        path to alternative Reticulum config directory
+  -i, --identity PATH   path to identity
+  --scope SCOPE         document scope: active, completed or all
+  -t, --title TITLE     document title for create
+  -d, --id ID           document ID
+  -v, --verbose
+  -q, --quiet
+  --version             show program&#39;s version number and exit
+</pre></div>
+</div>
+</section>
+</section>
+
+        </article>
+      </div>
+      <footer>
+        
+        <div class="related-pages">
+          <a class="next-page" href="support.html">
+              <div class="page-info">
+                <div class="context">
+                  <span>Next</span>
+                </div>
+                <div class="title">Support Reticulum</div>
+              </div>
+              <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
+            </a>
+          <a class="prev-page" href="networks.html">
+              <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
+              <div class="page-info">
+                <div class="context">
+                  <span>Previous</span>
+                </div>
+                
+                <div class="title">Building Networks</div>
+                
+              </div>
+            </a>
+        </div>
+        <div class="bottom-of-page">
+          <div class="left-details">
+            <div class="copyright">
+                Copyright &#169; 2025, Mark Qvist
+            </div>
+            Generated with <a href="https://www.sphinx-doc.org/">Sphinx</a> and 
+            <a href="https://github.com/pradyunsg/furo">Furo</a>
+            
+          </div>
+          <div class="right-details">
+            
+          </div>
+        </div>
+        
+      </footer>
+    </div>
+    <aside class="toc-drawer">
+      
+      
+      <div class="toc-sticky toc-scroll">
+        <div class="toc-title-container">
+          <span class="toc-title">
+            On this page
+          </span>
+        </div>
+        <div class="toc-tree-container">
+          <div class="toc-tree">
+            <ul>
+<li><a class="reference internal" href="#">Git Over Reticulum</a><ul>
+<li><a class="reference internal" href="#the-rngit-utility">The rngit Utility</a></li>
+<li><a class="reference internal" href="#repository-structure">Repository Structure</a></li>
+<li><a class="reference internal" href="#serving-pages-over-nomad-network">Serving Pages Over Nomad Network</a></li>
+<li><a class="reference internal" href="#formatting-syntax-highlighting">Formatting &amp; Syntax Highlighting</a></li>
+<li><a class="reference internal" href="#customizing-templates">Customizing Templates</a></li>
+<li><a class="reference internal" href="#release-management">Release Management</a></li>
+<li><a class="reference internal" href="#work-documents">Work Documents</a></li>
+</ul>
+</li>
+</ul>
+
+          </div>
+        </div>
+      </div>
+      
+      
+    </aside>
+  </div>
+</div><script src="_static/documentation_options.js?v=590429e0"></script>
+    <script src="_static/doctools.js?v=9bcbadda"></script>
+    <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
+    <script src="_static/scripts/furo.js?v=46bd48cc"></script>
+    <script src="_static/clipboard.min.js?v=a7894cd8"></script>
+    <script src="_static/copybutton.js?v=f281be69"></script>
+    </body>
+</html>

docs/manual/hardware.html

@@ -7,7 +7,7 @@
         <link rel="prefetch" href="_static/rns_logo_512.png" as="image">
 
     <!-- Generated with Sphinx 8.2.3 and Furo 2025.09.25.dev1 -->
-        <title>Communications Hardware - Reticulum Network Stack 1.0.3 documentation</title>
+        <title>Communications Hardware - Reticulum Network Stack 1.2.3 documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d111a655" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=580074bf" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
@@ -180,7 +180,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 1.0.3 documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 1.2.3 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -204,7 +204,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 1.0.3 documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 1.2.3 documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@@ -215,13 +215,17 @@
   <ul class="current">
 <li class="toctree-l1"><a class="reference internal" href="whatis.html">What is Reticulum?</a></li>
 <li class="toctree-l1"><a class="reference internal" href="gettingstartedfast.html">Getting Started Fast</a></li>
+<li class="toctree-l1"><a class="reference internal" href="zen.html">Zen of Reticulum</a></li>
+<li class="toctree-l1"><a class="reference internal" href="software.html">Programs Using Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
 <li class="toctree-l1 current current-page"><a class="current reference internal" href="#">Communications Hardware</a></li>
 <li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
 <li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks</a></li>
+<li class="toctree-l1"><a class="reference internal" href="git.html">Git Over Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a></li>
+<li class="toctree-l1"><a class="reference internal" href="license.html">Reticulum License</a></li>
 </ul>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="reference.html">API Reference</a></li>
@@ -671,7 +675,7 @@ can be used with Reticulum. This includes virtual software modems such as
       
     </aside>
   </div>
-</div><script src="_static/documentation_options.js?v=baaebd52"></script>
+</div><script src="_static/documentation_options.js?v=590429e0"></script>
     <script src="_static/doctools.js?v=9bcbadda"></script>
     <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="_static/scripts/furo.js?v=46bd48cc"></script>

docs/manual/index.html

@@ -7,7 +7,7 @@
         <link rel="prefetch" href="_static/rns_logo_512.png" as="image">
 
     <!-- Generated with Sphinx 8.2.3 and Furo 2025.09.25.dev1 -->
-        <title>Reticulum Network Stack 1.0.3 documentation</title>
+        <title>Reticulum Network Stack 1.2.3 documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d111a655" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=580074bf" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
@@ -180,7 +180,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="#"><div class="brand">Reticulum Network Stack 1.0.3 documentation</div></a>
+      <a href="#"><div class="brand">Reticulum Network Stack 1.2.3 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -204,7 +204,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 1.0.3 documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 1.2.3 documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@@ -215,13 +215,17 @@
   <ul>
 <li class="toctree-l1"><a class="reference internal" href="whatis.html">What is Reticulum?</a></li>
 <li class="toctree-l1"><a class="reference internal" href="gettingstartedfast.html">Getting Started Fast</a></li>
+<li class="toctree-l1"><a class="reference internal" href="zen.html">Zen of Reticulum</a></li>
+<li class="toctree-l1"><a class="reference internal" href="software.html">Programs Using Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
 <li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
 <li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks</a></li>
+<li class="toctree-l1"><a class="reference internal" href="git.html">Git Over Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a></li>
+<li class="toctree-l1"><a class="reference internal" href="license.html">Reticulum License</a></li>
 </ul>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="reference.html">API Reference</a></li>
@@ -270,10 +274,10 @@ to participate in the development of Reticulum itself.</p>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="whatis.html">What is Reticulum?</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="whatis.html#current-status">Current Status</a></li>
+<li class="toctree-l2"><a class="reference internal" href="whatis.html#reference-implementation">Reference Implementation</a></li>
 <li class="toctree-l2"><a class="reference internal" href="whatis.html#what-does-reticulum-offer">What does Reticulum Offer?</a></li>
 <li class="toctree-l2"><a class="reference internal" href="whatis.html#where-can-reticulum-be-used">Where can Reticulum be Used?</a></li>
 <li class="toctree-l2"><a class="reference internal" href="whatis.html#interface-types-and-devices">Interface Types and Devices</a></li>
-<li class="toctree-l2"><a class="reference internal" href="whatis.html#caveat-emptor">Caveat Emptor</a></li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="gettingstartedfast.html">Getting Started Fast</a><ul>
@@ -281,22 +285,23 @@ to participate in the development of Reticulum itself.</p>
 <li class="toctree-l3"><a class="reference internal" href="gettingstartedfast.html#resolving-dependency-installation-issues">Resolving Dependency &amp; Installation Issues</a></li>
 </ul>
 </li>
-<li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#try-using-a-reticulum-based-program">Try Using a Reticulum-based Program</a><ul>
-<li class="toctree-l3"><a class="reference internal" href="gettingstartedfast.html#remote-shell">Remote Shell</a></li>
-<li class="toctree-l3"><a class="reference internal" href="gettingstartedfast.html#nomad-network">Nomad Network</a></li>
-<li class="toctree-l3"><a class="reference internal" href="gettingstartedfast.html#sideband">Sideband</a></li>
-<li class="toctree-l3"><a class="reference internal" href="gettingstartedfast.html#meshchat">MeshChat</a></li>
-</ul>
-</li>
+<li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#try-using-a-reticulum-based-program">Try Using a Reticulum-based Program</a></li>
 <li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#using-the-included-utilities">Using the Included Utilities</a></li>
 <li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#creating-a-network-with-reticulum">Creating a Network With Reticulum</a></li>
-<li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#connecting-reticulum-instances-over-the-internet">Connecting Reticulum Instances Over the Internet</a></li>
-<li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#connect-to-the-public-testnet">Connect to the Public Testnet</a></li>
+<li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#bootstrapping-connectivity">Bootstrapping Connectivity</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="gettingstartedfast.html#finding-your-way">Finding Your Way</a></li>
+<li class="toctree-l3"><a class="reference internal" href="gettingstartedfast.html#build-personal-infrastructure">Build Personal Infrastructure</a></li>
+<li class="toctree-l3"><a class="reference internal" href="gettingstartedfast.html#mixing-strategies">Mixing Strategies</a></li>
+<li class="toctree-l3"><a class="reference internal" href="gettingstartedfast.html#network-health-responsibility">Network Health &amp; Responsibility</a></li>
+<li class="toctree-l3"><a class="reference internal" href="gettingstartedfast.html#contributing-to-the-global-ret">Contributing to the Global Ret</a></li>
+</ul>
+</li>
+<li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#connect-to-the-distributed-backbone">Connect to the Distributed Backbone</a></li>
 <li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#hosting-public-entrypoints">Hosting Public Entrypoints</a></li>
+<li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#connecting-reticulum-instances-over-the-internet">Connecting Reticulum Instances Over the Internet</a></li>
 <li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#adding-radio-interfaces">Adding Radio Interfaces</a></li>
 <li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#creating-and-using-custom-interfaces">Creating and Using Custom Interfaces</a></li>
 <li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#develop-a-program-with-reticulum">Develop a Program with Reticulum</a></li>
-<li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#participate-in-reticulum-development">Participate in Reticulum Development</a></li>
 <li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#platform-specific-install-notes">Platform-Specific Install Notes</a><ul>
 <li class="toctree-l3"><a class="reference internal" href="gettingstartedfast.html#android">Android</a></li>
 <li class="toctree-l3"><a class="reference internal" href="gettingstartedfast.html#arm64">ARM64</a></li>
@@ -312,6 +317,90 @@ to participate in the development of Reticulum itself.</p>
 <li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#pure-python-reticulum">Pure-Python Reticulum</a></li>
 </ul>
 </li>
+<li class="toctree-l1"><a class="reference internal" href="zen.html">Zen of Reticulum</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="zen.html#the-illusion-of-the-center">The Illusion Of The Center</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="zen.html#fallacy-of-the-cloud">Fallacy Of The Cloud</a></li>
+<li class="toctree-l3"><a class="reference internal" href="zen.html#decentralization-or-uncentralizability">Decentralization Or Uncentralizability?</a></li>
+<li class="toctree-l3"><a class="reference internal" href="zen.html#death-to-the-address">Death To The Address</a></li>
+</ul>
+</li>
+<li class="toctree-l2"><a class="reference internal" href="zen.html#physics-of-trust">Physics Of Trust</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="zen.html#hostile-environments">Hostile Environments</a></li>
+<li class="toctree-l3"><a class="reference internal" href="zen.html#encryption-is-not-a-feature">Encryption Is Not A Feature</a></li>
+<li class="toctree-l3"><a class="reference internal" href="zen.html#zero-trust-architectures">Zero-Trust Architectures</a></li>
+</ul>
+</li>
+<li class="toctree-l2"><a class="reference internal" href="zen.html#merits-of-scarcity">Merits Of Scarcity</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="zen.html#the-bandwidth-fallacy">The Bandwidth Fallacy</a></li>
+<li class="toctree-l3"><a class="reference internal" href="zen.html#cost-of-a-byte">Cost Of A Byte</a></li>
+<li class="toctree-l3"><a class="reference internal" href="zen.html#flow-time">Flow &amp; Time</a></li>
+<li class="toctree-l3"><a class="reference internal" href="zen.html#liberation-from-limits">Liberation From Limits</a></li>
+</ul>
+</li>
+<li class="toctree-l2"><a class="reference internal" href="zen.html#sovereignty-through-infrastructure">Sovereignty Through Infrastructure</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="zen.html#a-carrier-grade-fallacy">A Carrier-Grade Fallacy</a></li>
+<li class="toctree-l3"><a class="reference internal" href="zen.html#personal-infrastructure">Personal Infrastructure</a></li>
+<li class="toctree-l3"><a class="reference internal" href="zen.html#the-ability-to-disconnect">The Ability To Disconnect</a></li>
+</ul>
+</li>
+<li class="toctree-l2"><a class="reference internal" href="zen.html#identity-and-nomadism">Identity and Nomadism</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="zen.html#portable-existence">Portable Existence</a></li>
+<li class="toctree-l3"><a class="reference internal" href="zen.html#roaming-nodes">Roaming Nodes</a></li>
+<li class="toctree-l3"><a class="reference internal" href="zen.html#announcing-presence">Announcing Presence</a></li>
+<li class="toctree-l3"><a class="reference internal" href="zen.html#anchor-in-the-flow">Anchor In The Flow</a></li>
+</ul>
+</li>
+<li class="toctree-l2"><a class="reference internal" href="zen.html#ethics-of-the-tool">Ethics Of The Tool</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="zen.html#the-harm-principle">The Harm Principle</a></li>
+<li class="toctree-l3"><a class="reference internal" href="zen.html#public-domain-protocol">Public Domain Protocol</a></li>
+<li class="toctree-l3"><a class="reference internal" href="zen.html#preserving-human-agency">Preserving Human Agency</a></li>
+</ul>
+</li>
+<li class="toctree-l2"><a class="reference internal" href="zen.html#design-patterns-for-post-ip-systems">Design Patterns For Post-IP Systems</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="zen.html#store-forward">Store &amp; Forward</a></li>
+<li class="toctree-l3"><a class="reference internal" href="zen.html#naming-is-power">Naming Is Power</a></li>
+<li class="toctree-l3"><a class="reference internal" href="zen.html#the-interface-is-the-medium">The Interface Is The Medium</a></li>
+<li class="toctree-l3"><a class="reference internal" href="zen.html#emergent-patterns">Emergent Patterns</a></li>
+</ul>
+</li>
+<li class="toctree-l2"><a class="reference internal" href="zen.html#fabric-of-the-independent">Fabric Of The Independent</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="zen.html#the-work-is-finished">The Work Is Finished</a></li>
+<li class="toctree-l3"><a class="reference internal" href="zen.html#open-sky">Open Sky</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="software.html">Programs Using Reticulum</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="software.html#programs-utilities">Programs &amp; Utilities</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="software.html#remote-shell">Remote Shell</a></li>
+<li class="toctree-l3"><a class="reference internal" href="software.html#nomad-network">Nomad Network</a></li>
+<li class="toctree-l3"><a class="reference internal" href="software.html#rns-page-node">RNS Page Node</a></li>
+<li class="toctree-l3"><a class="reference internal" href="software.html#retipedia">Retipedia</a></li>
+<li class="toctree-l3"><a class="reference internal" href="software.html#sideband">Sideband</a></li>
+<li class="toctree-l3"><a class="reference internal" href="software.html#meshchatx">MeshChatX</a></li>
+<li class="toctree-l3"><a class="reference internal" href="software.html#meshchat">MeshChat</a></li>
+<li class="toctree-l3"><a class="reference internal" href="software.html#columba">Columba</a></li>
+<li class="toctree-l3"><a class="reference internal" href="software.html#reticulum-relay-chat">Reticulum Relay Chat</a></li>
+<li class="toctree-l3"><a class="reference internal" href="software.html#retibbs">RetiBBS</a></li>
+<li class="toctree-l3"><a class="reference internal" href="software.html#rbrowser">RBrowser</a></li>
+<li class="toctree-l3"><a class="reference internal" href="software.html#reticulum-network-telephone">Reticulum Network Telephone</a></li>
+<li class="toctree-l3"><a class="reference internal" href="software.html#lxst-phone">LXST Phone</a></li>
+<li class="toctree-l3"><a class="reference internal" href="software.html#lxmfy">LXMFy</a></li>
+<li class="toctree-l3"><a class="reference internal" href="software.html#lxmf-interactive-client">LXMF Interactive Client</a></li>
+<li class="toctree-l3"><a class="reference internal" href="software.html#rns-filesync">RNS FileSync</a></li>
+<li class="toctree-l3"><a class="reference internal" href="software.html#micron-parser-js">Micron Parser JS</a></li>
+<li class="toctree-l3"><a class="reference internal" href="software.html#rnmon">RNMon</a></li>
+</ul>
+</li>
+<li class="toctree-l2"><a class="reference internal" href="software.html#protocols">Protocols</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="software.html#lxmf">LXMF</a></li>
+<li class="toctree-l3"><a class="reference internal" href="software.html#id17">LXST</a></li>
+<li class="toctree-l3"><a class="reference internal" href="software.html#rrc">RRC</a></li>
+</ul>
+</li>
+<li class="toctree-l2"><a class="reference internal" href="software.html#interface-modules-connectivity-resources">Interface Modules &amp; Connectivity Resources</a></li>
+</ul>
+</li>
 <li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="using.html#configuration-data">Configuration &amp; Data</a></li>
 <li class="toctree-l2"><a class="reference internal" href="using.html#included-utility-programs">Included Utility Programs</a><ul>
@@ -321,11 +410,20 @@ to participate in the development of Reticulum itself.</p>
 <li class="toctree-l3"><a class="reference internal" href="using.html#the-rnpath-utility">The rnpath Utility</a></li>
 <li class="toctree-l3"><a class="reference internal" href="using.html#the-rnprobe-utility">The rnprobe Utility</a></li>
 <li class="toctree-l3"><a class="reference internal" href="using.html#the-rncp-utility">The rncp Utility</a></li>
+<li class="toctree-l3"><a class="reference internal" href="using.html#the-rngit-utility">The rngit Utility</a></li>
 <li class="toctree-l3"><a class="reference internal" href="using.html#the-rnx-utility">The rnx Utility</a></li>
+<li class="toctree-l3"><a class="reference internal" href="using.html#the-rnsh-utility">The rnsh Utility</a></li>
 <li class="toctree-l3"><a class="reference internal" href="using.html#the-rnodeconf-utility">The rnodeconf Utility</a></li>
 </ul>
 </li>
+<li class="toctree-l2"><a class="reference internal" href="using.html#discovering-interfaces">Discovering Interfaces</a></li>
 <li class="toctree-l2"><a class="reference internal" href="using.html#remote-management">Remote Management</a></li>
+<li class="toctree-l2"><a class="reference internal" href="using.html#blackhole-management">Blackhole Management</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="using.html#local-blackhole-management">Local Blackhole Management</a></li>
+<li class="toctree-l3"><a class="reference internal" href="using.html#automated-list-sourcing">Automated List Sourcing</a></li>
+<li class="toctree-l3"><a class="reference internal" href="using.html#publishing-blackhole-lists">Publishing Blackhole Lists</a></li>
+</ul>
+</li>
 <li class="toctree-l2"><a class="reference internal" href="using.html#improving-system-configuration">Improving System Configuration</a><ul>
 <li class="toctree-l3"><a class="reference internal" href="using.html#fixed-serial-port-names">Fixed Serial Port Names</a></li>
 <li class="toctree-l3"><a class="reference internal" href="using.html#reticulum-as-a-system-service">Reticulum as a System Service</a></li>
@@ -350,6 +448,13 @@ to participate in the development of Reticulum itself.</p>
 <li class="toctree-l3"><a class="reference internal" href="understanding.html#resources">Resources</a></li>
 </ul>
 </li>
+<li class="toctree-l2"><a class="reference internal" href="understanding.html#network-identities">Network Identities</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="understanding.html#conceptual-overview">Conceptual Overview</a></li>
+<li class="toctree-l3"><a class="reference internal" href="understanding.html#current-usage">Current Usage</a></li>
+<li class="toctree-l3"><a class="reference internal" href="understanding.html#future-implications">Future Implications</a></li>
+<li class="toctree-l3"><a class="reference internal" href="understanding.html#creating-and-using-a-network-identity">Creating and Using a Network Identity</a></li>
+</ul>
+</li>
 <li class="toctree-l2"><a class="reference internal" href="understanding.html#reference-setup">Reference Setup</a></li>
 <li class="toctree-l2"><a class="reference internal" href="understanding.html#protocol-specifics">Protocol Specifics</a><ul>
 <li class="toctree-l3"><a class="reference internal" href="understanding.html#packet-prioritisation">Packet Prioritisation</a></li>
@@ -394,26 +499,44 @@ to participate in the development of Reticulum itself.</p>
 <li class="toctree-l2"><a class="reference internal" href="interfaces.html#pipe-interface">Pipe Interface</a></li>
 <li class="toctree-l2"><a class="reference internal" href="interfaces.html#kiss-interface">KISS Interface</a></li>
 <li class="toctree-l2"><a class="reference internal" href="interfaces.html#ax-25-kiss-interface">AX.25 KISS Interface</a></li>
+<li class="toctree-l2"><a class="reference internal" href="interfaces.html#discoverable-interfaces">Discoverable Interfaces</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="interfaces.html#enabling-discovery">Enabling Discovery</a></li>
+<li class="toctree-l3"><a class="reference internal" href="interfaces.html#discovery-parameters">Discovery Parameters</a></li>
+<li class="toctree-l3"><a class="reference internal" href="interfaces.html#interface-modes">Interface Modes</a></li>
+<li class="toctree-l3"><a class="reference internal" href="interfaces.html#security-considerations">Security Considerations</a></li>
+<li class="toctree-l3"><a class="reference internal" href="interfaces.html#example-configuration">Example Configuration</a></li>
+</ul>
+</li>
 <li class="toctree-l2"><a class="reference internal" href="interfaces.html#common-interface-options">Common Interface Options</a></li>
-<li class="toctree-l2"><a class="reference internal" href="interfaces.html#interface-modes">Interface Modes</a></li>
+<li class="toctree-l2"><a class="reference internal" href="interfaces.html#interfaces-modes">Interface Modes</a></li>
 <li class="toctree-l2"><a class="reference internal" href="interfaces.html#announce-rate-control">Announce Rate Control</a></li>
 <li class="toctree-l2"><a class="reference internal" href="interfaces.html#new-destination-rate-limiting">New Destination Rate Limiting</a></li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks</a><ul>
-<li class="toctree-l2"><a class="reference internal" href="networks.html#concepts-overview">Concepts &amp; Overview</a></li>
-<li class="toctree-l2"><a class="reference internal" href="networks.html#example-scenarios">Example Scenarios</a><ul>
-<li class="toctree-l3"><a class="reference internal" href="networks.html#interconnected-lora-sites">Interconnected LoRa Sites</a></li>
-<li class="toctree-l3"><a class="reference internal" href="networks.html#bridging-over-the-internet">Bridging Over the Internet</a></li>
-<li class="toctree-l3"><a class="reference internal" href="networks.html#growth-and-convergence">Growth and Convergence</a></li>
+<li class="toctree-l2"><a class="reference internal" href="networks.html#concepts-overview">Concepts &amp; Overview</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="networks.html#introductory-considerations">Introductory Considerations</a></li>
+<li class="toctree-l3"><a class="reference internal" href="networks.html#destinations-not-addresses">Destinations, Not Addresses</a></li>
+<li class="toctree-l3"><a class="reference internal" href="networks.html#transport-nodes-and-instances">Transport Nodes and Instances</a></li>
+<li class="toctree-l3"><a class="reference internal" href="networks.html#trustless-networking">Trustless Networking</a></li>
+<li class="toctree-l3"><a class="reference internal" href="networks.html#heterogeneous-connectivity">Heterogeneous Connectivity</a></li>
 </ul>
 </li>
 </ul>
 </li>
+<li class="toctree-l1"><a class="reference internal" href="git.html">Git Over Reticulum</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="git.html#the-rngit-utility">The rngit Utility</a></li>
+<li class="toctree-l2"><a class="reference internal" href="git.html#repository-structure">Repository Structure</a></li>
+<li class="toctree-l2"><a class="reference internal" href="git.html#serving-pages-over-nomad-network">Serving Pages Over Nomad Network</a></li>
+<li class="toctree-l2"><a class="reference internal" href="git.html#formatting-syntax-highlighting">Formatting &amp; Syntax Highlighting</a></li>
+<li class="toctree-l2"><a class="reference internal" href="git.html#customizing-templates">Customizing Templates</a></li>
+<li class="toctree-l2"><a class="reference internal" href="git.html#release-management">Release Management</a></li>
+<li class="toctree-l2"><a class="reference internal" href="git.html#work-documents">Work Documents</a></li>
+</ul>
+</li>
 <li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="support.html#donations">Donations</a></li>
 <li class="toctree-l2"><a class="reference internal" href="support.html#provide-feedback">Provide Feedback</a></li>
-<li class="toctree-l2"><a class="reference internal" href="support.html#contribute-code">Contribute Code</a></li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a><ul>
@@ -430,6 +553,7 @@ to participate in the development of Reticulum itself.</p>
 <li class="toctree-l2"><a class="reference internal" href="examples.html#custom-interfaces">Custom Interfaces</a></li>
 </ul>
 </li>
+<li class="toctree-l1"><a class="reference internal" href="license.html">Reticulum License</a></li>
 </ul>
 </div>
 <div class="toctree-wrapper compound">
@@ -520,7 +644,7 @@ to participate in the development of Reticulum itself.</p>
       
     </aside>
   </div>
-</div><script src="_static/documentation_options.js?v=baaebd52"></script>
+</div><script src="_static/documentation_options.js?v=590429e0"></script>
     <script src="_static/doctools.js?v=9bcbadda"></script>
     <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="_static/scripts/furo.js?v=46bd48cc"></script>

docs/manual/interfaces.html

@@ -7,7 +7,7 @@
         <link rel="prefetch" href="_static/rns_logo_512.png" as="image">
 
     <!-- Generated with Sphinx 8.2.3 and Furo 2025.09.25.dev1 -->
-        <title>Configuring Interfaces - Reticulum Network Stack 1.0.3 documentation</title>
+        <title>Configuring Interfaces - Reticulum Network Stack 1.2.3 documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d111a655" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=580074bf" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
@@ -180,7 +180,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 1.0.3 documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 1.2.3 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -204,7 +204,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 1.0.3 documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 1.2.3 documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@@ -215,13 +215,17 @@
   <ul class="current">
 <li class="toctree-l1"><a class="reference internal" href="whatis.html">What is Reticulum?</a></li>
 <li class="toctree-l1"><a class="reference internal" href="gettingstartedfast.html">Getting Started Fast</a></li>
+<li class="toctree-l1"><a class="reference internal" href="zen.html">Zen of Reticulum</a></li>
+<li class="toctree-l1"><a class="reference internal" href="software.html">Programs Using Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
 <li class="toctree-l1 current current-page"><a class="current reference internal" href="#">Configuring Interfaces</a></li>
 <li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks</a></li>
+<li class="toctree-l1"><a class="reference internal" href="git.html">Git Over Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a></li>
+<li class="toctree-l1"><a class="reference internal" href="license.html">Reticulum License</a></li>
 </ul>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="reference.html">API Reference</a></li>
@@ -562,6 +566,7 @@ software-based soundmodems. To do this, use the <code class="docutils literal no
 <span class="w">  </span><span class="na">kiss_framing</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">True</span>
 <span class="w">  </span><span class="na">target_host</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">127.0.0.1</span>
 <span class="w">  </span><span class="na">target_port</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">8001</span>
+<span class="w">  </span><span class="na">fixed_mtu</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">500</span>
 </pre></div>
 </div>
 <p><strong>Caution!</strong> Only use the KISS framing option when connecting to external devices
@@ -570,6 +575,8 @@ and programs like soundmodems and similar over TCP. When using the
 never enable <code class="docutils literal notranslate"><span class="pre">kiss_framing</span></code>, since this will disable internal reliability and
 recovery mechanisms that greatly improves performance over unreliable and
 intermittent TCP links.</p>
+<p>For KISS devices that need only supports a particular MTU, you can use the
+<code class="docutils literal notranslate"><span class="pre">fixed_mtu</span></code> option.</p>
 <div class="admonition note">
 <p class="admonition-title">Note</p>
 <p>The TCP interfaces support tunneling over I2P, but to do so reliably,
@@ -1073,6 +1080,182 @@ relevant regulation for your location, and to make decisions accordingly.</p>
 </pre></div>
 </div>
 </section>
+<section id="discoverable-interfaces">
+<span id="interfaces-discoverable"></span><h2>Discoverable Interfaces<a class="headerlink" href="#discoverable-interfaces" title="Link to this heading">¶</a></h2>
+<p>Reticulum includes a powerful system for publishing your local interfaces to the wider network, allowing other peers to <a class="reference internal" href="using.html#using-interface-discovery"><span class="std std-ref">discover, validate, and automatically connect to them</span></a>. This feature is particularly useful for creating decentralized networks where peers can dynamically find entrypoints, such as public Internet gateways or local radio access points, without relying on static configuration files or centralized directories.</p>
+<p>When an interface is made <strong>discoverable</strong>, your Reticulum instance will periodically broadcast an announce packet containing the connection details and parameters required for other peers to establish a connection. These announces are propagated over the network using the standard Reticulum announce mechanism using the <code class="docutils literal notranslate"><span class="pre">rnstransport.discovery.interface</span></code> destination type.</p>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p>To use the interface discovery functionality, the <code class="docutils literal notranslate"><span class="pre">LXMF</span></code> module must be installed in your Python environment. You can install it using pip:</p>
+<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>pip<span class="w"> </span>install<span class="w"> </span>lxmf
+</pre></div>
+</div>
+</div>
+<section id="enabling-discovery">
+<h3>Enabling Discovery<a class="headerlink" href="#enabling-discovery" title="Link to this heading">¶</a></h3>
+<p>Interface discovery is enabled on a per-interface basis. To make a specific interface discoverable, you must add the <code class="docutils literal notranslate"><span class="pre">discoverable</span></code> option to that interface’s configuration block and set it to <code class="docutils literal notranslate"><span class="pre">yes</span></code>.</p>
+<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[[My Public Gateway]]</span>
+<span class="w">  </span><span class="na">type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">BackboneInterface</span>
+<span class="w">  </span><span class="na">...</span>
+<span class="w">  </span><span class="na">discoverable</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span>
+</pre></div>
+</div>
+<p>Once enabled, Reticulum will automatically handle the generation, signing, stamping, and broadcasting of the discovery announces. It is not <em>required</em> to enable Transport to publish interface discovery information, but for most use cases where you want others to connect to you, you will likely want <code class="docutils literal notranslate"><span class="pre">enable_transport</span></code> set to <code class="docutils literal notranslate"><span class="pre">yes</span></code> in the <code class="docutils literal notranslate"><span class="pre">[reticulum]</span></code> section of your configuration.</p>
+</section>
+<section id="discovery-parameters">
+<h3>Discovery Parameters<a class="headerlink" href="#discovery-parameters" title="Link to this heading">¶</a></h3>
+<p>When <code class="docutils literal notranslate"><span class="pre">discoverable</span></code> is enabled, a variety of additional options become available to control how the interface is presented to the network. These parameters allow you to fine-tune the metadata, security requirements, and visibility of your interface.</p>
+<p><strong>Basic Metadata</strong></p>
+<dl class="simple">
+<dt><code class="docutils literal notranslate"><span class="pre">discovery_name</span></code></dt><dd><p>A human-readable name for the interface. This name will be displayed to users on remote systems when they list discovered interfaces. If not specified, the interface name (the section header) will be used.</p>
+</dd>
+<dt><code class="docutils literal notranslate"><span class="pre">announce_interval</span></code></dt><dd><p>The interval in minutes between successive discovery announces for this interface. Default is 360 minutes (6 hours). For stable, long-running infrastructure, higher intervals (12 to 22 hours) are usually sufficient and reduce network load. Minimum allowed value is 5 minutes (but expect to have your announces throttled if using intervals below one hour).</p>
+</dd>
+</dl>
+<p><strong>Connectivity Specification</strong></p>
+<dl>
+<dt><code class="docutils literal notranslate"><span class="pre">reachable_on</span></code></dt><dd><p>Specifies the address that remote peers should use to connect to this interface.</p>
+<ul class="simple">
+<li><p>For TCP and Backbone interfaces, this is typically the public IP address or hostname. Do not include the port, this is fetched automatically from the interface.</p></li>
+<li><p>For I2P interfaces, this is usually the I2P <code class="docutils literal notranslate"><span class="pre">b32</span></code> address. This value is fetched automatically from the <code class="docutils literal notranslate"><span class="pre">I2PInterface</span></code> once it is up and connected to the I2P network, so you should not set this manually, unless you absolutely know what you’re doing.</p></li>
+</ul>
+<p><strong>Dynamic Resolution:</strong> This option also accepts a path to an external executable script or binary. If a path is provided, Reticulum will execute the script and use its <code class="docutils literal notranslate"><span class="pre">stdout</span></code> as the reachability address. This is useful for devices behind dynamic DNS, NATs, or complex cloud environments where the external IP is not known locally. The script must simply print the address to stdout and exit.</p>
+</dd>
+</dl>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p>When using an executable script for <code class="docutils literal notranslate"><span class="pre">reachable_on</span></code>, Reticulum expects the script to output only the IP address or hostname to <code class="docutils literal notranslate"><span class="pre">stdout</span></code>, followed by a newline character. Any additional output or errors may cause the resolution to fail. Ensure the script has executable permissions and is robust against temporary network failures.</p>
+</div>
+<p>A minimal example of a script that resolves the externally available, public IP of an internet-connected system could look like this:</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="ch">#!/bin/bash</span>
+curl<span class="w"> </span>-s<span class="w"> </span>ip.me
+<span class="nb">exit</span><span class="w"> </span><span class="nv">$?</span>
+</pre></div>
+</div>
+<p>On a real system, you should make the script robust enough to deal with intermittent Internet or service failures, such that the script <em>always</em> returns a sensible value, or if not possible at least exits with a non-zero exit return code, so Reticulum knows the output is invalid.</p>
+<p><strong>Security &amp; Cost</strong></p>
+<dl class="simple">
+<dt><code class="docutils literal notranslate"><span class="pre">discovery_stamp_value</span></code></dt><dd><p>Defines the proof-of-work difficulty for the cryptographic stamp included in the announce. This value acts as a cost barrier to prevent network flooding. The default value is <code class="docutils literal notranslate"><span class="pre">14</span></code>. Increasing this value makes it computationally more expensive to generate an announce, which can be useful to prevent spam on very large networks, but it also increases CPU load on your system when generating announces. Stamps are cached, and only generated if interface information changes, or at instance restart. If you have the computational resources, it is generally advisable to use as high a stamp value as possible.</p>
+</dd>
+</dl>
+<p><strong>Privacy &amp; Encryption</strong></p>
+<dl class="simple">
+<dt><code class="docutils literal notranslate"><span class="pre">discovery_encrypt</span></code></dt><dd><p>If set to <code class="docutils literal notranslate"><span class="pre">yes</span></code>, the discovery announce payload will be encrypted. To decrypt the announce, remote peers must possess the <em>network identity</em> configured for your instance (see <code class="docutils literal notranslate"><span class="pre">network_identity</span></code> in the <code class="docutils literal notranslate"><span class="pre">[reticulum]</span></code> section). This allows you to publish private interfaces that are only discoverable to specific trusted networks.</p>
+</dd>
+</dl>
+<div class="admonition important">
+<p class="admonition-title">Important</p>
+<p>If you enable <code class="docutils literal notranslate"><span class="pre">discovery_encrypt</span></code> but do not configure a valid <code class="docutils literal notranslate"><span class="pre">network_identity</span></code> in the <code class="docutils literal notranslate"><span class="pre">[reticulum]</span></code> section of your configuration, Reticulum will abort the interface discovery announce. Encryption requires a valid network identity key to function.</p>
+</div>
+<dl class="simple">
+<dt><code class="docutils literal notranslate"><span class="pre">publish_ifac</span></code></dt><dd><p>If set to <code class="docutils literal notranslate"><span class="pre">yes</span></code>, the Interface Access Code (IFAC) name and passphrase for this interface will be included in the discovery announce. This allows peers to automatically configure the correct authentication parameters when connecting to the interface.</p>
+</dd>
+</dl>
+<p><strong>Physical Location</strong></p>
+<dl class="simple">
+<dt><code class="docutils literal notranslate"><span class="pre">latitude</span></code>, <code class="docutils literal notranslate"><span class="pre">longitude</span></code>, <code class="docutils literal notranslate"><span class="pre">height</span></code></dt><dd><p>Optional physical coordinates for the interface. These are useful for mapping discovered interfaces geographically or for clients to automatically select the nearest access point. Coordinates should be in decimal degrees, height in meters.</p>
+</dd>
+</dl>
+<p><strong>Radio Parameters</strong></p>
+<p>For physical radio interfaces like <code class="docutils literal notranslate"><span class="pre">RNodeInterface</span></code> or <code class="docutils literal notranslate"><span class="pre">KISSInterface</span></code>, the following optional parameters allow you to broadcast the operating frequency and characteristics, allowing clients to verify compatibility before connecting:</p>
+<dl class="simple">
+<dt><code class="docutils literal notranslate"><span class="pre">discovery_frequency</span></code></dt><dd><p>The operating frequency in Hz. Auto-configured on RNode interfaces. Necessary on KISS-based radio interfaces and <code class="docutils literal notranslate"><span class="pre">TCPClientInterfaces</span></code> connecting to radio modems.</p>
+</dd>
+<dt><code class="docutils literal notranslate"><span class="pre">discovery_bandwidth</span></code></dt><dd><p>The signal bandwidth in Hz. Auto-configured on RNode interfaces. Useful on KISS-based radio interfaces and <code class="docutils literal notranslate"><span class="pre">TCPClientInterfaces</span></code> connecting to radio modems.</p>
+</dd>
+<dt><code class="docutils literal notranslate"><span class="pre">discovery_modulation</span></code></dt><dd><p>The modulation type or scheme. Auto-configured on RNode interfaces, but highly advisable to include on other radio-based interfaces.</p>
+</dd>
+</dl>
+</section>
+<section id="interface-modes">
+<h3>Interface Modes<a class="headerlink" href="#interface-modes" title="Link to this heading">¶</a></h3>
+<p>When you enable discovery on an interface, Reticulum enforces certain interface modes to ensure the interface is actually useful for remote peers.</p>
+<p>If an interface is configured as <code class="docutils literal notranslate"><span class="pre">discoverable</span></code>, but its mode is not explicitly set to <code class="docutils literal notranslate"><span class="pre">gateway</span></code> (for server-style interfaces like <code class="docutils literal notranslate"><span class="pre">BackboneInterface</span></code> or <code class="docutils literal notranslate"><span class="pre">TCPServerInterface</span></code>) or <code class="docutils literal notranslate"><span class="pre">access_point</span></code> (for radio interfaces like <code class="docutils literal notranslate"><span class="pre">RNodeInterface</span></code>), Reticulum will automatically configure the appropriate mode and log a notice.</p>
+<p>For example, if you enable discovery on a <code class="docutils literal notranslate"><span class="pre">RNodeInterface</span></code> without specifying the mode, Reticulum will automatically set it to <code class="docutils literal notranslate"><span class="pre">access_point</span></code> mode.</p>
+</section>
+<section id="security-considerations">
+<h3>Security Considerations<a class="headerlink" href="#security-considerations" title="Link to this heading">¶</a></h3>
+<p>When making interfaces discoverable, you are effectively broadcasting an invitation to connect to your system. It is important to understand the security implications of the configuration options you choose.</p>
+<p><strong>Publishing Credentials</strong></p>
+<p>If you enable <code class="docutils literal notranslate"><span class="pre">publish_ifac</span> <span class="pre">=</span> <span class="pre">yes</span></code>, your interface’s authentication passphrase will be included in the announce. If you are operating a public network and want anyone to connect, this is acceptable. However, if you wish to restrict access to a specific group of users, you <strong>must</strong> enable <code class="docutils literal notranslate"><span class="pre">discovery_encrypt</span> <span class="pre">=</span> <span class="pre">yes</span></code>. This ensures that only peers possessing the correct <code class="docutils literal notranslate"><span class="pre">network_identity</span></code> can decode the passphrase.</p>
+<p><strong>Topology Exposure</strong></p>
+<p>A discoverable interface announces its presence, location (if configured), and capabilities to the network. Even if the connection details are encrypted, the <em>fact</em> that a connectable node exists within a certain network becomes public information. In high-security or scenarios requiring operational secrecy, consider the implications of advertising your infrastructure’s existence.</p>
+</section>
+<section id="example-configuration">
+<h3>Example Configuration<a class="headerlink" href="#example-configuration" title="Link to this heading">¶</a></h3>
+<p>Below is an example configuration for a public backbone gateway. This configuration publishes a high-value, publicly discoverable interface, that anyone can connect to.</p>
+<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[[My Public Gateway]]</span>
+<span class="w">  </span><span class="na">type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">BackboneInterface</span>
+<span class="w">  </span><span class="na">mode</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">gateway</span>
+<span class="w">  </span><span class="na">listen_on</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">0.0.0.0</span>
+<span class="w">  </span><span class="na">port</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">4242</span>
+
+<span class="w">  </span><span class="c1"># Enable Discovery</span>
+<span class="w">  </span><span class="na">discoverable</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span>
+
+<span class="w">  </span><span class="c1"># Interface Details</span>
+<span class="w">  </span><span class="na">discovery_name</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">Region A Public Entrypoint</span>
+<span class="w">  </span><span class="na">announce_interval</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">720</span>
+
+<span class="w">  </span><span class="c1"># Use external script to resolve dynamic IP</span>
+<span class="w">  </span><span class="na">reachable_on</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">/usr/local/bin/get_external_ip.sh</span>
+
+<span class="w">  </span><span class="c1"># Generate high stamp value</span>
+<span class="w">  </span><span class="na">discovery_stamp_value</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">24</span>
+
+<span class="w">  </span><span class="c1"># Optional location data</span>
+<span class="w">  </span><span class="na">latitude</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">51.99714</span>
+<span class="w">  </span><span class="na">longitude</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">-0.74195</span>
+<span class="w">  </span><span class="na">height</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">15</span>
+</pre></div>
+</div>
+<p>The next example create an encrypted discovery-enabled interface, requiring a specific network identity to decode, and includes IFAC credentials for seamless authentication.</p>
+<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[[My Private Gateway]]</span>
+<span class="w">  </span><span class="na">type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">BackboneInterface</span>
+<span class="w">  </span><span class="na">mode</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">gateway</span>
+<span class="w">  </span><span class="na">listen_on</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">0.0.0.0</span>
+<span class="w">  </span><span class="na">port</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">5858</span>
+<span class="w">  </span><span class="na">network_name</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">internal_1</span>
+<span class="w">  </span><span class="na">passphrase</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">Mevpekyafshak5Wr</span>
+
+<span class="w">  </span><span class="c1"># Enable Discovery</span>
+<span class="w">  </span><span class="na">discoverable</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span>
+
+<span class="w">  </span><span class="c1"># Interface Details</span>
+<span class="w">  </span><span class="na">discovery_name</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">Region A Private Backbone</span>
+<span class="w">  </span><span class="na">announce_interval</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">720</span>
+
+<span class="w">  </span><span class="c1"># Use external script to resolve dynamic IP</span>
+<span class="w">  </span><span class="na">reachable_on</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">/usr/local/bin/get_external_ip.sh</span>
+
+<span class="w">  </span><span class="c1"># Target stamp value</span>
+<span class="w">  </span><span class="na">discovery_stamp_value</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">22</span>
+
+<span class="w">  </span><span class="c1"># Encrypt announces for our network only</span>
+<span class="w">  </span><span class="na">discovery_encrypt</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span>
+
+<span class="w">  </span><span class="c1"># Include credentials so trusted</span>
+<span class="w">  </span><span class="c1"># peers can connect automatically</span>
+<span class="w">  </span><span class="na">publish_ifac</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span>
+
+<span class="w">  </span><span class="c1"># Optional location data</span>
+<span class="w">  </span><span class="na">latitude</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">34.06915</span>
+<span class="w">  </span><span class="na">longitude</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">-118.44318</span>
+<span class="w">  </span><span class="na">height</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">15</span>
+</pre></div>
+</div>
+<p>In the <code class="docutils literal notranslate"><span class="pre">[reticulum]</span></code> section of your configuration, you would define the network identity used for encryption as follows:</p>
+<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[reticulum]</span>
+<span class="na">...</span>
+<span class="c1"># The identity used to sign/encrypt discovery announces</span>
+<span class="na">network_identity</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">~/.reticulum/storage/identities/my_network_identity</span>
+<span class="na">...</span>
+</pre></div>
+</div>
+<p>With these configuration options applied, your Reticulum instance will actively participate in the network’s discovery ecosystem. Other peers running Reticulum with discovery enabled will be able to see your interface, validate its cryptographic stamp, and (depending on their configuration) automatically connect to it.</p>
+<p>For information on how to use these discovered interfaces and configure your system to auto-connect to them, refer to the <a class="reference internal" href="using.html#using-interface-discovery"><span class="std std-ref">Discovering Interfaces</span></a> chapter.</p>
+</section>
+</section>
 <section id="common-interface-options">
 <span id="interfaces-options"></span><h2>Common Interface Options<a class="headerlink" href="#common-interface-options" title="Link to this heading">¶</a></h2>
 <p>A number of general configuration options are available on most interfaces.
@@ -1166,11 +1349,22 @@ sufficient, but it can be configured by using the <code class="docutils literal
 option, to set the interface speed in <em>bits per second</em>.</div>
 </div>
 </li>
+<li><div class="line-block">
+<div class="line">The <code class="docutils literal notranslate"><span class="pre">bootstrap_only</span></code> option designates an interface as a temporary
+bridge for initial connectivity. If this option is enabled, the
+interface will be monitored and automatically detached once the
+number of auto-connected interfaces reaches the limit configured by
+<code class="docutils literal notranslate"><span class="pre">autoconnect_discovered_interfaces</span></code>. This is particularly useful
+for using a slow or expensive connection (such as a single LoRa
+link or a remote TCP tunnel) solely to discover better local
+infrastructure, which then supersedes the bootstrap interface.</div>
+</div>
+</li>
 </ul>
 </div></blockquote>
 </section>
-<section id="interface-modes">
-<span id="interfaces-modes"></span><h2>Interface Modes<a class="headerlink" href="#interface-modes" title="Link to this heading">¶</a></h2>
+<section id="interfaces-modes">
+<span id="id4"></span><h2>Interface Modes<a class="headerlink" href="#interfaces-modes" title="Link to this heading">¶</a></h2>
 <p>The optional <code class="docutils literal notranslate"><span class="pre">mode</span></code> setting is available on all interfaces, and allows
 selecting the high-level behaviour of the interface from a number of modes.
 These modes affect how Reticulum selects paths in the network, how announces
@@ -1468,8 +1662,16 @@ to <code class="docutils literal notranslate"><span class="pre">30</span></code>
 <li><a class="reference internal" href="#pipe-interface">Pipe Interface</a></li>
 <li><a class="reference internal" href="#kiss-interface">KISS Interface</a></li>
 <li><a class="reference internal" href="#ax-25-kiss-interface">AX.25 KISS Interface</a></li>
-<li><a class="reference internal" href="#common-interface-options">Common Interface Options</a></li>
+<li><a class="reference internal" href="#discoverable-interfaces">Discoverable Interfaces</a><ul>
+<li><a class="reference internal" href="#enabling-discovery">Enabling Discovery</a></li>
+<li><a class="reference internal" href="#discovery-parameters">Discovery Parameters</a></li>
 <li><a class="reference internal" href="#interface-modes">Interface Modes</a></li>
+<li><a class="reference internal" href="#security-considerations">Security Considerations</a></li>
+<li><a class="reference internal" href="#example-configuration">Example Configuration</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#common-interface-options">Common Interface Options</a></li>
+<li><a class="reference internal" href="#interfaces-modes">Interface Modes</a></li>
 <li><a class="reference internal" href="#announce-rate-control">Announce Rate Control</a></li>
 <li><a class="reference internal" href="#new-destination-rate-limiting">New Destination Rate Limiting</a></li>
 </ul>
@@ -1483,7 +1685,7 @@ to <code class="docutils literal notranslate"><span class="pre">30</span></code>
       
     </aside>
   </div>
-</div><script src="_static/documentation_options.js?v=baaebd52"></script>
+</div><script src="_static/documentation_options.js?v=590429e0"></script>
     <script src="_static/doctools.js?v=9bcbadda"></script>
     <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="_static/scripts/furo.js?v=46bd48cc"></script>

docs/manual/license.html

@@ -0,0 +1,354 @@
+<!doctype html>
+<html class="no-js" lang="en" data-content_root="./">
+  <head><meta charset="utf-8">
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+    <meta name="color-scheme" content="light dark"><meta name="viewport" content="width=device-width, initial-scale=1" />
+<link rel="index" title="Index" href="genindex.html"><link rel="search" title="Search" href="search.html"><link rel="next" title="API Reference" href="reference.html"><link rel="prev" title="Code Examples" href="examples.html">
+        <link rel="prefetch" href="_static/rns_logo_512.png" as="image">
+
+    <!-- Generated with Sphinx 8.2.3 and Furo 2025.09.25.dev1 -->
+        <title>Reticulum License - Reticulum Network Stack 1.2.3 documentation</title>
+      <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d111a655" />
+    <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=580074bf" />
+    <link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
+    <link rel="stylesheet" type="text/css" href="_static/styles/furo-extensions.css?v=8dab3a3b" />
+    <link rel="stylesheet" type="text/css" href="_static/custom.css?v=bb3cebc5" />
+    
+    
+
+
+<style>
+  body {
+    --color-code-background: #f2f2f2;
+  --color-code-foreground: #1e1e1e;
+  
+  }
+  @media not print {
+    body[data-theme="dark"] {
+      --color-code-background: #202020;
+  --color-code-foreground: #d0d0d0;
+  --color-background-primary: #202b38;
+  --color-background-secondary: #161f27;
+  --color-foreground-primary: #dbdbdb;
+  --color-foreground-secondary: #a9b1ba;
+  --color-brand-primary: #41adff;
+  --color-background-hover: #161f27;
+  --color-api-name: #ffbe85;
+  --color-api-pre-name: #efae75;
+  
+    }
+    @media (prefers-color-scheme: dark) {
+      body:not([data-theme="light"]) {
+        --color-code-background: #202020;
+  --color-code-foreground: #d0d0d0;
+  --color-background-primary: #202b38;
+  --color-background-secondary: #161f27;
+  --color-foreground-primary: #dbdbdb;
+  --color-foreground-secondary: #a9b1ba;
+  --color-brand-primary: #41adff;
+  --color-background-hover: #161f27;
+  --color-api-name: #ffbe85;
+  --color-api-pre-name: #efae75;
+  
+      }
+    }
+  }
+</style></head>
+  <body>
+    
+    <script>
+      document.body.dataset.theme = localStorage.getItem("theme") || "auto";
+    </script>
+    
+
+<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
+  <symbol id="svg-toc" viewBox="0 0 24 24">
+    <title>Contents</title>
+    <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 1024 1024">
+      <path d="M408 442h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8zm-8 204c0 4.4 3.6 8 8 8h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56zm504-486H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zm0 632H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zM115.4 518.9L271.7 642c5.8 4.6 14.4.5 14.4-6.9V388.9c0-7.4-8.5-11.5-14.4-6.9L115.4 505.1a8.74 8.74 0 0 0 0 13.8z"/>
+    </svg>
+  </symbol>
+  <symbol id="svg-menu" viewBox="0 0 24 24">
+    <title>Menu</title>
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+      stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-menu">
+      <line x1="3" y1="12" x2="21" y2="12"></line>
+      <line x1="3" y1="6" x2="21" y2="6"></line>
+      <line x1="3" y1="18" x2="21" y2="18"></line>
+    </svg>
+  </symbol>
+  <symbol id="svg-arrow-right" viewBox="0 0 24 24">
+    <title>Expand</title>
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+      stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-chevron-right">
+      <polyline points="9 18 15 12 9 6"></polyline>
+    </svg>
+  </symbol>
+  <symbol id="svg-sun" viewBox="0 0 24 24">
+    <title>Light mode</title>
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+      stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="feather-sun">
+      <circle cx="12" cy="12" r="5"></circle>
+      <line x1="12" y1="1" x2="12" y2="3"></line>
+      <line x1="12" y1="21" x2="12" y2="23"></line>
+      <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line>
+      <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line>
+      <line x1="1" y1="12" x2="3" y2="12"></line>
+      <line x1="21" y1="12" x2="23" y2="12"></line>
+      <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line>
+      <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line>
+    </svg>
+  </symbol>
+  <symbol id="svg-moon" viewBox="0 0 24 24">
+    <title>Dark mode</title>
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+      stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-moon">
+      <path stroke="none" d="M0 0h24v24H0z" fill="none" />
+      <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z" />
+    </svg>
+  </symbol>
+  <symbol id="svg-sun-with-moon" viewBox="0 0 24 24">
+    <title>Auto light/dark, in light mode</title>
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+      stroke-width="1" stroke-linecap="round" stroke-linejoin="round"
+      class="icon-custom-derived-from-feather-sun-and-tabler-moon">
+      <path style="opacity: 50%" d="M 5.411 14.504 C 5.471 14.504 5.532 14.504 5.591 14.504 C 3.639 16.319 4.383 19.569 6.931 20.352 C 7.693 20.586 8.512 20.551 9.25 20.252 C 8.023 23.207 4.056 23.725 2.11 21.184 C 0.166 18.642 1.702 14.949 4.874 14.536 C 5.051 14.512 5.231 14.5 5.411 14.5 L 5.411 14.504 Z"/>
+      <line x1="14.5" y1="3.25" x2="14.5" y2="1.25"/>
+      <line x1="14.5" y1="15.85" x2="14.5" y2="17.85"/>
+      <line x1="10.044" y1="5.094" x2="8.63" y2="3.68"/>
+      <line x1="19" y1="14.05" x2="20.414" y2="15.464"/>
+      <line x1="8.2" y1="9.55" x2="6.2" y2="9.55"/>
+      <line x1="20.8" y1="9.55" x2="22.8" y2="9.55"/>
+      <line x1="10.044" y1="14.006" x2="8.63" y2="15.42"/>
+      <line x1="19" y1="5.05" x2="20.414" y2="3.636"/>
+      <circle cx="14.5" cy="9.55" r="3.6"/>
+    </svg>
+  </symbol>
+  <symbol id="svg-moon-with-sun" viewBox="0 0 24 24">
+    <title>Auto light/dark, in dark mode</title>
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+      stroke-width="1" stroke-linecap="round" stroke-linejoin="round"
+      class="icon-custom-derived-from-feather-sun-and-tabler-moon">
+      <path d="M 8.282 7.007 C 8.385 7.007 8.494 7.007 8.595 7.007 C 5.18 10.184 6.481 15.869 10.942 17.24 C 12.275 17.648 13.706 17.589 15 17.066 C 12.851 22.236 5.91 23.143 2.505 18.696 C -0.897 14.249 1.791 7.786 7.342 7.063 C 7.652 7.021 7.965 7 8.282 7 L 8.282 7.007 Z"/>
+      <line style="opacity: 50%" x1="18" y1="3.705" x2="18" y2="2.5"/>
+      <line style="opacity: 50%" x1="18" y1="11.295" x2="18" y2="12.5"/>
+      <line style="opacity: 50%" x1="15.316" y1="4.816" x2="14.464" y2="3.964"/>
+      <line style="opacity: 50%" x1="20.711" y1="10.212" x2="21.563" y2="11.063"/>
+      <line style="opacity: 50%" x1="14.205" y1="7.5" x2="13.001" y2="7.5"/>
+      <line style="opacity: 50%" x1="21.795" y1="7.5" x2="23" y2="7.5"/>
+      <line style="opacity: 50%" x1="15.316" y1="10.184" x2="14.464" y2="11.036"/>
+      <line style="opacity: 50%" x1="20.711" y1="4.789" x2="21.563" y2="3.937"/>
+      <circle style="opacity: 50%" cx="18" cy="7.5" r="2.169"/>
+    </svg>
+  </symbol>
+  <symbol id="svg-pencil" viewBox="0 0 24 24">
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+      stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-pencil-code">
+      <path d="M4 20h4l10.5 -10.5a2.828 2.828 0 1 0 -4 -4l-10.5 10.5v4" />
+      <path d="M13.5 6.5l4 4" />
+      <path d="M20 21l2 -2l-2 -2" />
+      <path d="M17 17l-2 2l2 2" />
+    </svg>
+  </symbol>
+  <symbol id="svg-eye" viewBox="0 0 24 24">
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+      stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-eye-code">
+      <path stroke="none" d="M0 0h24v24H0z" fill="none" />
+      <path d="M10 12a2 2 0 1 0 4 0a2 2 0 0 0 -4 0" />
+      <path
+        d="M11.11 17.958c-3.209 -.307 -5.91 -2.293 -8.11 -5.958c2.4 -4 5.4 -6 9 -6c3.6 0 6.6 2 9 6c-.21 .352 -.427 .688 -.647 1.008" />
+      <path d="M20 21l2 -2l-2 -2" />
+      <path d="M17 17l-2 2l2 2" />
+    </svg>
+  </symbol>
+</svg>
+
+<input type="checkbox" class="sidebar-toggle" name="__navigation" id="__navigation" aria-label="Toggle site navigation sidebar">
+<input type="checkbox" class="sidebar-toggle" name="__toc" id="__toc" aria-label="Toggle table of contents sidebar">
+<label class="overlay sidebar-overlay" for="__navigation"></label>
+<label class="overlay toc-overlay" for="__toc"></label>
+
+<a class="skip-to-content muted-link" href="#furo-main-content">Skip to content</a>
+
+
+
+<div class="page">
+  <header class="mobile-header">
+    <div class="header-left">
+      <label class="nav-overlay-icon" for="__navigation">
+        <span class="icon"><svg><use href="#svg-menu"></use></svg></span>
+      </label>
+    </div>
+    <div class="header-center">
+      <a href="index.html"><div class="brand">Reticulum Network Stack 1.2.3 documentation</div></a>
+    </div>
+    <div class="header-right">
+      <div class="theme-toggle-container theme-toggle-header">
+        <button class="theme-toggle" aria-label="Toggle Light / Dark / Auto color theme">
+          <svg class="theme-icon-when-auto-light"><use href="#svg-sun-with-moon"></use></svg>
+          <svg class="theme-icon-when-auto-dark"><use href="#svg-moon-with-sun"></use></svg>
+          <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg>
+          <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg>
+        </button>
+      </div>
+      <label class="toc-overlay-icon toc-header-icon no-toc" for="__toc">
+        <span class="icon"><svg><use href="#svg-toc"></use></svg></span>
+      </label>
+    </div>
+  </header>
+  <aside class="sidebar-drawer">
+    <div class="sidebar-container">
+      
+      <div class="sidebar-sticky"><a class="sidebar-brand" href="index.html">
+  <div class="sidebar-logo-container">
+    <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
+  </div>
+  
+  <span class="sidebar-brand-text">Reticulum Network Stack 1.2.3 documentation</span>
+  
+</a><form class="sidebar-search-container" method="get" action="search.html" role="search">
+  <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
+  <input type="hidden" name="check_keywords" value="yes">
+  <input type="hidden" name="area" value="default">
+</form>
+<div id="searchbox"></div><div class="sidebar-scroll"><div class="sidebar-tree">
+  <ul class="current">
+<li class="toctree-l1"><a class="reference internal" href="whatis.html">What is Reticulum?</a></li>
+<li class="toctree-l1"><a class="reference internal" href="gettingstartedfast.html">Getting Started Fast</a></li>
+<li class="toctree-l1"><a class="reference internal" href="zen.html">Zen of Reticulum</a></li>
+<li class="toctree-l1"><a class="reference internal" href="software.html">Programs Using Reticulum</a></li>
+<li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
+<li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
+<li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
+<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
+<li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks</a></li>
+<li class="toctree-l1"><a class="reference internal" href="git.html">Git Over Reticulum</a></li>
+<li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a></li>
+<li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a></li>
+<li class="toctree-l1 current current-page"><a class="current reference internal" href="#">Reticulum License</a></li>
+</ul>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="reference.html">API Reference</a></li>
+</ul>
+
+</div>
+</div>
+
+      </div>
+      
+    </div>
+  </aside>
+  <div class="main">
+    <div class="content">
+      <div class="article-container">
+        <a href="#" class="back-to-top muted-link">
+          <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
+            <path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8v12z"></path>
+          </svg>
+          <span>Back to top</span>
+        </a>
+        <div class="content-icon-container">
+          <div class="theme-toggle-container theme-toggle-content">
+            <button class="theme-toggle" aria-label="Toggle Light / Dark / Auto color theme">
+              <svg class="theme-icon-when-auto-light"><use href="#svg-sun-with-moon"></use></svg>
+              <svg class="theme-icon-when-auto-dark"><use href="#svg-moon-with-sun"></use></svg>
+              <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg>
+              <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg>
+            </button>
+          </div>
+          <label class="toc-overlay-icon toc-content-icon no-toc" for="__toc">
+            <span class="icon"><svg><use href="#svg-toc"></use></svg></span>
+          </label>
+        </div>
+        <article role="main" id="furo-main-content">
+          <section id="reticulum-license">
+<span id="license"></span><h1>Reticulum License<a class="headerlink" href="#reticulum-license" title="Link to this heading">¶</a></h1>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Reticulum License
+
+Copyright (c) 2016-2026 Mark Qvist
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the &quot;Software&quot;), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+- The Software shall not be used in any kind of system which includes amongst
+  its functions the ability to purposefully do harm to human beings.
+
+- The Software shall not be used, directly or indirectly, in the creation of
+  an artificial intelligence, machine learning or language model training
+  dataset, including but not limited to any use that contributes to the
+  training or development of such a model or algorithm.
+
+- The above copyright notice and this permission notice shall be included in
+  all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED &quot;AS IS&quot;, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+</pre></div>
+</div>
+</section>
+
+        </article>
+      </div>
+      <footer>
+        
+        <div class="related-pages">
+          <a class="next-page" href="reference.html">
+              <div class="page-info">
+                <div class="context">
+                  <span>Next</span>
+                </div>
+                <div class="title">API Reference</div>
+              </div>
+              <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
+            </a>
+          <a class="prev-page" href="examples.html">
+              <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
+              <div class="page-info">
+                <div class="context">
+                  <span>Previous</span>
+                </div>
+                
+                <div class="title">Code Examples</div>
+                
+              </div>
+            </a>
+        </div>
+        <div class="bottom-of-page">
+          <div class="left-details">
+            <div class="copyright">
+                Copyright &#169; 2025, Mark Qvist
+            </div>
+            Generated with <a href="https://www.sphinx-doc.org/">Sphinx</a> and 
+            <a href="https://github.com/pradyunsg/furo">Furo</a>
+            
+          </div>
+          <div class="right-details">
+            
+          </div>
+        </div>
+        
+      </footer>
+    </div>
+    <aside class="toc-drawer no-toc">
+      
+      
+      
+    </aside>
+  </div>
+</div><script src="_static/documentation_options.js?v=590429e0"></script>
+    <script src="_static/doctools.js?v=9bcbadda"></script>
+    <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
+    <script src="_static/scripts/furo.js?v=46bd48cc"></script>
+    <script src="_static/clipboard.min.js?v=a7894cd8"></script>
+    <script src="_static/copybutton.js?v=f281be69"></script>
+    </body>
+</html>

docs/manual/networks.html

@@ -3,11 +3,11 @@
   <head><meta charset="utf-8">
     <meta name="viewport" content="width=device-width,initial-scale=1">
     <meta name="color-scheme" content="light dark"><meta name="viewport" content="width=device-width, initial-scale=1" />
-<link rel="index" title="Index" href="genindex.html"><link rel="search" title="Search" href="search.html"><link rel="next" title="Support Reticulum" href="support.html"><link rel="prev" title="Configuring Interfaces" href="interfaces.html">
+<link rel="index" title="Index" href="genindex.html"><link rel="search" title="Search" href="search.html"><link rel="next" title="Git Over Reticulum" href="git.html"><link rel="prev" title="Configuring Interfaces" href="interfaces.html">
         <link rel="prefetch" href="_static/rns_logo_512.png" as="image">
 
     <!-- Generated with Sphinx 8.2.3 and Furo 2025.09.25.dev1 -->
-        <title>Building Networks - Reticulum Network Stack 1.0.3 documentation</title>
+        <title>Building Networks - Reticulum Network Stack 1.2.3 documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d111a655" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=580074bf" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
@@ -180,7 +180,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 1.0.3 documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 1.2.3 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -204,7 +204,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 1.0.3 documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 1.2.3 documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@@ -215,13 +215,17 @@
   <ul class="current">
 <li class="toctree-l1"><a class="reference internal" href="whatis.html">What is Reticulum?</a></li>
 <li class="toctree-l1"><a class="reference internal" href="gettingstartedfast.html">Getting Started Fast</a></li>
+<li class="toctree-l1"><a class="reference internal" href="zen.html">Zen of Reticulum</a></li>
+<li class="toctree-l1"><a class="reference internal" href="software.html">Programs Using Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
 <li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
 <li class="toctree-l1 current current-page"><a class="current reference internal" href="#">Building Networks</a></li>
+<li class="toctree-l1"><a class="reference internal" href="git.html">Git Over Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a></li>
+<li class="toctree-l1"><a class="reference internal" href="license.html">Reticulum License</a></li>
 </ul>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="reference.html">API Reference</a></li>
@@ -259,15 +263,39 @@
         <article role="main" id="furo-main-content">
           <section id="building-networks">
 <span id="networks-main"></span><h1>Building Networks<a class="headerlink" href="#building-networks" title="Link to this heading">¶</a></h1>
-<p>This chapter will provide you with the knowledge needed to build networks with
-Reticulum, which can often be easier than using traditional stacks, since you
-don’t have to worry about coordinating addresses, subnets and routing for an
+<p>This chapter will provide you with the high-level knowledge needed to build networks with
+Reticulum. It will not, however tell you all you need to know to succesfully
+design and configure every kind of network you can imagine. For this, you will
+most likely need to read this manual in its entirity, invest significant time
+into experimenting with the stack, and learning functionality intuitively.</p>
+<p>Still, after reading this chapter, you should be well equipped to <em>start</em> that
+journey. While Reticulum is <strong>fundamentally different</strong> compared to other
+networking technologies, it can often be easier than using traditional stacks.
+If you’ve built networks before, you will probably have to forget, or at least
+temporarily ignore, a lot of things at this point. It will all makes sense in
+the end though. Hopefully.</p>
+<p>If you’re used to protocols like IP, let’s at least start with some relief:
+You don’t have to worry about coordinating addresses, subnets and routing for an
 entire network that you might not know how will evolve in the future. With
 Reticulum, you can simply add more segments to your network when it becomes
 necessary, and Reticulum will handle the convergence of the entire network
-automatically.</p>
+automatically. There’s plenty more neat aspects like that to Reticulum, but
+we’re getting ahead of ourselves. Let’s cover the basics first.</p>
 <section id="concepts-overview">
 <h2>Concepts &amp; Overview<a class="headerlink" href="#concepts-overview" title="Link to this heading">¶</a></h2>
+<p>Before you start building your own networks, it’s important to understand the
+fundamental principles that distinguish Reticulum networks from traditional
+networking approaches. These principles shape how you design your network,
+what trade-offs you encounter, and what capabilities you can rely on.</p>
+<p>Reticulum is not a single network you “join”, it is a toolkit for <em>creating</em> networks.
+You decide what mediums to use, how nodes connect, what trust boundaries exist,
+and what the network’s purpose is. Reticulum provides the cryptographic foundation,
+the transport mechanisms, and the convergence algorithms that make your design
+workable. You provide the intent and the structure.</p>
+<p>This approach offers tremendous flexibility, but it requires thinking in terms of
+different abstractions than those used in conventional networking.</p>
+<section id="introductory-considerations">
+<h3>Introductory Considerations<a class="headerlink" href="#introductory-considerations" title="Link to this heading">¶</a></h3>
 <p>There are important points that need to be kept in mind when building networks
 with Reticulum:</p>
 <blockquote>
@@ -289,7 +317,12 @@ also very useful when just a few devices needs to communicate.</div>
 <div class="line">Low-bandwidth networks, like LoRa and packet radio, can interoperate and
 interconnect with much larger and higher bandwidth networks without issue.
 Reticulum automatically manages the flow of information to and from various
-network segments, and when bandwidth is limited, local traffic is prioritised.</div>
+network segments, and when bandwidth is limited, local traffic is prioritised.
+You will, however, need to configure your interfaces correctly. If you tell
+Reticulum to pass all announce traffic from a gigabit link to a LoRa interfaces,
+it will try as best as possible to comply with this, while still respecting
+bandwidth limits, but you <em>will</em> waste a lot of precious bandwidth and airtime,
+and your LoRa network will not work very well.</div>
 </div>
 </li>
 <li><div class="line-block">
@@ -361,69 +394,197 @@ chapter of this manual for interface configuration examples.</p>
 decide which are suitable to use in any given situation, depending on where
 traffic needs to flow.</p>
 </section>
-<section id="example-scenarios">
-<h2>Example Scenarios<a class="headerlink" href="#example-scenarios" title="Link to this heading">¶</a></h2>
-<p>This section illustrates a few example scenarios, and how they would, in general
-terms, be planned, implemented and configured.</p>
-<section id="interconnected-lora-sites">
-<h3>Interconnected LoRa Sites<a class="headerlink" href="#interconnected-lora-sites" title="Link to this heading">¶</a></h3>
-<p>An organisation wants to provide communication and information services to it’s
-members, which are located mainly in three separate areas. Three suitable hill-top
-locations are found, where the organisation can install equipment: Site A, B and C.</p>
-<p>Since the amount of data that needs to be exchanged between users is mainly text-
-based, the bandwidth requirements are low, and LoRa radios are chosen to connect
-users to the network.</p>
-<p>Due to the hill-top locations found, there is radio line-of-sight between site A
-and B, and also between site B and C. Because of this, the organisation does not
-need to use the Internet to interconnect the sites, but purchases four Point-to-Point
-WiFi based radios for interconnecting the sites.</p>
-<p>At each site, a Raspberry Pi is installed to function as a gateway. A LoRa radio
-is connected to the Pi with a USB cable, and the WiFi radio is connected to the
-Ethernet port of the Pi. At site B, two WiFi radios are needed to be able to reach
-both site A and site C, so an extra Ethernet adapter is connected to the Pi in
-this location.</p>
-<p>Once the hardware has been installed, Reticulum is installed on all the Pis, and at
-site A and C, one interface is added for the LoRa radio, as well as one for the WiFi
-radio. At site B, an interface for the LoRa radio, and one interface for each WiFi
-radio is added to the Reticulum configuration file. The transport node option is
-enabled in the configuration of all three gateways.</p>
-<p>The network is now operational, and ready to serve users across all three areas.
-The organisation prepares a LoRa radio that is supplied to the end users, along
-with a Reticulum configuration file, that contains the right parameters for
-communicating with the LoRa radios installed at the gateway sites.</p>
-<p>Once users connect to the network, anyone will be able to communicate with anyone
-else across all three sites.</p>
+<section id="destinations-not-addresses">
+<h3>Destinations, Not Addresses<a class="headerlink" href="#destinations-not-addresses" title="Link to this heading">¶</a></h3>
+<p>In traditional networking, addresses are allocated from a managed space. If you want to
+communicate with another node, you need to know its address, and that address
+must be unique within the network segment. This requires coordination, either
+through manual assignment, DHCP servers, or other allocation mechanisms.</p>
+<p>Reticulum replaces addresses with <strong>destinations</strong>. A destination is identified by a 16-byte
+hash (128 bits) derived from a SHA-256 hash of the destination’s identifying
+characteristics. This hash serves as the address on the network. On the network, it
+is represented in binary, but when displayed to human users, it will usually look something like
+this <code class="docutils literal notranslate"><span class="pre">&lt;13425ec15b621c1d928589718000d814&gt;</span></code>.</p>
+<p>The critical difference is that <em>any node can generate as many destinations as it
+needs, without coordination</em>. A destination’s uniqueness is guaranteed by the
+collision resistance of SHA-256 and the inclusion of the node’s public key in the
+hash calculation. Two nodes can both use the destination name
+<code class="docutils literal notranslate"><span class="pre">messenger.user.inbox</span></code>, but they will have different destination hashes because
+their public keys differ. Both can coexist on the same network without conflict.</p>
+<p>This has profound implications for network design:</p>
+<ul class="simple">
+<li><p><strong>No address allocation planning:</strong> You never need to reserve address ranges,
+plan subnets, or coordinate with other network operators. Nodes simply generate
+destinations and announce them.</p></li>
+<li><p><strong>Global portability:</strong> A destination is not tied to a physical location or
+network segment. A node can move its destinations across interfaces, mediums,
+or even between entirely separate Reticulum networks simply by sending an
+announce on the new medium.</p></li>
+<li><p><strong>Implicit authentication:</strong> Because destinations are bound to public keys,
+communication to a destination is inherently cryptographically authenticated.
+Only the holder of the corresponding private key can decrypt and respond to
+traffic addressed to that destination. This also makes application-level
+authentication <em>much</em> simpler, since it can directly use the foundational
+identity verification built into the core networking layer.</p></li>
+<li><p><strong>Identity abstraction:</strong> A single Reticulum Identity can create multiple
+destinations. This allows a single entity (a person, a device, a service) to
+present multiple endpoints without needing multiple cryptographic keypairs.</p></li>
+</ul>
 </section>
-<section id="bridging-over-the-internet">
-<h3>Bridging Over the Internet<a class="headerlink" href="#bridging-over-the-internet" title="Link to this heading">¶</a></h3>
-<p>As the organisation grows, several new communities form in places too far away
-from the core network to be reachable over WiFi links. New gateways similar to those
-previously installed are set up for the new communities at the new sites D and E, but
-they are islanded from the core network, and only serve the local users.</p>
-<p>After investigating the options, it is found that it is possible to install an
-Internet connection at site A, and an interface on the Internet connection is
-configured for Reticulum on the Raspberry Pi at site A.</p>
-<p>A member of the organisation at site D, named Dori, is willing to help by sharing
-the Internet connection she already has in her home, and is able to leave a Raspberry
-Pi running. A new Reticulum interface is configured on her Pi, connecting to the newly
-enabled Internet interface on the gateway at site A. Dori is now connected to both
-the nodes at her own local site (through the hill-top LoRa gateway), and all the
-combined users of sites A, B and C. She then enables transport on her node, and
-traffic from site D can now reach everyone at site A, B and C, and vice versa.</p>
+<section id="transport-nodes-and-instances">
+<h3>Transport Nodes and Instances<a class="headerlink" href="#transport-nodes-and-instances" title="Link to this heading">¶</a></h3>
+<p>Reticulum distinguishes between two types of nodes: <strong>Instances</strong>
+and <strong>Transport Nodes</strong>. Every node running Reticulum is an Instance, but not
+every Instance is a Transport Node.</p>
+<p>A <strong>Reticulum Instance</strong> is any system running the Reticulum stack. It can create
+destinations, send and receive packets, establish links, and communicate with
+other nodes. It can also host destinations that are connectable for <em>anyone</em> else
+in the network. This means you can easily host globally available services from
+any location, including your home or office. Network-wide, global connectivity
+for all destinations is guaranteed, as long as there is <em>some</em> physical way to
+actually transport the packets. Instances are the default state and are appropriate for most end-user devices,
+such as phones, laptops, sensors, or any device that primarily consumes network services.</p>
+<p>A <strong>Transport Node</strong> is an Instance that has been explicitly configured to
+participate in network-wide transport. Transport nodes forward packets across
+hops, propagate announces, maintain path tables, and serve path requests on
+behalf of other nodes. When a destination sends an announce, Transport Nodes
+receive it, remember the path, and rebroadcast it to other interfaces. When a node
+needs to reach a destination it doesn’t have a path for, Transport Nodes help
+resolve the path through the network.</p>
+<p>Even devices hosting services or serving content should probably just be configured
+as instances, and themselves connect to wider networks via a Transport Node.
+In some situations, this may not be practical though, and as an example, it is
+entirely viable to host a personal Transport Node on a Raspberry Pi, while it
+is at the same time running an LXMF propagation node, and hosting your personal
+site or files over Reticulum.</p>
+<p>The distinction is important. <strong>Not</strong> every node should be a Transport Node:</p>
+<ul class="simple">
+<li><p><strong>Resource consumption:</strong> Transport nodes maintain path tables, process
+announces, and forward traffic. This requires memory and CPU resources that
+may be limited on low-powered devices.</p></li>
+<li><p><strong>Stability requirements:</strong> Transport nodes contribute to network convergence.
+If Transport Nodes frequently go offline, path tables become stale and
+convergence suffers. Stable, always-on nodes make better Transport Nodes.</p></li>
+<li><p><strong>Bandwidth considerations:</strong> Transport nodes process and rebroadcast network
+maintenance traffic. On very low-bandwidth mediums, having too many Transport
+Nodes will consume capacity that should be used for actual data.</p></li>
+</ul>
+<p>In practice, a network typically has a relatively small number of Transport Nodes
+strategically placed to provide coverage and connectivity. End-user devices run
+as Instances, connecting through nearby Transport Nodes to reach the wider network.
+This pattern mirrors traditional networking where routers forward traffic while
+end hosts simply consume connectivity, but with the crucial difference that any
+node <em>can</em> become a router if needed, and the decision is yours to make based on
+your network’s requirements.</p>
+<p>Transport nodes also function as distributed cryptographic keystores. When a
+destination announces itself, Transport Nodes cache the public key and destination
+information. Other nodes can request unknown public keys from the network, and
+Transport Nodes respond with the cached information. This eliminates the need for
+a central directory service while ensuring that public keys remain available
+throughout the network.</p>
 </section>
-<section id="growth-and-convergence">
-<h3>Growth and Convergence<a class="headerlink" href="#growth-and-convergence" title="Link to this heading">¶</a></h3>
-<p>As the organisation grows, more gateways are added to keep up with the growing user
-base. Some local gateways even add VHF radios and packet modems to reach outlying users
-and communities that are out of reach for the LoRa radios and WiFi backhauls.</p>
-<p>As more sites, gateways and users are connected, the amount of coordination required
-is kept to a minimum. If one community wants to add connectivity to the next one
-over, it can simply be done without having to involve everyone or coordinate address
-space or routing tables.</p>
-<p>With the added geographical coverage, the operators at site A one day find that
-the original internet bridged interfaces are no longer utilised. The network has
-converged to be completely self-connected, and the sites that were once poorly
-connected outliers are now an integral part of the network.</p>
+<section id="trustless-networking">
+<h3>Trustless Networking<a class="headerlink" href="#trustless-networking" title="Link to this heading">¶</a></h3>
+<p>Traditional network security models assume high levels of trust at
+specific layers. You might trust your ISP to deliver packets without inspection,
+or trust your VPN provider to handle your traffic, or trust the network
+administrator to configure firewalls appropriately. These trust relationships
+create vulnerabilities and dependencies.</p>
+<p>Reticulum is designed to function in <strong>open, trustless environments</strong>. This
+means the protocol makes no assumptions about the trustworthiness of the network
+infrastructure, the other participants, or the transport mediums. Every aspect
+of communication is secured cryptographically:</p>
+<ul class="simple">
+<li><p><strong>Traffic encryption:</strong> All traffic to single destinations is encrypted using
+ephemeral keys.</p></li>
+<li><p><strong>Source anonymity:</strong> Reticulum packets do not include source addresses.
+An observer intercepting a packet cannot determine who sent it, only who it is
+addressed to (unless IFAC is enabled, in which case nothing can be determined).
+This provides initiator anonymity by default.</p></li>
+<li><p><strong>Path verification:</strong> The announce mechanism includes cryptographic signatures that
+prove the authenticity of destination announcements.</p></li>
+<li><p><strong>Unforgeable delivery confirmations:</strong> When a destination proves receipt of a
+packet, the proof is signed with the destination’s identity key. This prevents
+false acknowledgments and ensures reliable delivery verification.</p></li>
+<li><p><strong>Interface authentication:</strong> When using Interface Access Codes (IFAC), packets
+on authenticated interfaces carry signatures derived from a shared secret. Only
+nodes with the correct network name and passphrase can generate valid packets, allowing creation
+of virtual private networks on shared mediums.</p></li>
+</ul>
+<p>The trustless design has important consequences for network design:</p>
+<ul class="simple">
+<li><p><strong>Open-access networks are viable:</strong> You can build networks that anyone can
+join without pre-approval. Because traffic is encrypted and authenticated end-
+to-end, participants cannot interfere with each other’s private communication,
+even if they share the same transport infrastructure.</p></li>
+<li><p><strong>No traffic inspection or prioritization:</strong> Because traffic contents and
+sources are opaque to intermediate nodes, there is no mechanism for filtering,
+prioritizing, or throttling traffic based on its type or origin. All traffic
+is treated equally. From a neutrality perspective, this is a feature.</p></li>
+<li><p><strong>Adversarial resilience:</strong> The network can operate even if some nodes are
+malicious or controlled by adversaries. While a malicious Transport Node could
+refuse to forward certain traffic or drop packets, it cannot decrypt, modify,
+or impersonate legitimate traffic. Redundant paths and multiple Transport Nodes
+mitigate the impact of malicious nodes.</p></li>
+</ul>
+<p>Of course, you can also create closed networks. Interface Access
+Codes allow you to restrict participation on specific interfaces. Network
+Identities enable you to verify that discovered interfaces belong to trusted
+operators. Blackhole management lets you block malicious identities. Reticulum
+provides both the tools for open networks and the controls for closed ones. The
+choice is yours based on your requirements.</p>
+</section>
+<section id="heterogeneous-connectivity">
+<h3>Heterogeneous Connectivity<a class="headerlink" href="#heterogeneous-connectivity" title="Link to this heading">¶</a></h3>
+<p>In conventional networking, mixing different transport mediums typically requires
+gateways, translation layers, and careful configuration. A WiFi network doesn’t
+natively interoperate with a packet radio network without additional infrastructure,
+and you can’t just download a car over a serial port, or send an encrypted message
+in a QR code.</p>
+<p>Reticulum treats <strong>heterogeneity as a core premise</strong>. The protocol is designed
+to seamlessly mix mediums with vastly different characteristics:</p>
+<ul class="simple">
+<li><p><strong>Bandwidth:</strong> LoRa links operating at a few hundred bits per second can
+interconnect with gigabit Ethernet backbones. Reticulum automatically manages
+the flow of information, prioritizing local traffic on slow segments while
+allowing global convergence.</p></li>
+<li><p><strong>Latency:</strong> Satellite links with multi-second latency can coexist with local
+links measured in milliseconds. The transport system handles timing, asynchronous
+delivery and retransmissions transparently.</p></li>
+<li><p><strong>Topology:</strong> Point-to-point microwave links, broadcast radio networks,
+switched Ethernet fabrics, and virtual tunnels over the Internet can all be
+part of the same Reticulum network.</p></li>
+<li><p><strong>Reliability:</strong> Intermittent connections that come and go (such as mobile
+devices or opportunistic radio contacts) can participate alongside always-on
+infrastructure. Reticulum gracefully handles link loss and reconnection.</p></li>
+</ul>
+<p>This heterogeneity is achieved through several design elements:</p>
+<ul class="simple">
+<li><p><strong>Expandable, medium-agnostic interface system:</strong> Reticulum communicates with the physical
+world through interface modules. Adding support for a new medium is a matter
+of implementing an interface class. The protocol itself remains unchanged.</p></li>
+<li><p><strong>Interface modes:</strong> Different modes (<code class="docutils literal notranslate"><span class="pre">full</span></code>, <code class="docutils literal notranslate"><span class="pre">gateway</span></code>, <code class="docutils literal notranslate"><span class="pre">access_point</span></code>,
+<code class="docutils literal notranslate"><span class="pre">roaming</span></code>, <code class="docutils literal notranslate"><span class="pre">boundary</span></code>) allow you to configure how interfaces interact with
+the wider network based on their characteristics and role.</p></li>
+<li><p><strong>Announce propagation rules:</strong> Announces are forwarded between interfaces
+according to rules that account for bandwidth limitations and interface modes.
+Slow segments are not overwhelmed by traffic from fast segments.</p></li>
+<li><p><strong>Local traffic prioritization:</strong> When bandwidth is constrained, Reticulum
+prioritizes announces for nearby destinations. This ensures that local
+connectivity remains functional even when global convergence is incomplete.</p></li>
+</ul>
+<p>For network designers, this means you are free to use whatever mediums are
+available, affordable, or appropriate for your situation. You might use LoRa for
+wide-area low-bandwidth coverage, WiFi for local high-capacity links, I2P for
+anonymous Internet connectivity, and Ethernet for infrastructure backhauls, all
+within the same network. Reticulum handles the translation and coordination
+automatically.</p>
+<p>The key design consideration is not whether different mediums can work together
+(they can), but <strong>how</strong> they should work together based on your goals. A node
+with multiple interfaces spanning heterogeneous mediums needs to be configured
+with appropriate interface modes so that traffic flows efficiently. A gateway
+connecting a slow LoRa segment to a fast Internet backbone should be configured
+differently than a mobile device roaming between radio cells.</p>
 </section>
 </section>
 </section>
@@ -433,12 +594,12 @@ connected outliers are now an integral part of the network.</p>
       <footer>
         
         <div class="related-pages">
-          <a class="next-page" href="support.html">
+          <a class="next-page" href="git.html">
               <div class="page-info">
                 <div class="context">
                   <span>Next</span>
                 </div>
-                <div class="title">Support Reticulum</div>
+                <div class="title">Git Over Reticulum</div>
               </div>
               <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
             </a>
@@ -483,11 +644,12 @@ connected outliers are now an integral part of the network.</p>
           <div class="toc-tree">
             <ul>
 <li><a class="reference internal" href="#">Building Networks</a><ul>
-<li><a class="reference internal" href="#concepts-overview">Concepts &amp; Overview</a></li>
-<li><a class="reference internal" href="#example-scenarios">Example Scenarios</a><ul>
-<li><a class="reference internal" href="#interconnected-lora-sites">Interconnected LoRa Sites</a></li>
-<li><a class="reference internal" href="#bridging-over-the-internet">Bridging Over the Internet</a></li>
-<li><a class="reference internal" href="#growth-and-convergence">Growth and Convergence</a></li>
+<li><a class="reference internal" href="#concepts-overview">Concepts &amp; Overview</a><ul>
+<li><a class="reference internal" href="#introductory-considerations">Introductory Considerations</a></li>
+<li><a class="reference internal" href="#destinations-not-addresses">Destinations, Not Addresses</a></li>
+<li><a class="reference internal" href="#transport-nodes-and-instances">Transport Nodes and Instances</a></li>
+<li><a class="reference internal" href="#trustless-networking">Trustless Networking</a></li>
+<li><a class="reference internal" href="#heterogeneous-connectivity">Heterogeneous Connectivity</a></li>
 </ul>
 </li>
 </ul>
@@ -501,7 +663,7 @@ connected outliers are now an integral part of the network.</p>
       
     </aside>
   </div>
-</div><script src="_static/documentation_options.js?v=baaebd52"></script>
+</div><script src="_static/documentation_options.js?v=590429e0"></script>
     <script src="_static/doctools.js?v=9bcbadda"></script>
     <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="_static/scripts/furo.js?v=46bd48cc"></script>

docs/manual/reference.html

@@ -3,11 +3,11 @@
   <head><meta charset="utf-8">
     <meta name="viewport" content="width=device-width,initial-scale=1">
     <meta name="color-scheme" content="light dark"><meta name="viewport" content="width=device-width, initial-scale=1" />
-<link rel="index" title="Index" href="genindex.html"><link rel="search" title="Search" href="search.html"><link rel="prev" title="Code Examples" href="examples.html">
+<link rel="index" title="Index" href="genindex.html"><link rel="search" title="Search" href="search.html"><link rel="prev" title="Reticulum License" href="license.html">
         <link rel="prefetch" href="_static/rns_logo_512.png" as="image">
 
     <!-- Generated with Sphinx 8.2.3 and Furo 2025.09.25.dev1 -->
-        <title>API Reference - Reticulum Network Stack 1.0.3 documentation</title>
+        <title>API Reference - Reticulum Network Stack 1.2.3 documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d111a655" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=580074bf" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
@@ -180,7 +180,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 1.0.3 documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 1.2.3 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -204,7 +204,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 1.0.3 documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 1.2.3 documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@@ -215,13 +215,17 @@
   <ul>
 <li class="toctree-l1"><a class="reference internal" href="whatis.html">What is Reticulum?</a></li>
 <li class="toctree-l1"><a class="reference internal" href="gettingstartedfast.html">Getting Started Fast</a></li>
+<li class="toctree-l1"><a class="reference internal" href="zen.html">Zen of Reticulum</a></li>
+<li class="toctree-l1"><a class="reference internal" href="software.html">Programs Using Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
 <li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
 <li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks</a></li>
+<li class="toctree-l1"><a class="reference internal" href="git.html">Git Over Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a></li>
+<li class="toctree-l1"><a class="reference internal" href="license.html">Reticulum License</a></li>
 </ul>
 <ul class="current">
 <li class="toctree-l1 current current-page"><a class="current reference internal" href="#">API Reference</a></li>
@@ -395,6 +399,65 @@ can remotely query and manage this instance.</p>
 </dl>
 </dd></dl>
 
+<dl class="py method">
+<dt class="sig sig-object py" id="RNS.Reticulum.required_discovery_value">
+<em class="property"><span class="k"><span class="pre">static</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">required_discovery_value</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#RNS.Reticulum.required_discovery_value" title="Link to this definition">¶</a></dt>
+<dd><p>Returns the required stamp value for a discovered interface
+to be considered valid and remembered.</p>
+<dl class="field-list simple">
+<dt class="field-odd">Returns<span class="colon">:</span></dt>
+<dd class="field-odd"><p>The required stamp value as an integer.</p>
+</dd>
+</dl>
+</dd></dl>
+
+<dl class="py method">
+<dt class="sig sig-object py" id="RNS.Reticulum.publish_blackhole_enabled">
+<em class="property"><span class="k"><span class="pre">static</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">publish_blackhole_enabled</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#RNS.Reticulum.publish_blackhole_enabled" title="Link to this definition">¶</a></dt>
+<dd><p>Returns whether blackhole list publishing is enabled for the
+running instance.</p>
+<dl class="field-list simple">
+<dt class="field-odd">Returns<span class="colon">:</span></dt>
+<dd class="field-odd"><p>True if blackhole list publishing is enabled, False if not.</p>
+</dd>
+</dl>
+</dd></dl>
+
+<dl class="py method">
+<dt class="sig sig-object py" id="RNS.Reticulum.blackhole_sources">
+<em class="property"><span class="k"><span class="pre">static</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">blackhole_sources</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#RNS.Reticulum.blackhole_sources" title="Link to this definition">¶</a></dt>
+<dd><p>Returns the list of transport identity hashes from which
+blackhole lists are sourced.</p>
+<dl class="field-list simple">
+<dt class="field-odd">Returns<span class="colon">:</span></dt>
+<dd class="field-odd"><p>A list of identity hashes.</p>
+</dd>
+</dl>
+</dd></dl>
+
+<dl class="py method">
+<dt class="sig sig-object py" id="RNS.Reticulum.discovered_interfaces">
+<em class="property"><span class="k"><span class="pre">static</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">discovered_interfaces</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#RNS.Reticulum.discovered_interfaces" title="Link to this definition">¶</a></dt>
+<dd><p>Returns a list of interfaces discovered over the network.</p>
+<dl class="field-list simple">
+<dt class="field-odd">Returns<span class="colon">:</span></dt>
+<dd class="field-odd"><p>A list of discovered interfaces.</p>
+</dd>
+</dl>
+</dd></dl>
+
+<dl class="py method">
+<dt class="sig sig-object py" id="RNS.Reticulum.interface_discovery_sources">
+<em class="property"><span class="k"><span class="pre">static</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">interface_discovery_sources</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#RNS.Reticulum.interface_discovery_sources" title="Link to this definition">¶</a></dt>
+<dd><p>Returns the list of network identity hashes from which
+interfaces are discovered.</p>
+<dl class="field-list simple">
+<dt class="field-odd">Returns<span class="colon">:</span></dt>
+<dd class="field-odd"><p>A list of identity hashes.</p>
+</dd>
+</dl>
+</dd></dl>
+
 </dd></dl>
 
 <p id="api-identity"><h3> Identity </h3></p>
@@ -444,7 +507,7 @@ for addressable hashes and other purposes. Non-configurable.</p>
 
 <dl class="py method">
 <dt class="sig sig-object py" id="RNS.Identity.recall">
-<em class="property"><span class="k"><span class="pre">static</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">recall</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">target_hash</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">from_identity_hash</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#RNS.Identity.recall" title="Link to this definition">¶</a></dt>
+<em class="property"><span class="k"><span class="pre">static</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">recall</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">target_hash</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">from_identity_hash</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">_no_use</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#RNS.Identity.recall" title="Link to this definition">¶</a></dt>
 <dd><p>Recall identity for a destination or identity hash. By default, this function
 will return the identity associated with a given <em>destination</em> hash. As an
 example, if you know the <code class="docutils literal notranslate"><span class="pre">lxmf.delivery</span></code> destination hash of an endpoint,
@@ -466,7 +529,7 @@ search for an identity from a known <em>identity hash</em>, by setting the
 
 <dl class="py method">
 <dt class="sig sig-object py" id="RNS.Identity.recall_app_data">
-<em class="property"><span class="k"><span class="pre">static</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">recall_app_data</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">destination_hash</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#RNS.Identity.recall_app_data" title="Link to this definition">¶</a></dt>
+<em class="property"><span class="k"><span class="pre">static</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">recall_app_data</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">destination_hash</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">_no_use</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#RNS.Identity.recall_app_data" title="Link to this definition">¶</a></dt>
 <dd><p>Recall last heard app_data for a destination hash.</p>
 <dl class="field-list simple">
 <dt class="field-odd">Parameters<span class="colon">:</span></dt>
@@ -2125,6 +2188,25 @@ announces. See the <a class="reference internal" href="examples.html#example-ann
 </dl>
 </dd></dl>
 
+<dl class="py method">
+<dt class="sig sig-object py" id="RNS.Transport.await_path">
+<em class="property"><span class="k"><span class="pre">static</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">await_path</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">destination_hash</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">timeout</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">on_interface</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#RNS.Transport.await_path" title="Link to this definition">¶</a></dt>
+<dd><p>Requests a path to the destination from the network and
+blocks until the path is available, or the timeout is reached.</p>
+<dl class="field-list simple">
+<dt class="field-odd">Parameters<span class="colon">:</span></dt>
+<dd class="field-odd"><ul class="simple">
+<li><p><strong>destination_hash</strong> – A destination hash as <em>bytes</em>.</p></li>
+<li><p><strong>timeout</strong> – An optional timeout in seconds.</p></li>
+<li><p><strong>on_interface</strong> – If specified, the path request will only be sent on this interface. In normal use, Reticulum handles this automatically, and this parameter should not be used.</p></li>
+</ul>
+</dd>
+<dt class="field-even">Returns<span class="colon">:</span></dt>
+<dd class="field-even"><p><em>True</em> if a path to the destination is found, otherwise <em>False</em>.</p>
+</dd>
+</dl>
+</dd></dl>
+
 <dl class="py method">
 <dt class="sig sig-object py" id="RNS.Transport.request_path">
 <em class="property"><span class="k"><span class="pre">static</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">request_path</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">destination_hash</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">on_interface</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">tag</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">recursive</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#RNS.Transport.request_path" title="Link to this definition">¶</a></dt>
@@ -2151,14 +2233,14 @@ will announce it.</p>
         
         <div class="related-pages">
           
-          <a class="prev-page" href="examples.html">
+          <a class="prev-page" href="license.html">
               <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
               <div class="page-info">
                 <div class="context">
                   <span>Previous</span>
                 </div>
                 
-                <div class="title">Code Examples</div>
+                <div class="title">Reticulum License</div>
                 
               </div>
             </a>
@@ -2202,6 +2284,11 @@ will announce it.</p>
 <li><a class="reference internal" href="#RNS.Reticulum.transport_enabled"><code class="docutils literal notranslate"><span class="pre">transport_enabled()</span></code></a></li>
 <li><a class="reference internal" href="#RNS.Reticulum.link_mtu_discovery"><code class="docutils literal notranslate"><span class="pre">link_mtu_discovery()</span></code></a></li>
 <li><a class="reference internal" href="#RNS.Reticulum.remote_management_enabled"><code class="docutils literal notranslate"><span class="pre">remote_management_enabled()</span></code></a></li>
+<li><a class="reference internal" href="#RNS.Reticulum.required_discovery_value"><code class="docutils literal notranslate"><span class="pre">required_discovery_value()</span></code></a></li>
+<li><a class="reference internal" href="#RNS.Reticulum.publish_blackhole_enabled"><code class="docutils literal notranslate"><span class="pre">publish_blackhole_enabled()</span></code></a></li>
+<li><a class="reference internal" href="#RNS.Reticulum.blackhole_sources"><code class="docutils literal notranslate"><span class="pre">blackhole_sources()</span></code></a></li>
+<li><a class="reference internal" href="#RNS.Reticulum.discovered_interfaces"><code class="docutils literal notranslate"><span class="pre">discovered_interfaces()</span></code></a></li>
+<li><a class="reference internal" href="#RNS.Reticulum.interface_discovery_sources"><code class="docutils literal notranslate"><span class="pre">interface_discovery_sources()</span></code></a></li>
 </ul>
 </li>
 <li><a class="reference internal" href="#RNS.Identity"><code class="docutils literal notranslate"><span class="pre">Identity</span></code></a><ul>
@@ -2371,6 +2458,7 @@ will announce it.</p>
 <li><a class="reference internal" href="#RNS.Transport.hops_to"><code class="docutils literal notranslate"><span class="pre">hops_to()</span></code></a></li>
 <li><a class="reference internal" href="#RNS.Transport.next_hop"><code class="docutils literal notranslate"><span class="pre">next_hop()</span></code></a></li>
 <li><a class="reference internal" href="#RNS.Transport.next_hop_interface"><code class="docutils literal notranslate"><span class="pre">next_hop_interface()</span></code></a></li>
+<li><a class="reference internal" href="#RNS.Transport.await_path"><code class="docutils literal notranslate"><span class="pre">await_path()</span></code></a></li>
 <li><a class="reference internal" href="#RNS.Transport.request_path"><code class="docutils literal notranslate"><span class="pre">request_path()</span></code></a></li>
 </ul>
 </li>
@@ -2385,7 +2473,7 @@ will announce it.</p>
       
     </aside>
   </div>
-</div><script src="_static/documentation_options.js?v=baaebd52"></script>
+</div><script src="_static/documentation_options.js?v=590429e0"></script>
     <script src="_static/doctools.js?v=9bcbadda"></script>
     <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="_static/scripts/furo.js?v=46bd48cc"></script>

docs/manual/search.html

@@ -8,7 +8,7 @@
 
     <!-- Generated with Sphinx 8.2.3 and Furo 2025.09.25.dev1 -->
 <meta name="robots" content="noindex" />
-<title>Search - Reticulum Network Stack 1.0.3 documentation</title><link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d111a655" />
+<title>Search - Reticulum Network Stack 1.2.3 documentation</title><link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d111a655" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=580074bf" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo-extensions.css?v=8dab3a3b" />
@@ -180,7 +180,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 1.0.3 documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 1.2.3 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -204,7 +204,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 1.0.3 documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 1.2.3 documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="#" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@@ -215,13 +215,17 @@
   <ul>
 <li class="toctree-l1"><a class="reference internal" href="whatis.html">What is Reticulum?</a></li>
 <li class="toctree-l1"><a class="reference internal" href="gettingstartedfast.html">Getting Started Fast</a></li>
+<li class="toctree-l1"><a class="reference internal" href="zen.html">Zen of Reticulum</a></li>
+<li class="toctree-l1"><a class="reference internal" href="software.html">Programs Using Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
 <li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
 <li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks</a></li>
+<li class="toctree-l1"><a class="reference internal" href="git.html">Git Over Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a></li>
+<li class="toctree-l1"><a class="reference internal" href="license.html">Reticulum License</a></li>
 </ul>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="reference.html">API Reference</a></li>
@@ -299,7 +303,7 @@
       
     </aside>
   </div>
-</div><script src="_static/documentation_options.js?v=baaebd52"></script>
+</div><script src="_static/documentation_options.js?v=590429e0"></script>
     <script src="_static/doctools.js?v=9bcbadda"></script>
     <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="_static/scripts/furo.js?v=46bd48cc"></script>

docs/manual/software.html

@@ -0,0 +1,544 @@
+<!doctype html>
+<html class="no-js" lang="en" data-content_root="./">
+  <head><meta charset="utf-8">
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+    <meta name="color-scheme" content="light dark"><meta name="viewport" content="width=device-width, initial-scale=1" />
+<link rel="index" title="Index" href="genindex.html"><link rel="search" title="Search" href="search.html"><link rel="next" title="Using Reticulum on Your System" href="using.html"><link rel="prev" title="Zen of Reticulum" href="zen.html">
+        <link rel="prefetch" href="_static/rns_logo_512.png" as="image">
+
+    <!-- Generated with Sphinx 8.2.3 and Furo 2025.09.25.dev1 -->
+        <title>Programs Using Reticulum - Reticulum Network Stack 1.2.3 documentation</title>
+      <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d111a655" />
+    <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=580074bf" />
+    <link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
+    <link rel="stylesheet" type="text/css" href="_static/styles/furo-extensions.css?v=8dab3a3b" />
+    <link rel="stylesheet" type="text/css" href="_static/custom.css?v=bb3cebc5" />
+    
+    
+
+
+<style>
+  body {
+    --color-code-background: #f2f2f2;
+  --color-code-foreground: #1e1e1e;
+  
+  }
+  @media not print {
+    body[data-theme="dark"] {
+      --color-code-background: #202020;
+  --color-code-foreground: #d0d0d0;
+  --color-background-primary: #202b38;
+  --color-background-secondary: #161f27;
+  --color-foreground-primary: #dbdbdb;
+  --color-foreground-secondary: #a9b1ba;
+  --color-brand-primary: #41adff;
+  --color-background-hover: #161f27;
+  --color-api-name: #ffbe85;
+  --color-api-pre-name: #efae75;
+  
+    }
+    @media (prefers-color-scheme: dark) {
+      body:not([data-theme="light"]) {
+        --color-code-background: #202020;
+  --color-code-foreground: #d0d0d0;
+  --color-background-primary: #202b38;
+  --color-background-secondary: #161f27;
+  --color-foreground-primary: #dbdbdb;
+  --color-foreground-secondary: #a9b1ba;
+  --color-brand-primary: #41adff;
+  --color-background-hover: #161f27;
+  --color-api-name: #ffbe85;
+  --color-api-pre-name: #efae75;
+  
+      }
+    }
+  }
+</style></head>
+  <body>
+    
+    <script>
+      document.body.dataset.theme = localStorage.getItem("theme") || "auto";
+    </script>
+    
+
+<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
+  <symbol id="svg-toc" viewBox="0 0 24 24">
+    <title>Contents</title>
+    <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 1024 1024">
+      <path d="M408 442h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8zm-8 204c0 4.4 3.6 8 8 8h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56zm504-486H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zm0 632H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zM115.4 518.9L271.7 642c5.8 4.6 14.4.5 14.4-6.9V388.9c0-7.4-8.5-11.5-14.4-6.9L115.4 505.1a8.74 8.74 0 0 0 0 13.8z"/>
+    </svg>
+  </symbol>
+  <symbol id="svg-menu" viewBox="0 0 24 24">
+    <title>Menu</title>
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+      stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-menu">
+      <line x1="3" y1="12" x2="21" y2="12"></line>
+      <line x1="3" y1="6" x2="21" y2="6"></line>
+      <line x1="3" y1="18" x2="21" y2="18"></line>
+    </svg>
+  </symbol>
+  <symbol id="svg-arrow-right" viewBox="0 0 24 24">
+    <title>Expand</title>
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+      stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-chevron-right">
+      <polyline points="9 18 15 12 9 6"></polyline>
+    </svg>
+  </symbol>
+  <symbol id="svg-sun" viewBox="0 0 24 24">
+    <title>Light mode</title>
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+      stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="feather-sun">
+      <circle cx="12" cy="12" r="5"></circle>
+      <line x1="12" y1="1" x2="12" y2="3"></line>
+      <line x1="12" y1="21" x2="12" y2="23"></line>
+      <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line>
+      <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line>
+      <line x1="1" y1="12" x2="3" y2="12"></line>
+      <line x1="21" y1="12" x2="23" y2="12"></line>
+      <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line>
+      <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line>
+    </svg>
+  </symbol>
+  <symbol id="svg-moon" viewBox="0 0 24 24">
+    <title>Dark mode</title>
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+      stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-moon">
+      <path stroke="none" d="M0 0h24v24H0z" fill="none" />
+      <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z" />
+    </svg>
+  </symbol>
+  <symbol id="svg-sun-with-moon" viewBox="0 0 24 24">
+    <title>Auto light/dark, in light mode</title>
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+      stroke-width="1" stroke-linecap="round" stroke-linejoin="round"
+      class="icon-custom-derived-from-feather-sun-and-tabler-moon">
+      <path style="opacity: 50%" d="M 5.411 14.504 C 5.471 14.504 5.532 14.504 5.591 14.504 C 3.639 16.319 4.383 19.569 6.931 20.352 C 7.693 20.586 8.512 20.551 9.25 20.252 C 8.023 23.207 4.056 23.725 2.11 21.184 C 0.166 18.642 1.702 14.949 4.874 14.536 C 5.051 14.512 5.231 14.5 5.411 14.5 L 5.411 14.504 Z"/>
+      <line x1="14.5" y1="3.25" x2="14.5" y2="1.25"/>
+      <line x1="14.5" y1="15.85" x2="14.5" y2="17.85"/>
+      <line x1="10.044" y1="5.094" x2="8.63" y2="3.68"/>
+      <line x1="19" y1="14.05" x2="20.414" y2="15.464"/>
+      <line x1="8.2" y1="9.55" x2="6.2" y2="9.55"/>
+      <line x1="20.8" y1="9.55" x2="22.8" y2="9.55"/>
+      <line x1="10.044" y1="14.006" x2="8.63" y2="15.42"/>
+      <line x1="19" y1="5.05" x2="20.414" y2="3.636"/>
+      <circle cx="14.5" cy="9.55" r="3.6"/>
+    </svg>
+  </symbol>
+  <symbol id="svg-moon-with-sun" viewBox="0 0 24 24">
+    <title>Auto light/dark, in dark mode</title>
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+      stroke-width="1" stroke-linecap="round" stroke-linejoin="round"
+      class="icon-custom-derived-from-feather-sun-and-tabler-moon">
+      <path d="M 8.282 7.007 C 8.385 7.007 8.494 7.007 8.595 7.007 C 5.18 10.184 6.481 15.869 10.942 17.24 C 12.275 17.648 13.706 17.589 15 17.066 C 12.851 22.236 5.91 23.143 2.505 18.696 C -0.897 14.249 1.791 7.786 7.342 7.063 C 7.652 7.021 7.965 7 8.282 7 L 8.282 7.007 Z"/>
+      <line style="opacity: 50%" x1="18" y1="3.705" x2="18" y2="2.5"/>
+      <line style="opacity: 50%" x1="18" y1="11.295" x2="18" y2="12.5"/>
+      <line style="opacity: 50%" x1="15.316" y1="4.816" x2="14.464" y2="3.964"/>
+      <line style="opacity: 50%" x1="20.711" y1="10.212" x2="21.563" y2="11.063"/>
+      <line style="opacity: 50%" x1="14.205" y1="7.5" x2="13.001" y2="7.5"/>
+      <line style="opacity: 50%" x1="21.795" y1="7.5" x2="23" y2="7.5"/>
+      <line style="opacity: 50%" x1="15.316" y1="10.184" x2="14.464" y2="11.036"/>
+      <line style="opacity: 50%" x1="20.711" y1="4.789" x2="21.563" y2="3.937"/>
+      <circle style="opacity: 50%" cx="18" cy="7.5" r="2.169"/>
+    </svg>
+  </symbol>
+  <symbol id="svg-pencil" viewBox="0 0 24 24">
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+      stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-pencil-code">
+      <path d="M4 20h4l10.5 -10.5a2.828 2.828 0 1 0 -4 -4l-10.5 10.5v4" />
+      <path d="M13.5 6.5l4 4" />
+      <path d="M20 21l2 -2l-2 -2" />
+      <path d="M17 17l-2 2l2 2" />
+    </svg>
+  </symbol>
+  <symbol id="svg-eye" viewBox="0 0 24 24">
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+      stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-eye-code">
+      <path stroke="none" d="M0 0h24v24H0z" fill="none" />
+      <path d="M10 12a2 2 0 1 0 4 0a2 2 0 0 0 -4 0" />
+      <path
+        d="M11.11 17.958c-3.209 -.307 -5.91 -2.293 -8.11 -5.958c2.4 -4 5.4 -6 9 -6c3.6 0 6.6 2 9 6c-.21 .352 -.427 .688 -.647 1.008" />
+      <path d="M20 21l2 -2l-2 -2" />
+      <path d="M17 17l-2 2l2 2" />
+    </svg>
+  </symbol>
+</svg>
+
+<input type="checkbox" class="sidebar-toggle" name="__navigation" id="__navigation" aria-label="Toggle site navigation sidebar">
+<input type="checkbox" class="sidebar-toggle" name="__toc" id="__toc" aria-label="Toggle table of contents sidebar">
+<label class="overlay sidebar-overlay" for="__navigation"></label>
+<label class="overlay toc-overlay" for="__toc"></label>
+
+<a class="skip-to-content muted-link" href="#furo-main-content">Skip to content</a>
+
+
+
+<div class="page">
+  <header class="mobile-header">
+    <div class="header-left">
+      <label class="nav-overlay-icon" for="__navigation">
+        <span class="icon"><svg><use href="#svg-menu"></use></svg></span>
+      </label>
+    </div>
+    <div class="header-center">
+      <a href="index.html"><div class="brand">Reticulum Network Stack 1.2.3 documentation</div></a>
+    </div>
+    <div class="header-right">
+      <div class="theme-toggle-container theme-toggle-header">
+        <button class="theme-toggle" aria-label="Toggle Light / Dark / Auto color theme">
+          <svg class="theme-icon-when-auto-light"><use href="#svg-sun-with-moon"></use></svg>
+          <svg class="theme-icon-when-auto-dark"><use href="#svg-moon-with-sun"></use></svg>
+          <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg>
+          <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg>
+        </button>
+      </div>
+      <label class="toc-overlay-icon toc-header-icon" for="__toc">
+        <span class="icon"><svg><use href="#svg-toc"></use></svg></span>
+      </label>
+    </div>
+  </header>
+  <aside class="sidebar-drawer">
+    <div class="sidebar-container">
+      
+      <div class="sidebar-sticky"><a class="sidebar-brand" href="index.html">
+  <div class="sidebar-logo-container">
+    <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
+  </div>
+  
+  <span class="sidebar-brand-text">Reticulum Network Stack 1.2.3 documentation</span>
+  
+</a><form class="sidebar-search-container" method="get" action="search.html" role="search">
+  <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
+  <input type="hidden" name="check_keywords" value="yes">
+  <input type="hidden" name="area" value="default">
+</form>
+<div id="searchbox"></div><div class="sidebar-scroll"><div class="sidebar-tree">
+  <ul class="current">
+<li class="toctree-l1"><a class="reference internal" href="whatis.html">What is Reticulum?</a></li>
+<li class="toctree-l1"><a class="reference internal" href="gettingstartedfast.html">Getting Started Fast</a></li>
+<li class="toctree-l1"><a class="reference internal" href="zen.html">Zen of Reticulum</a></li>
+<li class="toctree-l1 current current-page"><a class="current reference internal" href="#">Programs Using Reticulum</a></li>
+<li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
+<li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
+<li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
+<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
+<li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks</a></li>
+<li class="toctree-l1"><a class="reference internal" href="git.html">Git Over Reticulum</a></li>
+<li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a></li>
+<li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a></li>
+<li class="toctree-l1"><a class="reference internal" href="license.html">Reticulum License</a></li>
+</ul>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="reference.html">API Reference</a></li>
+</ul>
+
+</div>
+</div>
+
+      </div>
+      
+    </div>
+  </aside>
+  <div class="main">
+    <div class="content">
+      <div class="article-container">
+        <a href="#" class="back-to-top muted-link">
+          <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
+            <path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8v12z"></path>
+          </svg>
+          <span>Back to top</span>
+        </a>
+        <div class="content-icon-container">
+          <div class="theme-toggle-container theme-toggle-content">
+            <button class="theme-toggle" aria-label="Toggle Light / Dark / Auto color theme">
+              <svg class="theme-icon-when-auto-light"><use href="#svg-sun-with-moon"></use></svg>
+              <svg class="theme-icon-when-auto-dark"><use href="#svg-moon-with-sun"></use></svg>
+              <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg>
+              <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg>
+            </button>
+          </div>
+          <label class="toc-overlay-icon toc-content-icon" for="__toc">
+            <span class="icon"><svg><use href="#svg-toc"></use></svg></span>
+          </label>
+        </div>
+        <article role="main" id="furo-main-content">
+          <section id="programs-using-reticulum">
+<span id="software-main"></span><h1>Programs Using Reticulum<a class="headerlink" href="#programs-using-reticulum" title="Link to this heading">¶</a></h1>
+<p>This chapter provides a non-exhaustive list of notable programs, systems and application-layer
+protocols that have been built using Reticulum.</p>
+<p>These programs will let you get a feel for how Reticulum works. Most of them have been designed
+to run well even over slow networks based on LoRa or packet radio, but all can also be used over fast
+links, such as local WiFi, wired Ethernet, the Internet, or any combination.</p>
+<p>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.</p>
+<section id="programs-utilities">
+<h2>Programs &amp; Utilities<a class="headerlink" href="#programs-utilities" title="Link to this heading">¶</a></h2>
+<p>Many different applications using Reticulum already exist, serving a wide variety of purposes
+from day-to-day communication and information sharing to systems administration and tackling
+advanced networking and communications challenges.</p>
+<p>Development of Reticulum-based applications and systems is ongoing, so consider this list
+a non-exhaustive starting point of <em>some</em> of the options available. With a bit of searching,
+primarily over Reticulum itself, you will find many more interesting things.</p>
+<section id="remote-shell">
+<h3>Remote Shell<a class="headerlink" href="#remote-shell" title="Link to this heading">¶</a></h3>
+<p>The <a class="reference external" href="https://github.com/acehoss/rnsh">rnsh</a> program lets you establish fully interactive
+remote shell sessions over Reticulum. It also allows you to pipe any program to or from a
+remote system, and is similar to how <code class="docutils literal notranslate"><span class="pre">ssh</span></code> works. The <code class="docutils literal notranslate"><span class="pre">rnsh</span></code> program is very efficient, and
+can facilitate fully interactive shell sessions, even over extremely low-bandwidth links,
+such as LoRa or packet radio.</p>
+<p>In addition to the default, fully interactive terminal mode,
+for extremely limited links, <code class="docutils literal notranslate"><span class="pre">rnsh</span></code> offers line-interactive mode, allowing you to interact
+with remote systems, even when link throughput is counted in a few hundreds of bits per second.</p>
+</section>
+<section id="nomad-network">
+<h3>Nomad Network<a class="headerlink" href="#nomad-network" title="Link to this heading">¶</a></h3>
+<p>The terminal-based program <a class="reference external" href="https://github.com/markqvist/nomadnet">Nomad Network</a>
+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.</p>
+<a class="reference external image-reference" href="https://github.com/markqvist/nomadnet"><img alt="_images/nomadnet_3.png" src="_images/nomadnet_3.png" />
+</a>
+<p><a class="reference external" href="https://github.com/markqvist/nomadnet">Nomad Network</a> is a user-facing client
+for the messaging and information-sharing protocol LXMF.</p>
+</section>
+<section id="rns-page-node">
+<h3>RNS Page Node<a class="headerlink" href="#rns-page-node" title="Link to this heading">¶</a></h3>
+<p><a class="reference external" href="https://git.quad4.io/RNS-Things/rns-page-node">RNS Page Node</a> is a simple way to serve pages and files to any other Nomad Network compatible client. Drop-in replacement for NomadNet nodes that primarily serve pages and files.</p>
+</section>
+<section id="retipedia">
+<h3>Retipedia<a class="headerlink" href="#retipedia" title="Link to this heading">¶</a></h3>
+<p>You can host the entirity of Wikipedia (or any <code class="docutils literal notranslate"><span class="pre">.zim</span></code>) file to other Nomad Network clients using <a class="reference external" href="https://github.com/RFnexus/Retipedia">Retipedia</a>.</p>
+</section>
+<section id="sideband">
+<h3>Sideband<a class="headerlink" href="#sideband" title="Link to this heading">¶</a></h3>
+<p>If you would rather use an LXMF client with a graphical user interface, you can take
+a look at <a class="reference external" href="https://unsigned.io/sideband">Sideband</a>, which is available for Android,
+Linux, macOS and Windows. Sideband is an advanced LXMF and LXST client, and a multi-purpose Reticulum
+utility, with features and functionality targeted at advanced users.</p>
+<a class="reference external image-reference" href="https://unsigned.io/sideband"><img alt="_images/sideband_devices.webp" class="align-center" src="_images/sideband_devices.webp" />
+</a>
+<p>Sideband allows you to communicate with other people or LXMF-compatible
+systems over Reticulum networks using LoRa, Packet Radio, WiFi, I2P, Encrypted QR
+Paper Messages, or anything else Reticulum supports.</p>
+<p>It also interoperates with all other LXMF clients, and provides advanced features such as voice messaging,
+real-time voice calls, file attachments, private telemetry sharing, and a full
+plugin system for expandability.</p>
+</section>
+<section id="meshchatx">
+<h3>MeshChatX<a class="headerlink" href="#meshchatx" title="Link to this heading">¶</a></h3>
+<p>A <a class="reference external" href="https://git.quad4.io/RNS-Things/MeshChatX">Reticulum MeshChat fork from the future</a>, with the goal of providing everything you need for Reticulum, LXMF, and LXST in one beautiful and feature-rich application. This project is separate from the original Reticulum MeshChat project, and is not affiliated with the original project.</p>
+<a class="reference external image-reference" href="https://git.quad4.io/RNS-Things/MeshChatX"><img alt="_images/meshchatx.webp" class="align-center" src="_images/meshchatx.webp" />
+</a>
+<p>Features include full LXST support, custom voicemail, phonebook, contact sharing, and ringtone support, multi-identity handling, modern UI/UX, offline documentation, expanded tools, page archiving, integrated maps, telemetry and improved application security.</p>
+</section>
+<section id="meshchat">
+<h3>MeshChat<a class="headerlink" href="#meshchat" title="Link to this heading">¶</a></h3>
+<p>The <a class="reference external" href="https://github.com/liamcottle/reticulum-meshchat">Reticulum MeshChat</a> application
+is a user-friendly LXMF client for Linux, macOS and Windows, that also includes a Nomad Network
+page browser and other interesting functionality.</p>
+<a class="reference external image-reference" href="https://github.com/liamcottle/reticulum-meshchat"><img alt="_images/meshchat_1.webp" class="align-center" src="_images/meshchat_1.webp" />
+</a>
+<p>Reticulum MeshChat is of course also compatible with Sideband and Nomad Network, or
+any other LXMF client.</p>
+</section>
+<section id="columba">
+<h3>Columba<a class="headerlink" href="#columba" title="Link to this heading">¶</a></h3>
+<p><a class="reference external" href="https://github.com/torlando-tech/columba/">Columba</a> is a simple and familiar LXMF
+messaging app Android, built with a native Android interface and Material Design 3.</p>
+<a class="reference external image-reference" href="https://github.com/torlando-tech/columba/"><img alt="_images/columba.webp" class="align-center" src="_images/columba.webp" style="width: 25%;" />
+</a>
+<p>While still in early and very active development, it is of course also compatible
+with all other LXMF clients, and allows you to message seamlessly with anyone else
+using LXMF.</p>
+</section>
+<section id="reticulum-relay-chat">
+<h3>Reticulum Relay Chat<a class="headerlink" href="#reticulum-relay-chat" title="Link to this heading">¶</a></h3>
+<p><a class="reference external" href="https://rrc.kc1awv.net/">Reticulum Relay Chat</a> is a live chat system built on top of the Reticulum Network Stack. It exists to let people talk to each other in real time over Reticulum without dragging in message databases, synchronization engines, or architectural commitments they did not ask for.</p>
+<p>The <a class="reference external" href="https://github.com/kc1awv/rrcd">rrcd</a> program provides a functional, reference RRC hub-server daemon implementation. RRC user clients include <a class="reference external" href="https://github.com/kc1awv/rrc-gui">rrc-gui</a> and <a class="reference external" href="https://github.com/kc1awv/rrc-web">rrc-web</a>.</p>
+<p>RRC is closer in spirit to IRC than to modern “everything platforms.” You connect, you join a room, you talk, and then you leave. If you were present, you saw the conversation. If you were not, the conversation did not wait for you. This is not an accident. This is the entire design.</p>
+</section>
+<section id="retibbs">
+<h3>RetiBBS<a class="headerlink" href="#retibbs" title="Link to this heading">¶</a></h3>
+<p><a class="reference external" href="https://github.com/kc1awv/RetiBBS">RetiBBS</a> is a bulletin board system implementation for Reticulum networks.</p>
+<a class="reference external image-reference" href="https://github.com/kc1awv/RetiBBS"><img alt="_images/retibbs.webp" class="align-center" src="_images/retibbs.webp" />
+</a>
+<p>RetiBBS allows users to communicate through message boards in a secure manner.</p>
+</section>
+<section id="rbrowser">
+<h3>RBrowser<a class="headerlink" href="#rbrowser" title="Link to this heading">¶</a></h3>
+<p>The <a class="reference external" href="https://github.com/fr33n0w/rBrowser">rBrowser</a> program is a cross-platform, standalone, web-based browser for exploring NomadNetwork Nodes over Reticulum Network. It automatically discovers NomadNet nodes through network announces and provides a user-friendly interface for browsing distributed content with Micron markup support.</p>
+<a class="reference external image-reference" href="https://github.com/fr33n0w/rBrowser"><img alt="_images/rbrowser.webp" class="align-center" src="_images/rbrowser.webp" />
+</a>
+<p>Includes useful features like automatic listening for announce, adding nodes to favorites, browsing and rendering any kind of NomadNet links, downloading files from remote nodes, a unique local NomadNet Search Engine and more.</p>
+</section>
+<section id="reticulum-network-telephone">
+<h3>Reticulum Network Telephone<a class="headerlink" href="#reticulum-network-telephone" title="Link to this heading">¶</a></h3>
+<p>The <code class="docutils literal notranslate"><span class="pre">rnphone</span></code> program, included as part of the <a class="reference external" href="https://github.com/markqvist/LXST">LXST</a> package is a command-line Reticulum telephone utility and daemon, that allows building physical, hardware telephones for LXST and Reticulum, as well as simply performing calls via the command line.</p>
+<a class="reference external image-reference" href="https://github.com/markqvist/LXST"><img alt="_images/rnphone.webp" class="align-center" src="_images/rnphone.webp" />
+</a>
+<p>It supports interfacing directly with hardware peripherals such as GPIO keypads and LCD displays, providing a modular system for building secure hardware telephones.</p>
+</section>
+<section id="lxst-phone">
+<h3>LXST Phone<a class="headerlink" href="#lxst-phone" title="Link to this heading">¶</a></h3>
+<p>The <a class="reference external" href="https://github.com/kc1awv/lxst_phone">LXST Phone</a> program is a cross-platform desktop application for performing LXST voice calls over Reticulum.</p>
+<a class="reference external image-reference" href="https://github.com/kc1awv/lxst_phone"><img alt="_images/lxst_phone.webp" class="align-center" src="_images/lxst_phone.webp" />
+</a>
+<p>It supports various advanced features such as SAS verification, peer blocking, rate limiting, encrypted call history storage and contact management.</p>
+</section>
+<section id="lxmfy">
+<h3>LXMFy<a class="headerlink" href="#lxmfy" title="Link to this heading">¶</a></h3>
+<p><a class="reference external" href="https://lxmfy.quad4.io/">LXMFy</a> is a comprehensive and advanced bot creation framework for LXMF, that allows building any kind of automation or bot system running over LXMF and Reticulum. <a class="reference external" href="https://github.com/lxmfy/awesome-lxmfy-bots">Bot implementations exist</a> for Home Assistant control, LLM integrations, and various other purposes.</p>
+</section>
+<section id="lxmf-interactive-client">
+<h3>LXMF Interactive Client<a class="headerlink" href="#lxmf-interactive-client" title="Link to this heading">¶</a></h3>
+<p><a class="reference external" href="https://github.com/fr33n0w/lxmf-cli">LXMF Interactive Client</a> is a feature-rich, terminal-based LXMF messaging client with many advanced features and an extensible plugin architecture.</p>
+</section>
+<section id="rns-filesync">
+<h3>RNS FileSync<a class="headerlink" href="#rns-filesync" title="Link to this heading">¶</a></h3>
+<p>The <a class="reference external" href="https://git.quad4.io/RNS-Things/RNS-Filesync">RNS FileSync</a> program enables automatic file synchronization between devices without requiring central servers, internet connectivity, or cloud services. It works over any network medium supported by Reticulum, including radio, LoRa, WiFi, or the internet, making it ideal for off-grid, privacy-focused, and resilient file sharing.</p>
+</section>
+<section id="micron-parser-js">
+<h3>Micron Parser JS<a class="headerlink" href="#micron-parser-js" title="Link to this heading">¶</a></h3>
+<p><a class="reference external" href="https://github.com/RFnexus/micron-parser-js">Micron Parser JS</a> is the JavaScript-based parser for the Micron markup language, that most web-based Nomad Network browsers use. If you want to make utilities or tools that display Micron pages, this library is essential.</p>
+</section>
+<section id="rnmon">
+<h3>RNMon<a class="headerlink" href="#rnmon" title="Link to this heading">¶</a></h3>
+<p><a class="reference external" href="https://github.com/lbatalha/rnmon">RNMon</a> is a monitoring daemon designed to monitor the status of multiple RNS applications and push the metrics to an InfluxDB instance over the influx line protocol.</p>
+</section>
+</section>
+<section id="protocols">
+<h2>Protocols<a class="headerlink" href="#protocols" title="Link to this heading">¶</a></h2>
+<p>A number of standard protocols have emerged through real-world usage and testing in the Reticulum community. While you may sometimes want to use completely custom protocols and implementations when writing Reticulum-based software, using these protocols provides application developers with an easy way to implement advanced functionality quickly and effortlessly. Using them also ensures compatibility and interoperability between many different client applications, creating an open communications ecosystem where users are free to choose the applications that suit their needs, while remaining connected to everyone else.</p>
+<section id="lxmf">
+<h3>LXMF<a class="headerlink" href="#lxmf" title="Link to this heading">¶</a></h3>
+<p><a class="reference external" href="https://github.com/markqvist/lxmf">LXMF</a> is a simple and flexible messaging format and delivery protocol that allows a wide variety of applications, while using as little bandwidth as possible. It offers zero-conf message routing, end-to-end encryption and Forward Secrecy, and can be transported over any kind of medium that Reticulum supports.</p>
+<p>LXMF is efficient enough that it can deliver messages over extremely low-bandwidth systems such as packet radio or LoRa. Encrypted LXMF messages can also be encoded as QR-codes or text-based URIs, allowing completely analog paper message transport.</p>
+<p>Using Propagation Nodes, LXMF also offer a way to store and forward messages to users or endpoints that are not directly reachable at the time of message emission.</p>
+</section>
+<section id="id17">
+<h3>LXST<a class="headerlink" href="#id17" title="Link to this heading">¶</a></h3>
+<p><a class="reference external" href="https://github.com/markqvist/lxst">LXST</a> is a simple and flexible real-time streaming format and delivery protocol that allows a wide variety of applications, while using as little bandwidth as possible. It is built on top of Reticulum and offers zero-conf stream routing, end-to-end encryption and Forward Secrecy, and can be transported over any kind of medium that Reticulum supports. It currently powers real-time voice and telephony applications over Reticulum.</p>
+</section>
+<section id="rrc">
+<h3>RRC<a class="headerlink" href="#rrc" title="Link to this heading">¶</a></h3>
+<p>The <a class="reference external" href="https://rrc.kc1awv.net/">Reticulum Relay Chat</a> protocol, is a live chat system built on top of the Reticulum Network Stack. It exists to provide near real-time group communication without dragging in message history databases, federation machinery, or architectural guilt.</p>
+<p>RRC is intentionally simple. It does not pretend to be email, a mailbox, or a distributed archive. It behaves more like a conversation in a room. If you were there, you heard it. If you were not, you did not. That is not a bug, that is the point.</p>
+</section>
+</section>
+<section id="interface-modules-connectivity-resources">
+<h2>Interface Modules &amp; Connectivity Resources<a class="headerlink" href="#interface-modules-connectivity-resources" title="Link to this heading">¶</a></h2>
+<p>This section provides a list of various community-provided interface modules, guides and resources for creating Reticulum networks over special or challenging mediums.</p>
+<ul class="simple">
+<li><p>Custom interface module for running <a class="reference external" href="https://git.quad4.io/RNS-Things/RNS-over-HTTP">RNS over HTTP</a></p></li>
+<li><p>Guide for running <a class="reference external" href="https://github.com/matvik22000/rns-over-icmp">Reticulum over ICMP</a> using <code class="docutils literal notranslate"><span class="pre">PipeInterface</span></code></p></li>
+<li><p>Guide for running <a class="reference external" href="https://github.com/markqvist/Reticulum/discussions/1002">Reticulum over DNS</a> with Iodine</p></li>
+<li><p>Guide for running <a class="reference external" href="https://github.com/RFnexus/reticulum-over-hf">Reticulum over HF radio</a></p></li>
+<li><p><a class="reference external" href="https://github.com/RFnexus/modem73">Modem73</a> is a KISS TNC OFDM modem frontend that can be used with Reticulum</p></li>
+</ul>
+</section>
+</section>
+
+        </article>
+      </div>
+      <footer>
+        
+        <div class="related-pages">
+          <a class="next-page" href="using.html">
+              <div class="page-info">
+                <div class="context">
+                  <span>Next</span>
+                </div>
+                <div class="title">Using Reticulum on Your System</div>
+              </div>
+              <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
+            </a>
+          <a class="prev-page" href="zen.html">
+              <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
+              <div class="page-info">
+                <div class="context">
+                  <span>Previous</span>
+                </div>
+                
+                <div class="title">Zen of Reticulum</div>
+                
+              </div>
+            </a>
+        </div>
+        <div class="bottom-of-page">
+          <div class="left-details">
+            <div class="copyright">
+                Copyright &#169; 2025, Mark Qvist
+            </div>
+            Generated with <a href="https://www.sphinx-doc.org/">Sphinx</a> and 
+            <a href="https://github.com/pradyunsg/furo">Furo</a>
+            
+          </div>
+          <div class="right-details">
+            
+          </div>
+        </div>
+        
+      </footer>
+    </div>
+    <aside class="toc-drawer">
+      
+      
+      <div class="toc-sticky toc-scroll">
+        <div class="toc-title-container">
+          <span class="toc-title">
+            On this page
+          </span>
+        </div>
+        <div class="toc-tree-container">
+          <div class="toc-tree">
+            <ul>
+<li><a class="reference internal" href="#">Programs Using Reticulum</a><ul>
+<li><a class="reference internal" href="#programs-utilities">Programs &amp; Utilities</a><ul>
+<li><a class="reference internal" href="#remote-shell">Remote Shell</a></li>
+<li><a class="reference internal" href="#nomad-network">Nomad Network</a></li>
+<li><a class="reference internal" href="#rns-page-node">RNS Page Node</a></li>
+<li><a class="reference internal" href="#retipedia">Retipedia</a></li>
+<li><a class="reference internal" href="#sideband">Sideband</a></li>
+<li><a class="reference internal" href="#meshchatx">MeshChatX</a></li>
+<li><a class="reference internal" href="#meshchat">MeshChat</a></li>
+<li><a class="reference internal" href="#columba">Columba</a></li>
+<li><a class="reference internal" href="#reticulum-relay-chat">Reticulum Relay Chat</a></li>
+<li><a class="reference internal" href="#retibbs">RetiBBS</a></li>
+<li><a class="reference internal" href="#rbrowser">RBrowser</a></li>
+<li><a class="reference internal" href="#reticulum-network-telephone">Reticulum Network Telephone</a></li>
+<li><a class="reference internal" href="#lxst-phone">LXST Phone</a></li>
+<li><a class="reference internal" href="#lxmfy">LXMFy</a></li>
+<li><a class="reference internal" href="#lxmf-interactive-client">LXMF Interactive Client</a></li>
+<li><a class="reference internal" href="#rns-filesync">RNS FileSync</a></li>
+<li><a class="reference internal" href="#micron-parser-js">Micron Parser JS</a></li>
+<li><a class="reference internal" href="#rnmon">RNMon</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#protocols">Protocols</a><ul>
+<li><a class="reference internal" href="#lxmf">LXMF</a></li>
+<li><a class="reference internal" href="#id17">LXST</a></li>
+<li><a class="reference internal" href="#rrc">RRC</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#interface-modules-connectivity-resources">Interface Modules &amp; Connectivity Resources</a></li>
+</ul>
+</li>
+</ul>
+
+          </div>
+        </div>
+      </div>
+      
+      
+    </aside>
+  </div>
+</div><script src="_static/documentation_options.js?v=590429e0"></script>
+    <script src="_static/doctools.js?v=9bcbadda"></script>
+    <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
+    <script src="_static/scripts/furo.js?v=46bd48cc"></script>
+    <script src="_static/clipboard.min.js?v=a7894cd8"></script>
+    <script src="_static/copybutton.js?v=f281be69"></script>
+    </body>
+</html>

docs/manual/support.html

@@ -3,11 +3,11 @@
   <head><meta charset="utf-8">
     <meta name="viewport" content="width=device-width,initial-scale=1">
     <meta name="color-scheme" content="light dark"><meta name="viewport" content="width=device-width, initial-scale=1" />
-<link rel="index" title="Index" href="genindex.html"><link rel="search" title="Search" href="search.html"><link rel="next" title="Code Examples" href="examples.html"><link rel="prev" title="Building Networks" href="networks.html">
+<link rel="index" title="Index" href="genindex.html"><link rel="search" title="Search" href="search.html"><link rel="next" title="Code Examples" href="examples.html"><link rel="prev" title="Git Over Reticulum" href="git.html">
         <link rel="prefetch" href="_static/rns_logo_512.png" as="image">
 
     <!-- Generated with Sphinx 8.2.3 and Furo 2025.09.25.dev1 -->
-        <title>Support Reticulum - Reticulum Network Stack 1.0.3 documentation</title>
+        <title>Support Reticulum - Reticulum Network Stack 1.2.3 documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d111a655" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=580074bf" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
@@ -180,7 +180,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 1.0.3 documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 1.2.3 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -204,7 +204,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 1.0.3 documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 1.2.3 documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@@ -215,13 +215,17 @@
   <ul class="current">
 <li class="toctree-l1"><a class="reference internal" href="whatis.html">What is Reticulum?</a></li>
 <li class="toctree-l1"><a class="reference internal" href="gettingstartedfast.html">Getting Started Fast</a></li>
+<li class="toctree-l1"><a class="reference internal" href="zen.html">Zen of Reticulum</a></li>
+<li class="toctree-l1"><a class="reference internal" href="software.html">Programs Using Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
 <li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
 <li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks</a></li>
+<li class="toctree-l1"><a class="reference internal" href="git.html">Git Over Reticulum</a></li>
 <li class="toctree-l1 current current-page"><a class="current reference internal" href="#">Support Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a></li>
+<li class="toctree-l1"><a class="reference internal" href="license.html">Reticulum License</a></li>
 </ul>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="reference.html">API Reference</a></li>
@@ -267,11 +271,11 @@ systems by donating, providing feedback and contributing code and learning resou
 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Monero:
 84FpY1QbxHcgdseePYNmhTHcrgMX4nFfBYtz2GKYToqHVVhJp8Eaw1Z1EedRnKD19b3B8NiLCGVxzKV17UMmmeEsCrPyA5w
 
-Ethereum:
-0x81F7B979fEa6134bA9FD5c701b3501A2e61E897a
-
 Bitcoin:
-3CPmacGm34qYvR6XWLVEJmi2aNe3PZqUuq
+bc1pgqgu8h8xvj4jtafslq396v7ju7hkgymyrzyqft4llfslz5vp99psqfk3a6
+
+Ethereum:
+0x91C421DdfB8a30a49A71d63447ddb54cEBe3465E
 
 Liberapay:
 https://liberapay.com/Reticulum/
@@ -285,18 +289,29 @@ organisation? Make them a reality quickly by sponsoring their implementation.</p
 </section>
 <section id="provide-feedback">
 <h2>Provide Feedback<a class="headerlink" href="#provide-feedback" title="Link to this heading">¶</a></h2>
-<p>All feedback on the usage, functioning and potential dysfunctioning of any and
+<p>Feedback on the usage, functioning and potential dysfunctioning of any and
 all components of the system is very valuable to the continued development and
-improvement of Reticulum.</p>
+improvement of Reticulum. But…</p>
+<div class="admonition warning">
+<p class="admonition-title">Warning</p>
+<p><strong>Think before you speak</strong>. As time has shown, over 80% of the “feedback”,
+“bug reports” and “advice” the Reticulum project has received has been
+irrelevant noise, stemming from erroneous assumptions, misunderstanding the
+foundational functionality or philosophy behind the system, or simply
+the malinformed (but overly opinionated) personal preferences of individual
+drive-by architects. This wastes the time of everyone involved.</p>
+<p>The Reticulum project is not a public teahouse for serving the attention
+needs of random bypassers, but a highly complex system engineered and
+refined over more than a decade, designed to provide communication and
+connectivity guarantees in highly adversarial environments.</p>
+<p>If you want to voice your opinion, it better be well-informed, and we
+expect you to have a comprehensive and solid foundation for your points
+of view. Everything else will be ignored.</p>
+</div>
 <p>Absolutely no automated analytics, telemetry, error
 reporting or statistics is collected and reported by Reticulum under any
 circumstances, so we rely on old-fashioned human feedback.</p>
 </section>
-<section id="contribute-code">
-<h2>Contribute Code<a class="headerlink" href="#contribute-code" title="Link to this heading">¶</a></h2>
-<p>Join us on <a class="reference external" href="https://github.com/markqvist/reticulum">the GitHub repository</a> to
-report issues, suggest functionality and contribute code to Reticulum.</p>
-</section>
 </section>
 
         </article>
@@ -313,14 +328,14 @@ report issues, suggest functionality and contribute code to Reticulum.</p>
               </div>
               <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
             </a>
-          <a class="prev-page" href="networks.html">
+          <a class="prev-page" href="git.html">
               <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
               <div class="page-info">
                 <div class="context">
                   <span>Previous</span>
                 </div>
                 
-                <div class="title">Building Networks</div>
+                <div class="title">Git Over Reticulum</div>
                 
               </div>
             </a>
@@ -356,7 +371,6 @@ report issues, suggest functionality and contribute code to Reticulum.</p>
 <li><a class="reference internal" href="#">Support Reticulum</a><ul>
 <li><a class="reference internal" href="#donations">Donations</a></li>
 <li><a class="reference internal" href="#provide-feedback">Provide Feedback</a></li>
-<li><a class="reference internal" href="#contribute-code">Contribute Code</a></li>
 </ul>
 </li>
 </ul>
@@ -368,7 +382,7 @@ report issues, suggest functionality and contribute code to Reticulum.</p>
       
     </aside>
   </div>
-</div><script src="_static/documentation_options.js?v=baaebd52"></script>
+</div><script src="_static/documentation_options.js?v=590429e0"></script>
     <script src="_static/doctools.js?v=9bcbadda"></script>
     <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="_static/scripts/furo.js?v=46bd48cc"></script>

docs/manual/understanding.html

@@ -7,7 +7,7 @@
         <link rel="prefetch" href="_static/rns_logo_512.png" as="image">
 
     <!-- Generated with Sphinx 8.2.3 and Furo 2025.09.25.dev1 -->
-        <title>Understanding Reticulum - Reticulum Network Stack 1.0.3 documentation</title>
+        <title>Understanding Reticulum - Reticulum Network Stack 1.2.3 documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d111a655" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=580074bf" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
@@ -180,7 +180,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 1.0.3 documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 1.2.3 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -204,7 +204,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 1.0.3 documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 1.2.3 documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@@ -215,13 +215,17 @@
   <ul class="current">
 <li class="toctree-l1"><a class="reference internal" href="whatis.html">What is Reticulum?</a></li>
 <li class="toctree-l1"><a class="reference internal" href="gettingstartedfast.html">Getting Started Fast</a></li>
+<li class="toctree-l1"><a class="reference internal" href="zen.html">Zen of Reticulum</a></li>
+<li class="toctree-l1"><a class="reference internal" href="software.html">Programs Using Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
 <li class="toctree-l1 current current-page"><a class="current reference internal" href="#">Understanding Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
 <li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
 <li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks</a></li>
+<li class="toctree-l1"><a class="reference internal" href="git.html">Git Over Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a></li>
+<li class="toctree-l1"><a class="reference internal" href="license.html">Reticulum License</a></li>
 </ul>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="reference.html">API Reference</a></li>
@@ -267,9 +271,8 @@ the only complete repository, and final authority on how Reticulum actually func
 reference implementation and API reference. That being said, this chapter is an essential resource in
 understanding how Reticulum works from a high-level perspective, along with the general principles of
 Reticulum, and how to apply them when creating your own networks or software.</p>
-<p>After reading this document, you should be well-equipped to understand how a Reticulum network
-operates, what it can achieve, and how you can use it yourself. If you want to help out with the
-development, this is also the place to start, since it will provide a pretty clear overview of the
+<p>After reading this chapter, you should be well-equipped to understand how a Reticulum network
+operates, what it can achieve, and how you can use it yourself. This chapter also seeks to provide an overview of the
 sentiments and the philosophy behind Reticulum, what problems it seeks to solve, and how it
 approaches those solutions.</p>
 <section id="motivation">
@@ -381,7 +384,7 @@ to be transported over multiple hops in a complex network to reach the recipient
 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
 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 <em>represented</em> as a 16 byte hash. This hash is derived from truncating a full
 SHA-256 hash of identifying characteristics of the destination. To users, the destination addresses
 will be displayed as 16 hexadecimal bytes, like this example: <code class="docutils literal notranslate"><span class="pre">&lt;13425ec15b621c1d928589718000d814&gt;</span></code>.</p>
 <p>The truncation size of 16 bytes (128 bits) for destinations has been chosen as a reasonable trade-off
@@ -402,7 +405,7 @@ packet communication can also provide forward secrecy, with automatic key ratche
 ratchets on a per-destination basis. The multi-hop transport, coordination, verification and reliability
 layers are fully autonomous and also based on elliptic curve cryptography.</p>
 <p>Reticulum also offers symmetric key encryption for group-oriented communications, as well as
-unencrypted packets for local broadcast purposes.</p>
+unencrypted packets (for local broadcast purposes <strong>only</strong>).</p>
 <p>Reticulum can connect to a variety of interfaces such as radio modems, data radios and serial ports,
 and offers the possibility to easily tunnel Reticulum traffic over IP links such as the Internet or
 private IP networks.</p>
@@ -650,17 +653,26 @@ application specific data, it will replace the old announce.</div>
 </div>
 </li>
 </ul>
-<p>Once an announce has reached a node in the network, any other node in direct contact with that
-node will be able to reach the destination the announce originated from, simply by sending a packet
-addressed to that destination. Any node with knowledge of the announce will be able to direct the
-packet towards the destination by looking up the next node with the shortest amount of hops to the
-destination.</p>
+<p>Once an announce has reached a transport node in the network, any other node in direct contact with that
+transport node will be able to reach the destination the announce originated from, simply by sending a packet
+addressed to that destination. Any transport node with knowledge of the announce will be able to direct the
+packet towards the destination by looking up the most efficient next node to the destination.</p>
 <p>According to these rules, an announce will propagate throughout the network in a predictable way,
 and make the announced destination reachable in a short amount of time. Fast networks that have the
 capacity to process many announces can reach full convergence very quickly, even when constantly adding
 new destinations. Slower segments of such networks might take a bit longer to gain full knowledge about
 the wide and fast networks they are connected to, but can still do so over time, while prioritising full
 and quickly converging end-to-end connectivity for their local, slower segments.</p>
+<div class="admonition tip">
+<p class="admonition-title">Tip</p>
+<p>Even very slow networks, that simply don’t have the capacity to ever reach <em>full</em> convergence
+will generally still be able to reach <strong>any other destination on any connected segments</strong>, since
+interconnecting transport nodes will prioritize announces into the slower segments that are
+actually requested by nodes on these.</p>
+<p>This means that slow, low-capacity or low-resource segments <strong>don’t</strong> need to have full network
+knowledge, since paths can always be recursively resolved from other segments that do have
+knowledge about them.</p>
+</div>
 <p>In general, even extremely complex networks, that utilize the maximum 128 hops will converge to full
 end-to-end connectivity in about one minute, given there is enough bandwidth available to process
 the required amount of announces.</p>
@@ -668,7 +680,7 @@ the required amount of announces.</p>
 <section id="reaching-the-destination">
 <span id="understanding-paths"></span><h3>Reaching the Destination<a class="headerlink" href="#reaching-the-destination" title="Link to this heading">¶</a></h3>
 <p>In networks with changing topology and trustless connectivity, nodes need a way to establish
-<em>verified connectivity</em> with each other. Since the network is assumed to be trustless, Reticulum
+<em>verified connectivity</em> with each other. Since the underlying network mediums are assumed to be trustless, Reticulum
 must provide a way to guarantee that the peer you are communicating with is actually who you
 expect. Reticulum offers two ways to do this.</p>
 <p>For exchanges of small amounts of information, Reticulum offers the <em>Packet</em> API, which works exactly like you would expect - on a per packet level. The following process is employed when sending a packet:</p>
@@ -681,7 +693,7 @@ an ECDH key exchange with the destination’s public key (or ratchet key, if ava
 </li>
 <li><div class="line-block">
 <div class="line">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 <em>announce</em>, and can thus perform the ECDH
+knows the public key of the destination from an earlier received announce, and can thus perform the ECDH
 key exchange locally, before sending the packet.</div>
 </div>
 </li>
@@ -719,16 +731,16 @@ strictly necessary to use one of the others.</div>
 <p>For exchanges of larger amounts of data, or when longer sessions of bidirectional communication is desired, Reticulum offers the <em>Link</em> API. To establish a <em>link</em>, the following process is employed:</p>
 <ul>
 <li><div class="line-block">
-<div class="line">First, the node that wishes to establish a link will send out a special packet, that
+<div class="line">First, the node that wishes to establish a link will send out a <em>link request</em> packet, that
 traverses the network and locates the desired destination. Along the way, the Transport Nodes that
-forward the packet will take note of this <em>link request</em>.</div>
+forward the packet will take note of this <em>link request</em>, and mark it as pending.</div>
 </div>
 </li>
 <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
 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
-accept the validity of the <em>link</em> throughout the network.</div>
+accept the validity of the <em>link</em> throughout the network. The link is now marked as <em>established</em>.</div>
 </div>
 </li>
 <li><div class="line-block">
@@ -841,8 +853,11 @@ that is used to encrypt the channel. Information can now be exchanged reliably a
 </div>
 </li>
 </ul>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
 <p>It’s important to note that this methodology ensures that the source of the request does not need to
-reveal any identifying information about itself. The link initiator remains completely anonymous.</p>
+reveal any identifying information about itself. <strong>The link initiator remains completely anonymous</strong>.</p>
+</div>
 <p>When using <em>links</em>, Reticulum will automatically verify all data sent over the link, and can also
 automate retransmissions if <em>Resources</em> are used.</p>
 </section>
@@ -861,6 +876,66 @@ of codes to reliably transfer any amount of data. They can be used to transfer d
 or stream data directly from files.</p>
 </section>
 </section>
+<section id="network-identities">
+<span id="understanding-network-identities"></span><h2>Network Identities<a class="headerlink" href="#network-identities" title="Link to this heading">¶</a></h2>
+<p>In Reticulum, every peer and application utilizes a cryptographic <strong>Identity</strong> to verify authenticity and establish encrypted channels. While standard identities are typically used to represent a single user, device, or service, Reticulum introduces the concept of a <strong>Network Identity</strong> to represent a logical group of nodes or an entire community infrastructure.</p>
+<p>A Network Identity is, at its core, a standard Reticulum Identity keyset. However, its purpose and usage differ from a personal identity. Instead of identifying a single entity, a Network Identity acts as a shared credential that federates multiple independent Transport Instances under a single, verifiable administrative domain.</p>
+<section id="conceptual-overview">
+<h3>Conceptual Overview<a class="headerlink" href="#conceptual-overview" title="Link to this heading">¶</a></h3>
+<p>You can think of a standard Reticulum Identity as a self-sovereign, privately created passport for a single person. A Network Identity, conversely, is akin to a cryptographic flag, or a charter that flies over a fleet of ships. It signifies that while the ships may operate independently and be physically distant, they belong to the same organization, follow the same protocols, and are expected to act in concert.</p>
+<p>When you configure a Network Identity on one or more of your nodes, you are effectively declaring that these nodes constitute a specific “network” within a broader Reticulum mesh. This allows other peers to recognize interfaces not just as “a node named Alice”, but as “a gateway belonging to The Eastern Ret Of Freedom”.</p>
+</section>
+<section id="current-usage">
+<h3>Current Usage<a class="headerlink" href="#current-usage" title="Link to this heading">¶</a></h3>
+<p>At present, the primary function of a Network Identity is within the <a class="reference internal" href="using.html#using-interface-discovery"><span class="std std-ref">Interface Discovery</span></a> system.</p>
+<p>When a Transport Instance broadcasts a discovery announce for an interface, it can optionally sign that announce with a Network Identity, instead of just its local transport identity. Remote peers receiving the announce can then verify the signature. This provides functionality for two important distinctions:</p>
+<ol class="arabic simple">
+<li><p><strong>Authenticity:</strong> It proves that the interface was published by an operator who possesses the private key for that Network Identity.</p></li>
+<li><p><strong>Trust Boundaries:</strong> It allows users to configure their systems to only accept and connect to interfaces that belong to specific Network Identities, effectively creating “whitelisted” zones of trusted infrastructure.</p></li>
+</ol>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p>If you enable encryption on your discovery announces, the Network Identity is used as the shared secret. Only peers who have been explicitly provided with the Network Identity’s full keyset (and have it configured locally) will be able to decrypt and utilize the connection details.</p>
+<p>This functionality will be expanded in the future, so that peers with delegated keys can be allowed to decrypt discovery announces without holding the root network key. Currently, the functionality is sufficient for sharing interface information privately where you control all nodes that must decrypt the discovered interfaces.</p>
+</div>
+</section>
+<section id="future-implications">
+<h3>Future Implications<a class="headerlink" href="#future-implications" title="Link to this heading">¶</a></h3>
+<p>While the current implementation focuses on interface discovery, the concept of Network Identities serves as the foundational building block for future Reticulum features designed to support large-scale, organic mesh formation.</p>
+<p>As the ecosystem evolves, Network Identities will facilitate:</p>
+<ul class="simple">
+<li><p><strong>Distributed Name Resolution:</strong> A system where networks can publish name-to-identity mappings, allowing human-readable names to resolve without centralized servers.</p></li>
+<li><p><strong>Service Publishing:</strong> Networks will be able to announce specific capabilities, services, or information endpoints available publicly or to their members.</p></li>
+<li><p><strong>Inter-Network Federation:</strong> Trust relationships between different networks, allowing for seamless but managed flow of traffic and information across distinct administrative boundaries.</p></li>
+<li><p><strong>Distributed Blackhole Management:</strong> A reputation-based system for blackhole list distribution, where trusted Network Identities can sign and publish lists of blackholed identities. This allows communities to collaboratively enforce security standards and filter spam or malicious identities across the parts of the wider mesh that they are responsible for.</p></li>
+</ul>
+<p>By adopting the use of Network Identities now, you are preparing your infrastructure to be compatible with this future functionality.</p>
+</section>
+<section id="creating-and-using-a-network-identity">
+<h3>Creating and Using a Network Identity<a class="headerlink" href="#creating-and-using-a-network-identity" title="Link to this heading">¶</a></h3>
+<p>Since a Network Identity is simply a standard Reticulum Identity, you create one using the built-in tools.</p>
+<ol class="arabic">
+<li><p><strong>Generate the Identity:</strong>
+Use the <code class="docutils literal notranslate"><span class="pre">rnid</span></code> utility to generate a new identity file that will serve as your Network Identity.</p>
+<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>rnid<span class="w"> </span>-g<span class="w"> </span>~/.reticulum/storage/identities/my_network
+</pre></div>
+</div>
+</li>
+<li><p><strong>Distribute the Public Key:</strong>
+The public key must be distributed to any Transport Instance that needs to verify your network’s announces and discovery information. By default, if your node is set up to use a network identity, this happens automatically (using the standard announce mechanism).</p></li>
+<li><p><strong>Configure Instances:</strong>
+In the <code class="docutils literal notranslate"><span class="pre">[reticulum]</span></code> section of the configuration file on every node within your network, point the <code class="docutils literal notranslate"><span class="pre">network_identity</span></code> option to the file you created.</p>
+<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[reticulum]</span>
+<span class="na">...</span>
+<span class="na">network_identity</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">~/.reticulum/storage/identities/my_network</span>
+<span class="na">...</span>
+</pre></div>
+</div>
+</li>
+</ol>
+<p>Once configured, your instances will automatically utilize this identity for signing discovery announces (and potentially decrypting network-private information), presenting a unified front to the wider network.</p>
+</section>
+</section>
 <section id="reference-setup">
 <span id="understanding-referencesystem"></span><h2>Reference Setup<a class="headerlink" href="#reference-setup" title="Link to this heading">¶</a></h2>
 <p>This section will detail a recommended <em>Reference Setup</em> for Reticulum. It is important to
@@ -903,27 +978,30 @@ into the future. The current Reference System Setup is as follows:</p>
 <li><dl class="simple">
 <dt><strong>Interface Device</strong></dt><dd><p>A data radio consisting of a LoRa radio module, and a microcontroller with open source
 firmware, that can connect to host devices via USB. It operates in either the 430, 868 or 900
-MHz frequency bands. More details can be found on the <a class="reference external" href="https://unsigned.io/rnode">RNode Page</a>.</p>
+MHz frequency bands. More details can be found on the <a class="reference external" href="https://github.com/markqvist/rnode_firmware">RNode Page</a>.</p>
 </dd>
 </dl>
 </li>
 <li><dl class="simple">
 <dt><strong>Host Device</strong></dt><dd><p>Any computer device running Linux and Python. A Raspberry Pi with a Debian based OS is
-recommended.</p>
+a good place to start, but anything can be used.</p>
 </dd>
 </dl>
 </li>
 <li><dl class="simple">
-<dt><strong>Software Stack</strong></dt><dd><p>The most recently released Python Implementation of Reticulum, running on a Debian based
+<dt><strong>Software Stack</strong></dt><dd><p>The most recently released Python Implementation of Reticulum, running on a Linux-based
 operating system.</p>
 </dd>
 </dl>
 </li>
 </ul>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
 <p>To avoid confusion, it is very important to note, that the reference interface device <strong>does not</strong>
 use the LoRaWAN standard, but uses a custom MAC layer on top of the plain LoRa modulation! As such, you will
-need a plain LoRa radio module connected to an controller with the correct firmware. Full details on how to
-get or make such a device is available on the <a class="reference external" href="https://unsigned.io/rnode">RNode Page</a>.</p>
+need a plain LoRa radio module connected to a controller with the correct firmware. Full details on how to
+get or make such a device is available on the <a class="reference external" href="https://github.com/markqvist/rnode_firmware">RNode Page</a>.</p>
+</div>
 <p>With the current reference setup, it should be possible to get on a Reticulum network for around 100$
 even if you have none of the hardware already, and need to purchase everything.</p>
 <p>This reference setup is of course just a recommendation for getting started easily, and you should
@@ -932,20 +1010,20 @@ tailor it to your own specific needs, or whatever hardware you have available.</
 <section id="protocol-specifics">
 <span id="understanding-protocolspecifics"></span><h2>Protocol Specifics<a class="headerlink" href="#protocol-specifics" title="Link to this heading">¶</a></h2>
 <p>This chapter will detail protocol specific information that is essential to the implementation of
-Reticulum, but non critical in understanding how the protocol works on a general level. It should be
+Reticulum, but non-critical in understanding how the protocol works on a general level. It should be
 treated more as a reference than as essential reading.</p>
 <section id="packet-prioritisation">
 <h3>Packet Prioritisation<a class="headerlink" href="#packet-prioritisation" title="Link to this heading">¶</a></h3>
-<p>Currently, Reticulum is completely priority-agnostic regarding general traffic. All traffic is handled
-on a first-come, first-serve basis. Announce re-transmission are handled according to the re-transmission
-times and priorities described earlier in this chapter.</p>
+<p>Currently, Reticulum is completely priority-agnostic regarding <em>general</em> traffic. All traffic is handled
+on a first-come, first-serve basis. Announce re-transmission and other maintenance traffic is handled
+according to the re-transmission times and priorities described earlier in this chapter.</p>
 </section>
 <section id="interface-access-codes">
 <h3>Interface Access Codes<a class="headerlink" href="#interface-access-codes" title="Link to this heading">¶</a></h3>
 <p>Reticulum can create named virtual networks, and networks that are only accessible by knowing a preshared
 passphrase. The configuration of this is detailed in the <a class="reference internal" href="interfaces.html#interfaces-options"><span class="std std-ref">Common Interface Options</span></a>
-section. To implement these feature, Reticulum uses the concept of Interface Access Codes, that are calculated
-and verified per packet.</p>
+section. To implement this feature, Reticulum uses the concept of Interface Access Codes, that are calculated
+and verified per-packet.</p>
 <p>An interface with a named virtual network or passphrase authentication enabled will derive a shared Ed25519
 signing identity, and for every outbound packet generate a signature of the entire packet. This signature is
 then inserted into the packet as an Interface Access Code before transmission. Depending on the speed and
@@ -1141,6 +1219,10 @@ instead use the internal pure-python primitives. A trivial consequence of this i
 with the OpenSSL backend being <em>much</em> faster. The most important consequence however, is the
 potential loss of security by using primitives that has not seen the same amount of scrutiny,
 testing and review as those from OpenSSL.</p>
+<p>Using the normal RNS installation procedures, it is not possible to install Reticulum on a
+system without the required OpenSSL primitives being available, and if they are not, they will
+be resolved and installed as a dependency. It is only possible to use the pure-python primitives
+by manually specifying this, for example by using the <code class="docutils literal notranslate"><span class="pre">rnspure</span></code> package.</p>
 <div class="admonition warning">
 <p class="admonition-title">Warning</p>
 <p>If you want to use the internal pure-python primitives, it is <strong>highly advisable</strong> that you
@@ -1228,6 +1310,13 @@ those risks are acceptable to you.</p>
 <li><a class="reference internal" href="#resources">Resources</a></li>
 </ul>
 </li>
+<li><a class="reference internal" href="#network-identities">Network Identities</a><ul>
+<li><a class="reference internal" href="#conceptual-overview">Conceptual Overview</a></li>
+<li><a class="reference internal" href="#current-usage">Current Usage</a></li>
+<li><a class="reference internal" href="#future-implications">Future Implications</a></li>
+<li><a class="reference internal" href="#creating-and-using-a-network-identity">Creating and Using a Network Identity</a></li>
+</ul>
+</li>
 <li><a class="reference internal" href="#reference-setup">Reference Setup</a></li>
 <li><a class="reference internal" href="#protocol-specifics">Protocol Specifics</a><ul>
 <li><a class="reference internal" href="#packet-prioritisation">Packet Prioritisation</a></li>
@@ -1248,7 +1337,7 @@ those risks are acceptable to you.</p>
       
     </aside>
   </div>
-</div><script src="_static/documentation_options.js?v=baaebd52"></script>
+</div><script src="_static/documentation_options.js?v=590429e0"></script>
     <script src="_static/doctools.js?v=9bcbadda"></script>
     <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="_static/scripts/furo.js?v=46bd48cc"></script>

docs/manual/using.html

@@ -3,11 +3,11 @@
   <head><meta charset="utf-8">
     <meta name="viewport" content="width=device-width,initial-scale=1">
     <meta name="color-scheme" content="light dark"><meta name="viewport" content="width=device-width, initial-scale=1" />
-<link rel="index" title="Index" href="genindex.html"><link rel="search" title="Search" href="search.html"><link rel="next" title="Understanding Reticulum" href="understanding.html"><link rel="prev" title="Getting Started Fast" href="gettingstartedfast.html">
+<link rel="index" title="Index" href="genindex.html"><link rel="search" title="Search" href="search.html"><link rel="next" title="Understanding Reticulum" href="understanding.html"><link rel="prev" title="Programs Using Reticulum" href="software.html">
         <link rel="prefetch" href="_static/rns_logo_512.png" as="image">
 
     <!-- Generated with Sphinx 8.2.3 and Furo 2025.09.25.dev1 -->
-        <title>Using Reticulum on Your System - Reticulum Network Stack 1.0.3 documentation</title>
+        <title>Using Reticulum on Your System - Reticulum Network Stack 1.2.3 documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d111a655" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=580074bf" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
@@ -180,7 +180,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 1.0.3 documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 1.2.3 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -204,7 +204,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 1.0.3 documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 1.2.3 documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@@ -215,13 +215,17 @@
   <ul class="current">
 <li class="toctree-l1"><a class="reference internal" href="whatis.html">What is Reticulum?</a></li>
 <li class="toctree-l1"><a class="reference internal" href="gettingstartedfast.html">Getting Started Fast</a></li>
+<li class="toctree-l1"><a class="reference internal" href="zen.html">Zen of Reticulum</a></li>
+<li class="toctree-l1"><a class="reference internal" href="software.html">Programs Using Reticulum</a></li>
 <li class="toctree-l1 current current-page"><a class="current reference internal" href="#">Using Reticulum on Your System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
 <li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
 <li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks</a></li>
+<li class="toctree-l1"><a class="reference internal" href="git.html">Git Over Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a></li>
+<li class="toctree-l1"><a class="reference internal" href="license.html">Reticulum License</a></li>
 </ul>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="reference.html">API Reference</a></li>
@@ -554,8 +558,8 @@ Reticulum Transport Instance &lt;5245a8efe1788c6a1cd36144a270e13b&gt; running
 </div>
 <p><strong>All Command-Line Options</strong></p>
 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnstatus [-h] [--config CONFIG] [--version] [-a] [-A]
-                [-l] [-s SORT] [-r] [-j] [-R hash] [-i path]
-                [-w seconds] [-v] [filter]
+                [-l] [-t] [-s SORT] [-r] [-j] [-R hash] [-i path]
+                [-w seconds] [-d] [-D] [-m] [-I seconds] [-v] [filter]
 
 Reticulum Network Stack Status
 
@@ -569,12 +573,19 @@ options:
   -a, --all             show all interfaces
   -A, --announce-stats  show announce stats
   -l, --link-stats      show link stats
-  -s SORT, --sort SORT  sort interfaces by [rate, traffic, rx, tx, announces, arx, atx, held]
+  -t, --totals          display traffic totals
+  -s, --sort SORT       sort interfaces by [rate, traffic, rx, tx, rxs, txs,
+                                            announces, arx, atx, held]
   -r, --reverse         reverse sorting
   -j, --json            output in JSON format
-  -R hash               transport identity hash of remote instance to get status from (requires -i)
+  -R hash               transport identity hash of remote instance to get status from
   -i path               path to identity used for remote management
   -w seconds            timeout before giving up on remote queries
+  -d, --discovered      list discovered interfaces
+  -D                    show details and config entries for discovered interfaces
+  -m, --monitor         continuously monitor status
+  -I, --monitor-interval seconds
+                        refresh interval for monitor mode (default: 1)
   -v, --verbose
 </pre></div>
 </div>
@@ -667,7 +678,7 @@ options:
 </div>
 </section>
 <section id="the-rnpath-utility">
-<h3>The rnpath Utility<a class="headerlink" href="#the-rnpath-utility" title="Link to this heading">¶</a></h3>
+<span id="utility-rnpath"></span><h3>The rnpath Utility<a class="headerlink" href="#the-rnpath-utility" title="Link to this heading">¶</a></h3>
 <p>With the <code class="docutils literal notranslate"><span class="pre">rnpath</span></code> utility, you can look up and view paths for
 destinations on the Reticulum network.</p>
 <p><strong>Usage Examples</strong></p>
@@ -678,21 +689,23 @@ Path found, destination &lt;c89b4da064bf66d280f0e4d8abfd9806&gt; is 4 hops away
 </pre></div>
 </div>
 <p><strong>All Command-Line Options</strong></p>
-<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnpath [-h] [--config CONFIG] [--version] [-t] [-m hops]
-              [-r] [-d] [-D] [-x] [-w seconds] [-R hash] [-i path]
-              [-W seconds] [-j] [-v] [destination]
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnpath [-h] [--config CONFIG] [--version] [-t] [-m hops] [-r] [-d] [-D]
+              [-x] [-w seconds] [-R hash] [-i path] [-W seconds] [-b] [-B] [-U]
+              [--duration DURATION] [--reason REASON] [-p] [-j] [-v]
+              [destination] [list_filter]
 
-Reticulum Path Discovery Utility
+Reticulum Path Management Utility
 
 positional arguments:
   destination           hexadecimal hash of the destination
+  list_filter           filter for remote blackhole list view
 
 options:
   -h, --help            show this help message and exit
   --config CONFIG       path to alternative Reticulum config directory
   --version             show program&#39;s version number and exit
   -t, --table           show all known paths
-  -m hops, --max hops   maximum hops to filter path table by
+  -m, --max hops        maximum hops to filter path table by
   -r, --rates           show announce rate info
   -d, --drop            remove the path to a destination
   -D, --drop-announces  drop all queued announces
@@ -701,6 +714,13 @@ options:
   -R hash               transport identity hash of remote instance to manage
   -i path               path to identity used for remote management
   -W seconds            timeout before giving up on remote queries
+  -b, --blackholed      list blackholed identities
+  -B, --blackhole       blackhole identity
+  -U, --unblackhole     unblackhole identity
+  --duration DURATION   duration of blackhole enforcement in hours
+  --reason REASON       reason for blackholing identity
+  -p, --blackholed-list
+                        view published blackhole list for remote transport instance
   -j, --json            output in JSON format
   -v, --verbose
 </pre></div>
@@ -791,10 +811,15 @@ and simply running the program in listener mode:</p>
 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rncp --fetch ~/path/to/file.tgz 73cbd378bb0286ed11a707c13447bb1e
 </pre></div>
 </div>
+<p>The default identity file is stored in <code class="docutils literal notranslate"><span class="pre">~/.reticulum/identities/rncp</span></code>, but you can use
+another one, which will be created if it does not already exist</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rncp ~/path/to/file.tgz 73cbd378bb0286ed11a707c13447bb1e -i /path/to/identity
+</pre></div>
+</div>
 <p><strong>All Command-Line Options</strong></p>
 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rncp [-h] [--config path] [-v] [-q] [-S] [-l] [-F] [-f]
             [-j path] [-b seconds] [-a allowed_hash] [-n] [-p]
-            [-w seconds] [--version] [file] [destination]
+            [-i identity] [-w seconds] [--version] [file] [destination]
 
 Reticulum File Transfer Utility
 
@@ -819,12 +844,24 @@ options:
   -a allowed_hash       allow this identity (or add in ~/.rncp/allowed_identities)
   -n, --no-auth         accept requests from anyone
   -p, --print-identity  print identity and destination info and exit
+  -i identity           path to identity to use
   -w seconds            sender timeout before giving up
   -P, --phy-rates       display physical layer transfer rates
   --version             show program&#39;s version number and exit
 </pre></div>
 </div>
 </section>
+<section id="the-rngit-utility">
+<h3>The rngit Utility<a class="headerlink" href="#the-rngit-utility" title="Link to this heading">¶</a></h3>
+<p>The <code class="docutils literal notranslate"><span class="pre">rngit</span></code> utility provides full Git repository hosting and interaction over Reticulum, as well as many other useful features for software development, collaboration and publishing. It allows you to host Git repositories on Reticulum nodes, interact with remote repositories using standard Git commands through the <code class="docutils literal notranslate"><span class="pre">rns://</span></code> URL scheme, and to publish software releases.</p>
+<p>The system consists of two parts: The <code class="docutils literal notranslate"><span class="pre">rngit</span></code> node that hosts and manages repositories, and the <code class="docutils literal notranslate"><span class="pre">git-remote-rns</span></code> helper that enables Git to communicate with rngit nodes. As soon as you have RNS installed on your system, you can transparently use Git with Reticulum-hosted repositories just like any other type of remote. Git over Reticulum uses URLs in the following format: <code class="docutils literal notranslate"><span class="pre">rns://DESTINATION_HASH/group/repo</span></code>.</p>
+<p>If you set a branch to track a Reticulum remote as the default upstream, you can simply use <code class="docutils literal notranslate"><span class="pre">git</span></code> as you normally would; all commands work transparently and as expected.</p>
+<div class="admonition warning">
+<p class="admonition-title">Warning</p>
+<p><strong>The rngit program is a new addition to RNS!</strong> This functionality was introduced in RNS 1.2.0. While great care has been taken to design a secure, but highly configurable and flexible permission system for allowing many users to interact with many different repositories on a single node, <code class="docutils literal notranslate"><span class="pre">rngit</span></code> has not been tested extensively in the wild! Be careful when hosting repositories, especially if they are public or semi-public.</p>
+</div>
+<p>For the full documentation on the <cite>rngit</cite> system, see the <a class="reference internal" href="git.html#git-main"><span class="std std-ref">Git Over Reticulum</span></a> chapter of this manual.</p>
+</section>
 <section id="the-rnx-utility">
 <h3>The rnx Utility<a class="headerlink" href="#the-rnx-utility" title="Link to this heading">¶</a></h3>
 <p>The <code class="docutils literal notranslate"><span class="pre">rnx</span></code> utility is a basic remote command execution program. It allows you to
@@ -884,6 +921,232 @@ optional arguments:
 </pre></div>
 </div>
 </section>
+<section id="the-rnsh-utility">
+<h3>The rnsh Utility<a class="headerlink" href="#the-rnsh-utility" title="Link to this heading">¶</a></h3>
+<p>The <code class="docutils literal notranslate"><span class="pre">rnsh</span></code> utility provides a fully interactive remote shell over Reticulum.
+It allows you to establish encrypted, authenticated shell sessions on remote
+systems, complete with terminal emulation, pipe support, and window resizing.</p>
+<p>While the <code class="docutils literal notranslate"><span class="pre">rnx</span></code> utility is useful for simple remote command execution and
+retrieving output, <code class="docutils literal notranslate"><span class="pre">rnsh</span></code> provides a complete interactive terminal experience,
+making it ideal for remote administration and management tasks that require
+real-time interaction, just like SSH does for IP networks.</p>
+<p><code class="docutils literal notranslate"><span class="pre">rnsh</span></code> operates in two modes: a <em>listener</em> mode that accepts incoming
+connections, and an <em>initiator</em> mode that connects to a remote listener. Both
+sides authenticate using Reticulum Identities, ensuring that only authorised
+peers can establish sessions.</p>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p><code class="docutils literal notranslate"><span class="pre">rnsh</span></code> provides a genuine interactive terminal over Reticulum. It supports
+full terminal emulation including escape sequences, window resizing, signal
+forwarding, and piping of standard input, output and error streams. This
+makes it suitable for running text editors, terminal multiplexers, and any
+other interactive programs on remote systems.</p>
+</div>
+<p><strong>Usage Examples</strong></p>
+<p>Start <code class="docutils literal notranslate"><span class="pre">rnsh</span></code> in listener mode, accepting connections from specific identities:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnsh -l -a 941bed5e228775e5a8079fc38b1ccf3f -a 1b03013c25f1c2ca068a4f080b844a10
+</pre></div>
+</div>
+<p>You can also specify allowed identity hashes (one per line) in the file
+<code class="docutils literal notranslate"><span class="pre">~/.rnsh/allowed_identities</span></code> or <code class="docutils literal notranslate"><span class="pre">~/.config/rnsh/allowed_identities</span></code>, and
+simply run the program in listener mode:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnsh -l
+</pre></div>
+</div>
+<p>Connect to a remote listener from another system:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnsh 7a55144adf826958a9529a3bcf08b149
+</pre></div>
+</div>
+<p>Specify a command to run on the remote system, separating <code class="docutils literal notranslate"><span class="pre">rnsh</span></code> options from
+the remote command with <code class="docutils literal notranslate"><span class="pre">--</span></code>:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnsh 7a55144adf826958a9529a3bcf08b149 -- top
+</pre></div>
+</div>
+<p>Set a default command for the listener, in case the initiator does not supply
+one, or when remote command execution is disabled:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnsh -l -- /bin/bash --login
+</pre></div>
+</div>
+<p>Use the <code class="docutils literal notranslate"><span class="pre">-m</span></code> flag to mirror the exit code of the remote process:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnsh -m 7a55144adf826958a9529a3bcf08b149 -- /usr/local/bin/check-status
+</pre></div>
+</div>
+<p>Use the <code class="docutils literal notranslate"><span class="pre">-p</span></code> flag to display the identity and destination hash for a listener:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnsh -l -p
+
+Identity     : &lt;984b74a3f768bef236af4371e6f248cd&gt;
+Listening on : 7a55144adf826958a9529a3bcf08b149
+</pre></div>
+</div>
+<p>Use a specific identity file rather than the default:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnsh -l -i /path/to/identity
+</pre></div>
+</div>
+<p>Announce the listener destination on startup, and periodically:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnsh -l -b 900
+</pre></div>
+</div>
+<p>The <code class="docutils literal notranslate"><span class="pre">-b</span></code> option specifies the announce period in seconds. Use <code class="docutils literal notranslate"><span class="pre">0</span></code> to
+announce only once at startup.</p>
+<p><strong>Authentication &amp; Authorisation</strong></p>
+<p>By default, <code class="docutils literal notranslate"><span class="pre">rnsh</span></code> requires that connecting initiators identify themselves
+with a Reticulum Identity whose hash is present in the list of allowed
+identities. Allowed identities can be specified on the command line with the
+<code class="docutils literal notranslate"><span class="pre">-a</span></code> option, and can be used multiple times:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnsh -l -a 941bed5e228775e5a8079fc38b1ccf3f -a 1b03013c25f1c2ca068a4f080b844a10
+</pre></div>
+</div>
+<p>You can also maintain a list of allowed identity hashes in the file
+<code class="docutils literal notranslate"><span class="pre">~/.rnsh/allowed_identities</span></code> or <code class="docutils literal notranslate"><span class="pre">~/.config/rnsh/allowed_identities</span></code>,
+with one hex hash per line. This file is reloaded every time a new connection
+is received, so changes take effect immediately without restarting <code class="docutils literal notranslate"><span class="pre">rnsh</span></code>.</p>
+<p>If you want to accept connections from any identity (for testing or in fully
+trusted environments), you can disable authentication with the <code class="docutils literal notranslate"><span class="pre">-n</span></code> option:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnsh -l -n
+</pre></div>
+</div>
+<div class="admonition warning">
+<p class="admonition-title">Warning</p>
+<p>Disabling authentication with <code class="docutils literal notranslate"><span class="pre">-n</span></code> means that <strong>any</strong> Reticulum peer that
+can reach your listener will be able to execute commands on your system. Only
+use this option if you <em>really</em> know what you’re doing.</p>
+</div>
+<p><strong>Remote Command Control</strong></p>
+<p>When running in listener mode, <code class="docutils literal notranslate"><span class="pre">rnsh</span></code> allows you to control how remote
+commands are handled:</p>
+<ul class="simple">
+<li><p>By default, the listener accepts the command sent by the initiator. If the
+initiator does not supply a command, the listener’s default shell is used.</p></li>
+<li><p>Use <code class="docutils literal notranslate"><span class="pre">-C</span></code> (<code class="docutils literal notranslate"><span class="pre">--no-remote-command</span></code>) to disable execution of commands received
+from the initiator. Only the listener’s default command (or the command
+specified after <code class="docutils literal notranslate"><span class="pre">--</span></code>) will be executed:</p></li>
+</ul>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnsh -l -C -- /usr/local/bin/safe-script
+</pre></div>
+</div>
+<ul class="simple">
+<li><p>Use <code class="docutils literal notranslate"><span class="pre">-A</span></code> (<code class="docutils literal notranslate"><span class="pre">--remote-command-as-args</span></code>) to append the initiator’s command
+to the listener’s default command instead of replacing it. This can be useful
+for restricting the remote to a specific program while still allowing the
+initiator to pass arguments:</p></li>
+</ul>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnsh -l -A -- /usr/bin/top
+</pre></div>
+</div>
+<p><strong>Service Names</strong></p>
+<p>When running in listener mode, <code class="docutils literal notranslate"><span class="pre">rnsh</span></code> uses a service name to differentiate
+between multiple listener instances that may share the same identity. By
+default, the service name is <code class="docutils literal notranslate"><span class="pre">default</span></code>. You can specify a different service
+name with the <code class="docutils literal notranslate"><span class="pre">-s</span></code> option:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnsh -l -s monitoring
+</pre></div>
+</div>
+<p>This allows you to run multiple listeners on the same node, each with a
+different service name and purpose.</p>
+<p><strong>Initiator Options</strong></p>
+<p>When connecting to a remote listener, several options are available:</p>
+<ul class="simple">
+<li><p>Use <code class="docutils literal notranslate"><span class="pre">-N</span></code> (<code class="docutils literal notranslate"><span class="pre">--no-id</span></code>) to disable sending your identity to the remote
+listener. Note that the listener must have authentication disabled (<code class="docutils literal notranslate"><span class="pre">-n</span></code>)
+for the connection to succeed in this case.</p></li>
+<li><p>Use <code class="docutils literal notranslate"><span class="pre">-m</span></code> (<code class="docutils literal notranslate"><span class="pre">--mirror</span></code>) to make the initiator return with the exit code of
+the remote process, rather than always returning <code class="docutils literal notranslate"><span class="pre">0</span></code>.</p></li>
+<li><p>Use <code class="docutils literal notranslate"><span class="pre">-w</span></code> (<code class="docutils literal notranslate"><span class="pre">--timeout</span></code>) to specify the connection and request timeout in
+seconds. By default, the timeout matches the Reticulum path request timeout.</p></li>
+</ul>
+<p><strong>Identity &amp; Destination</strong></p>
+<p>The default identity file for <code class="docutils literal notranslate"><span class="pre">rnsh</span></code> is stored at
+<code class="docutils literal notranslate"><span class="pre">~/.reticulum/identities/rnsh</span></code>, but you can specify a different one with the
+<code class="docutils literal notranslate"><span class="pre">-i</span></code> option, which will be created if it does not already exist:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnsh -l -i /path/to/identity
+</pre></div>
+</div>
+<p>To display the identity and destination information for a listener, use the
+<code class="docutils literal notranslate"><span class="pre">-p</span></code> option. When combined with <code class="docutils literal notranslate"><span class="pre">-l</span></code>, both the identity and the listening
+destination hash are displayed:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnsh -p
+
+Identity     : &lt;984b74a3f768bef236af4371e6f248cd&gt;
+
+$ rnsh -l -p
+
+Identity     : &lt;984b74a3f768bef236af4371e6f248cd&gt;
+Listening on : 7a55144adf826958a9529a3bcf08b149
+</pre></div>
+</div>
+<p><strong>Verbosity</strong></p>
+<p>Like other Reticulum utilities, <code class="docutils literal notranslate"><span class="pre">rnsh</span></code> supports the <code class="docutils literal notranslate"><span class="pre">-v</span></code> and <code class="docutils literal notranslate"><span class="pre">-q</span></code> flags
+to increase or decrease logging verbosity. Multiple flags can be specified to
+further adjust the log level. The default log level is <code class="docutils literal notranslate"><span class="pre">INFO</span></code> for listeners
+and <code class="docutils literal notranslate"><span class="pre">ERROR</span></code> for initiators.</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnsh -l -vv       # Listener with debug-level output
+$ rnsh -q 7a55144adf826958a9529a3bcf08b149   # Quiet initiator
+</pre></div>
+</div>
+<p>By default, all log output is routed to <code class="docutils literal notranslate"><span class="pre">~/.rnsh/logfile</span></code> for initiators.</p>
+<p><strong>Escape Sequences</strong></p>
+<p>During an active <code class="docutils literal notranslate"><span class="pre">rnsh</span></code> session, the following escape sequences are
+available. These are only recognised immediately after a newline character:</p>
+<ul class="simple">
+<li><p><code class="docutils literal notranslate"><span class="pre">~~</span></code> - Send a literal tilde character</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">~.</span></code> - Terminate the session and exit immediately</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">~L</span></code> - Toggle line-interactive mode</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">~?</span></code> - Display the escape sequence quick reference</p></li>
+</ul>
+<p><strong>All Command-Line Options</strong></p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnsh [-h] [--config CONFIG] [--identity IDENTITY] [-v] [-q] [-p]
+            [--version] [-l] [-s SERVICE] [-b PERIOD] [-a HASH] [-n] [-A] [-C]
+            [-N] [-m] [-w SECONDS]
+            [destination]
+
+Reticulum Remote Shell Utility
+
+positional arguments:
+  destination           hexadecimal hash of the destination to connect to
+
+options:
+  -h, --help            show this help message and exit
+  --config, -c CONFIG   path to alternative Reticulum config directory
+  --identity, -i IDENTITY
+                        path to identity file to use
+  -v, --verbose         increase verbosity
+  -q, --quiet           decrease verbosity
+  -p, --print-identity  print identity and destination info and exit
+  --version             show program&#39;s version number and exit
+  -l, --listen          listen (server) mode; any command specified after --
+                        will be used as the default command when the initiator
+                        does not provide one or when remote command execution
+                        is disabled; if no command is specified, the default
+                        shell of the user running rnsh will be used
+  -s, --service SERVICE
+                        service name for identity file if not the default
+  -b, --announce PERIOD
+                        announce on startup and every PERIOD seconds; specify
+                        0 to announce on startup only
+  -a, --allowed HASH    allow this identity to connect (may be specified
+                        multiple times); allowed identities can also be
+                        specified in ~/.rnsh/allowed_identities or
+                        ~/.config/rnsh/allowed_identities, one hash per line
+  -n, --no-auth         disable authentication (allow any identity to connect)
+  -A, --remote-command-as-args
+                        concatenate remote command to the argument list of the
+                        default program or shell
+  -C, --no-remote-command
+                        disable executing command lines received from the
+                        remote initiator
+  -N, --no-id           disable identity announcement on connect
+  -m, --mirror          return with the exit code of the remote process
+  -w, --timeout SECONDS
+                        connect and request timeout in seconds
+
+When specifying a command to execute, separate rnsh options from the command
+and its arguments with --. For example:
+
+  rnsh -l -- /bin/bash --login
+  rnsh &lt;destination&gt; -- ls -la /tmp
+</pre></div>
+</div>
+</section>
 <section id="the-rnodeconf-utility">
 <h3>The rnodeconf Utility<a class="headerlink" href="#the-rnodeconf-utility" title="Link to this heading">¶</a></h3>
 <p>The <code class="docutils literal notranslate"><span class="pre">rnodeconf</span></code> utility allows you to inspect and configure existing <a class="reference internal" href="hardware.html#rnode-main"><span class="std std-ref">RNodes</span></a>, and
@@ -963,6 +1226,87 @@ options:
 section of this manual.</p>
 </section>
 </section>
+<section id="discovering-interfaces">
+<span id="using-interface-discovery"></span><h2>Discovering Interfaces<a class="headerlink" href="#discovering-interfaces" title="Link to this heading">¶</a></h2>
+<p>Reticulum includes built-in functionality for discovering connectable interfaces over Reticulum itself. This is particularly useful in situations where you want to do one or more of the following:</p>
+<ul class="simple">
+<li><p>Discover connectable entrypoints available on the Internet</p></li>
+<li><p>Find connectable radio access points in the physical world</p></li>
+<li><p>Maintain connectivity to RNS instances with unknown or changing IP addresses</p></li>
+</ul>
+<p>Discovered interfaces can be <strong>auto-connected</strong> by Reticulum, which makes it possible to create setups where an arbitrary interface can act simply as a bootstrap connection, that can be torn down again once more suitable interfaces have been discovered and connected.</p>
+<p>The interface discovery mechanism uses announces sent over Reticulum itself, and supports both publicly readable interfaces and private, encrypted discovery, that can only be decoded by specified <em>network identities</em>. It is also possible to specify which network identities should be considered valid sources for discovered interfaces, so that interfaces published by unknown entities are ignored.</p>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p>A <em>network identity</em> is a normal Reticulum identity keyset that can be used by
+one or more transport nodes to identify them as belonging to the same overall
+network. In the context of interface discovery, this makes it easy to manage
+connecting to only the particular networks you care about, even if those networks
+utilize many individual physical transport node.</p>
+<p>This also makes it convenient to auto-connect discovered interfaces only for networks you have some level of trust in.</p>
+</div>
+<p>For information on how to make your interfaces discoverable, see the <a class="reference internal" href="interfaces.html#interfaces-discoverable"><span class="std std-ref">Discoverable Interfaces</span></a> chapter of this manual. The current section will focus on how to actually <em>discover and connect to</em> interfaces available on the network.</p>
+<p>In its most basic form, enabling interface discovery is as simple as setting <code class="docutils literal notranslate"><span class="pre">discover_interfaces</span></code> to <code class="docutils literal notranslate"><span class="pre">true</span></code> in your Reticulum config:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>[reticulum]
+...
+discover_interfaces = yes
+...
+</pre></div>
+</div>
+<p>Once this option is enabled, your RNS instance will start listening for interface discovery announces, and store them for later use or inspection. You can list discovered interfaces with the <code class="docutils literal notranslate"><span class="pre">rnstatus</span></code> utility:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnstatus -d
+
+Name           Type      Status       Last Heard   Value  Location
+-------------------------------------------------------------------------
+Sideband Hub   Backbone  ✓ Available  1h  ago      16     46.2316, 6.0536
+RNS Amsterdam  Backbone  ✓ Available  32m ago      16     52.3865, 4.9037
+</pre></div>
+</div>
+<p>You can view more detailed information about discovered interfaces, including configuration snippets for pasting directly into your <code class="docutils literal notranslate"><span class="pre">[interfaces]</span></code> config, by using the <code class="docutils literal notranslate"><span class="pre">rnstatus</span> <span class="pre">-D</span></code> option:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnstatus -D sideband
+
+Transport ID : 521c87a83afb8f29e4455e77930b973b
+Name         : Sideband Hub
+Type         : BackboneInterface
+Status       : Available
+Transport    : Enabled
+Distance     : 2 hops
+Discovered   : 9h and 40m ago
+Last Heard   : 1h and 15m ago
+Location     : 46.2316, 6.0536
+Address      : sideband.connect.reticulum.network:7822
+Stamp Value  : 16
+
+Configuration Entry:
+  [[Sideband Hub]]
+    type = BackboneInterface
+    enabled = yes
+    remote = sideband.connect.reticulum.network
+    target_port = 7822
+    transport_identity = 521c87a83afb8f29e4455e77930b973b
+</pre></div>
+</div>
+<p>In addition to providing local interface discovery information and control, the <code class="docutils literal notranslate"><span class="pre">rnstatus</span></code> utility can export discovered interface data in machine-readable JSON format using the <code class="docutils literal notranslate"><span class="pre">rnstatus</span> <span class="pre">-d</span> <span class="pre">--json</span></code> option. This can be useful for exporting the data to external applications such as status pages, access point maps and similar.</p>
+<p>To control what sources are considered valid for discovered sources, additional
+configuration options can be specified for the interface discovery system.</p>
+<ul class="simple">
+<li><p>The <code class="docutils literal notranslate"><span class="pre">interface_discovery_sources</span></code> option is a list of the network or transport identities from which interfaces will be accepted. If this option is set, all others will be ignored. If this option is not set, discovered interfaces will be accepted from any source, but are still subject to stamp value requirements.</p></li>
+<li><p>The <code class="docutils literal notranslate"><span class="pre">required_discovery_value</span></code> options specifies the minimum stamp value required for the interface announce to be considered valid. To make it computationally difficult to spam the network with a large number of defunct or malicious interfaces, each announced interface requires a valid cryptographical stamp, of configurable difficulty value.</p></li>
+<li><p>The <code class="docutils literal notranslate"><span class="pre">autoconnect_discovered_interfaces</span></code> value defaults to <code class="docutils literal notranslate"><span class="pre">0</span></code>, and specifies the maximum number of discovered interfaces that should be auto-connected at any given time. If set to a number greater than <code class="docutils literal notranslate"><span class="pre">0</span></code>, Reticulum automatically manages discovered interface connections, and will bring discovered interfaces up and down based on availability. You can at any time add discovered interfaces to your configuration manually, to persistently keep them available.</p></li>
+<li><p>The <code class="docutils literal notranslate"><span class="pre">network_identity</span></code> option specifies the <em>network identity</em> for this RNS instance. This identity is used both to sign (and potentially encrypt) <em>outgoing</em> interface discovery announces, and to decrypt incoming discovery information.</p></li>
+</ul>
+<p>The configuration snippet below contains an example of setting these additional configuration options:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>[reticulum]
+...
+discover_interfaces = yes
+interface_discovery_sources = 521c87a83afb8f29e4455e77930b973b
+required_discovery_value = 16
+autoconnect_discovered_interfaces = 3
+network_identity = ~/.reticulum/storage/identities/my_network
+...
+</pre></div>
+</div>
+</section>
 <section id="remote-management">
 <h2>Remote Management<a class="headerlink" href="#remote-management" title="Link to this heading">¶</a></h2>
 <p>It is possible to allow remote management of Reticulum
@@ -984,6 +1328,97 @@ remote_management_allowed = 9fb6d773498fb3feda407ed8ef2c3229, 2d882c5586e548d79b
 </div>
 <p>For a complete example configuration, you can run <code class="docutils literal notranslate"><span class="pre">rnsd</span> <span class="pre">--exampleconfig</span></code>.</p>
 </section>
+<section id="blackhole-management">
+<span id="using-blackhole-management"></span><h2>Blackhole Management<a class="headerlink" href="#blackhole-management" title="Link to this heading">¶</a></h2>
+<p>Reticulum networks are fundamentally permissionless and open, allowing anyone with a compatible interface to participate. While this openness is essential for a resilient and decentralized network, it also exposes the network to potential abuse, such as peers flooding the network with excessive announce broadcasts or other forms of resource exhaustion.</p>
+<p>The <strong>Blackhole</strong> system provides tools to help manage this problem. It allows operators and individual users to block specific identities at the Transport layer, preventing them from propagating announces through your node, and for other nodes to reach them through your network.</p>
+<div class="admonition important">
+<p class="admonition-title">Important</p>
+<p>There is fundamentally <strong>no way</strong> to <em>globally</em> block or censor any identity or destination in Reticulum networks. The blackhole functionality will prevent announces from (and traffic to) all destinations associated with the blackholed identity <em>on your own network segments only</em>.</p>
+<p>This provides users and operators with control over what they want to allow <em>on their own network segments</em>, but there is no way to globally censor or remove an identity, as long as <em>someone</em> is willing to provide transport for it.</p>
+</div>
+<p>This functionality serves a dual purpose:</p>
+<ul class="simple">
+<li><p><strong>For Individual Users:</strong> It offers a simple way to maintain a quiet and efficient local network by manually blocking spammy or unwanted peers.</p></li>
+<li><p><strong>For Network Operators:</strong> It enables the creation of federated, community-wide security standards. By publishing and sharing blackhole lists, operators can protect large infrastructures and distribute spam filtering rules across the mesh without manual intervention.</p></li>
+</ul>
+<section id="local-blackhole-management">
+<h3>Local Blackhole Management<a class="headerlink" href="#local-blackhole-management" title="Link to this heading">¶</a></h3>
+<p>The most immediate way to manage unwanted identities is through manual configuration using the <code class="docutils literal notranslate"><span class="pre">rnpath</span></code> utility. This allows you to instantly block or unblock specific identities on your local Transport Instance.</p>
+<p><strong>Blackholing an Identity</strong></p>
+<p>To block an identity, use the <code class="docutils literal notranslate"><span class="pre">-B</span></code> (or <code class="docutils literal notranslate"><span class="pre">--blackhole</span></code>) flag followed by the identity hash. You can optionally specify a duration and a reason, which are useful for logging and future reference.</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnpath -B 3a4f8b9c1d2e3f4g5h6i7j8k9l0m1n2o
+</pre></div>
+</div>
+<p>You can also add a duration (in hours) and a reason:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnpath -B 3a4f8b9c1d2e3f4g5h6i7j8k9l0m1n2o --duration 24 --reason &quot;Excessive announces&quot;
+</pre></div>
+</div>
+<p><strong>Lifting Blackholes</strong></p>
+<p>To remove an identity from the blackhole, use the <code class="docutils literal notranslate"><span class="pre">-U</span></code> (or <code class="docutils literal notranslate"><span class="pre">--unblackhole</span></code>) flag:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnpath -U 3a4f8b9c1d2e3f4g5h6i7j8k9l0m1n2o
+</pre></div>
+</div>
+<p><strong>Viewing the Blackhole List</strong></p>
+<p>To see all identities currently blackholed on your local instance, use the <code class="docutils literal notranslate"><span class="pre">-b</span></code> (or <code class="docutils literal notranslate"><span class="pre">--blackholed</span></code>) flag:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnpath -b
+
+&lt;3a4f8b9c1d2e3f4g5h6i7j8k9l0m1n2o&gt; blackholed for 23h, 56m (Excessive announces)
+&lt;399ea050ce0eed1816c300bcb0840938&gt; blackholed indefinitely (Announce spam)
+&lt;d56a4fa02c0a77b3575935aedd90bdb2&gt; blackholed indefinitely (Announce spam)
+&lt;2b9ec651326d9bc274119054c70fb75e&gt; blackholed indefinitely (Announce spam)
+&lt;1178a8f1fad405bf2ad153bf5036bdfd&gt; blackholed indefinitely (Announce spam)
+</pre></div>
+</div>
+</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>
+<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>
+</div>
+<p>When enabled, your Transport Instance will periodically (approximately once per hour) connect to configured sources, retrieve their latest blackhole lists, and automatically merge them into your local blocklist. This provides “set-and-forget” protection for both individual users and large networks.</p>
+<p><strong>Configuration</strong></p>
+<p>To enable automated sourcing, add the <code class="docutils literal notranslate"><span class="pre">blackhole_sources</span></code> option to the <code class="docutils literal notranslate"><span class="pre">[reticulum]</span></code> section of your configuration file. This option accepts a comma-separated list of Transport Identity hashes that you trust to provide valid blackhole lists.</p>
+<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[reticulum]</span>
+<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="na">...</span>
+</pre></div>
+</div>
+<p><strong>How It Works</strong></p>
+<ol class="arabic simple">
+<li><p>When enabled, the <code class="docutils literal notranslate"><span class="pre">BlackholeUpdater</span></code> service runs in the background.</p></li>
+<li><p>For every identity hash listed in <code class="docutils literal notranslate"><span class="pre">blackhole_sources</span></code>, it attempts to establish a temporary link to its associated``rnstransport.info.blackhole`` destination.</p></li>
+<li><p>It requests the <code class="docutils literal notranslate"><span class="pre">/list</span></code> path, which returns a dictionary of blackholed identities and their associated metadata.</p></li>
+<li><p>The received list is merged with your local <code class="docutils literal notranslate"><span class="pre">blackholed_identities</span></code> database.</p></li>
+<li><p>The lists are persisted to disk, ensuring they survive restarts.</p></li>
+</ol>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p>You can verify the external lists you are subscribed to, and their contents, without importing them by using <code class="docutils literal notranslate"><span class="pre">rnpath</span> <span class="pre">-p</span></code>. See the <a class="reference internal" href="#utility-rnpath"><span class="std std-ref">rnpath utility documentation</span></a> for details on querying remote blackhole lists.</p>
+</div>
+</section>
+<section id="publishing-blackhole-lists">
+<h3>Publishing Blackhole Lists<a class="headerlink" href="#publishing-blackhole-lists" title="Link to this heading">¶</a></h3>
+<p>If you are operating a public gateway, a community hub, or simply wish to share your blackhole list with others, you can configure your instance to act as a blackhole list publisher. This allows other nodes to subscribe to <em>your</em> definitions of unwanted traffic.</p>
+<p><strong>Enabling Publishing</strong></p>
+<p>To publish your local blackhole list, enable the <code class="docutils literal notranslate"><span class="pre">publish_blackhole</span></code> option in the <code class="docutils literal notranslate"><span class="pre">[reticulum]</span></code> section:</p>
+<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[reticulum]</span>
+<span class="na">...</span>
+<span class="na">publish_blackhole</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span>
+<span class="na">...</span>
+</pre></div>
+</div>
+<p>When this is enabled, your Transport Instance will register a request handler at <code class="docutils literal notranslate"><span class="pre">rnstransport.info.blackhole</span></code>. Any peer that connects to this destination and requests <code class="docutils literal notranslate"><span class="pre">/list</span></code> will receive the complete set of identities currently present in your local blackhole database.</p>
+<p><strong>Federation and Trust</strong></p>
+<p>The blackhole system relies on the trust relationship between the subscriber and the publisher. By subscribing to a source, you are implicitly trusting that source to only block identities that are genuinely detrimental to the network.</p>
+<p>As the ecosystem matures, this system is designed to integrate with <strong>Network Identities</strong>. This allows communities to verify that a published blackhole list is actually provided by a specific network or organization with a certain level of reputation and trustworthiness, adding a layer of cryptographic trust to the federation process. This prevents malicious actors from publishing fake lists intended to censor legitimate traffic.</p>
+<p>For operators, this creates a scalable model where maintaining a single high-quality blocklist can protect thousands of downstream peers, drastically reducing the administrative.</p>
+</section>
+</section>
 <section id="improving-system-configuration">
 <h2>Improving System Configuration<a class="headerlink" href="#improving-system-configuration" title="Link to this heading">¶</a></h2>
 <p>If you are setting up a system for permanent use with Reticulum, there is a
@@ -1117,14 +1552,14 @@ systemctl --user enable rnsd.service
               </div>
               <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
             </a>
-          <a class="prev-page" href="gettingstartedfast.html">
+          <a class="prev-page" href="software.html">
               <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
               <div class="page-info">
                 <div class="context">
                   <span>Previous</span>
                 </div>
                 
-                <div class="title">Getting Started Fast</div>
+                <div class="title">Programs Using Reticulum</div>
                 
               </div>
             </a>
@@ -1166,11 +1601,20 @@ systemctl --user enable rnsd.service
 <li><a class="reference internal" href="#the-rnpath-utility">The rnpath Utility</a></li>
 <li><a class="reference internal" href="#the-rnprobe-utility">The rnprobe Utility</a></li>
 <li><a class="reference internal" href="#the-rncp-utility">The rncp Utility</a></li>
+<li><a class="reference internal" href="#the-rngit-utility">The rngit Utility</a></li>
 <li><a class="reference internal" href="#the-rnx-utility">The rnx Utility</a></li>
+<li><a class="reference internal" href="#the-rnsh-utility">The rnsh Utility</a></li>
 <li><a class="reference internal" href="#the-rnodeconf-utility">The rnodeconf Utility</a></li>
 </ul>
 </li>
+<li><a class="reference internal" href="#discovering-interfaces">Discovering Interfaces</a></li>
 <li><a class="reference internal" href="#remote-management">Remote Management</a></li>
+<li><a class="reference internal" href="#blackhole-management">Blackhole Management</a><ul>
+<li><a class="reference internal" href="#local-blackhole-management">Local Blackhole Management</a></li>
+<li><a class="reference internal" href="#automated-list-sourcing">Automated List Sourcing</a></li>
+<li><a class="reference internal" href="#publishing-blackhole-lists">Publishing Blackhole Lists</a></li>
+</ul>
+</li>
 <li><a class="reference internal" href="#improving-system-configuration">Improving System Configuration</a><ul>
 <li><a class="reference internal" href="#fixed-serial-port-names">Fixed Serial Port Names</a></li>
 <li><a class="reference internal" href="#reticulum-as-a-system-service">Reticulum as a System Service</a><ul>
@@ -1191,7 +1635,7 @@ systemctl --user enable rnsd.service
       
     </aside>
   </div>
-</div><script src="_static/documentation_options.js?v=baaebd52"></script>
+</div><script src="_static/documentation_options.js?v=590429e0"></script>
     <script src="_static/doctools.js?v=9bcbadda"></script>
     <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="_static/scripts/furo.js?v=46bd48cc"></script>

docs/manual/whatis.html

@@ -7,7 +7,7 @@
         <link rel="prefetch" href="_static/rns_logo_512.png" as="image">
 
     <!-- Generated with Sphinx 8.2.3 and Furo 2025.09.25.dev1 -->
-        <title>What is Reticulum? - Reticulum Network Stack 1.0.3 documentation</title>
+        <title>What is Reticulum? - Reticulum Network Stack 1.2.3 documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d111a655" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=580074bf" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
@@ -180,7 +180,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 1.0.3 documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 1.2.3 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -204,7 +204,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 1.0.3 documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 1.2.3 documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@@ -215,13 +215,17 @@
   <ul class="current">
 <li class="toctree-l1 current current-page"><a class="current reference internal" href="#">What is Reticulum?</a></li>
 <li class="toctree-l1"><a class="reference internal" href="gettingstartedfast.html">Getting Started Fast</a></li>
+<li class="toctree-l1"><a class="reference internal" href="zen.html">Zen of Reticulum</a></li>
+<li class="toctree-l1"><a class="reference internal" href="software.html">Programs Using Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
 <li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
 <li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks</a></li>
+<li class="toctree-l1"><a class="reference internal" href="git.html">Git Over Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a></li>
+<li class="toctree-l1"><a class="reference internal" href="license.html">Reticulum License</a></li>
 </ul>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="reference.html">API Reference</a></li>
@@ -262,6 +266,8 @@
 <p>Reticulum is a cryptography-based networking stack for building both local and
 wide-area networks with readily available hardware, that can continue to operate
 under adverse conditions, such as extremely low bandwidth and very high latency.</p>
+<p>To understand the foundational philosophy and goals of this system, read the
+<a class="reference internal" href="zen.html#zen"><span class="std std-ref">Zen of Reticulum</span></a>.</p>
 <p>Reticulum allows you to build wide-area networks with off-the-shelf tools, and
 offers end-to-end encryption, forward secrecy, autoconfiguring cryptographically
 backed multi-hop transport, efficient addressing, unforgeable packet
@@ -289,6 +295,18 @@ runs well even on small single-board computers like the Pi Zero.</p>
 real-world use is explored. The API and wire-format can be considered complete and stable, but
 could change if absolutely warranted.</p>
 </section>
+<section id="reference-implementation">
+<h2>Reference Implementation<a class="headerlink" href="#reference-implementation" title="Link to this heading">¶</a></h2>
+<p>The Python code, for which this documentation is written, and known as the Reticulum Network Stack,
+is the Reference Implementation of Reticulum. The Reticulum Protocol is defined entirely
+and authoritatively by this reference implementation, and this manual. It is maintained by Mark Qvist,
+identified by the Reticulum Identity <code class="docutils literal notranslate"><span class="pre">&lt;bc7291552be7a58f361522990465165c&gt;</span></code>.</p>
+<p>Compatibility with the Reticulum Protocol is defined as having full interoperability,
+and sufficient functional parity with this reference implementation. Any specific protocol
+implementation that achieves this is Reticulum. Any that does not is not Reticulum.</p>
+<p>The reference implementation is licensed under the <a class="reference internal" href="license.html#license"><span class="std std-ref">Reticulum License</span></a>.</p>
+<p>The Reticulum Protocol was dedicated to the Public Domain in 2016.</p>
+</section>
 <section id="what-does-reticulum-offer">
 <h2>What does Reticulum Offer?<a class="headerlink" href="#what-does-reticulum-offer" title="Link to this heading">¶</a></h2>
 <ul class="simple">
@@ -409,18 +427,10 @@ network, and vice versa.</p>
 <li><p>Or to quickly create interfaces with custom hardware</p></li>
 </ul>
 </li>
+<li><p>Anything else using <a class="reference internal" href="interfaces.html#interfaces-custom"><span class="std std-ref">custom interface modules</span></a> written in Python</p></li>
 </ul>
 <p>For a full list and more details, see the <a class="reference internal" href="interfaces.html#interfaces-main"><span class="std std-ref">Supported Interfaces</span></a> chapter.</p>
 </section>
-<section id="caveat-emptor">
-<h2>Caveat Emptor<a class="headerlink" href="#caveat-emptor" title="Link to this heading">¶</a></h2>
-<p>Reticulum is an experimental networking stack, and should be considered as
-such. While it has been built with cryptography best-practices very foremost in
-mind, it has not yet been externally security audited, and there could very well be
-privacy-breaking bugs. To be considered secure, Reticulum needs a thorough
-security review by independent cryptographers and security researchers. If you
-want to help out with this, or can help sponsor an audit, please do get in touch.</p>
-</section>
 </section>
 
         </article>
@@ -479,10 +489,10 @@ want to help out with this, or can help sponsor an audit, please do get in touch
             <ul>
 <li><a class="reference internal" href="#">What is Reticulum?</a><ul>
 <li><a class="reference internal" href="#current-status">Current Status</a></li>
+<li><a class="reference internal" href="#reference-implementation">Reference Implementation</a></li>
 <li><a class="reference internal" href="#what-does-reticulum-offer">What does Reticulum Offer?</a></li>
 <li><a class="reference internal" href="#where-can-reticulum-be-used">Where can Reticulum be Used?</a></li>
 <li><a class="reference internal" href="#interface-types-and-devices">Interface Types and Devices</a></li>
-<li><a class="reference internal" href="#caveat-emptor">Caveat Emptor</a></li>
 </ul>
 </li>
 </ul>
@@ -494,7 +504,7 @@ want to help out with this, or can help sponsor an audit, please do get in touch
       
     </aside>
   </div>
-</div><script src="_static/documentation_options.js?v=baaebd52"></script>
+</div><script src="_static/documentation_options.js?v=590429e0"></script>
     <script src="_static/doctools.js?v=9bcbadda"></script>
     <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="_static/scripts/furo.js?v=46bd48cc"></script>