reticulum-utilities

name	reticulum-utilities
description	Comprehensive guide to Reticulum's command-line utilities for network management, diagnostics, identity operations, file transfer, and remote execution
triggers	["rnpath","rnprobe","rnir","rnid","rncp","rnx","rnstatus","rnsd","path inspection","network probe","identity recall","file transfer","remote execution","network status","reticulum daemon","announce database"]

Reticulum Utilities

Reticulum provides a comprehensive suite of command-line utilities for network management, diagnostics, identity operations, file transfer, and remote execution. These utilities form the operational toolkit for managing and interacting with Reticulum networks.

Overview of Utilities

Reticulum includes the following core utilities:

• rnpath: Path discovery and management
• rnprobe: Network probing and RTT measurement
• rnir: Identity Recall (announce database inspection)
• rnid: Identity management and cryptographic operations
• rncp: File transfer using the Resource API
• rnx: Remote command execution
• rnstatus: Network status and interface statistics
• rnsd: Reticulum daemon for running as a service

rnpath - Path Discovery and Management

The rnpath utility manages path discovery and routing table inspection in Reticulum networks.

Basic Path Request

Request and display a path to a destination:

# Request path to a destination (replace with actual hash)
rnpath c89b4da064bf66d280f0e4d8abfd9806

# Output shows:
# Path to <c89b4da064bf66d280f0e4d8abfd9806> requested
# Path found, destination <c89b4da064bf66d280f0e4d8abfd9806> is 3 hops away via <e89b4da064bf66d2> on AutoInterface[wlan0]

Display Path Table

View all known paths in the routing table:

# Show all paths
rnpath --table

# Show only paths with maximum 2 hops
rnpath --table --max 2

# Filter to specific destination
rnpath --table c89b4da064bf66d280f0e4d8abfd9806

Example output:

<3e12fc71692f8ec47bc5> is 1 hop  away via <3e12fc71692f8ec47bc5> on AutoInterface[eth0] expires 2026-01-15 14:23:19
<94b08f2d39ee12cf0922> is 2 hops away via <3e12fc71692f8ec47bc5> on AutoInterface[eth0] expires 2026-01-15 14:25:41
<c89b4da064bf66d280f0> is 3 hops away via <3e12fc71692f8ec47bc5> on AutoInterface[eth0] expires 2026-01-15 14:20:08

Announce Rate Information

Monitor announce rates and rate violations:

# Show announce rate info for all destinations
rnpath --rates

# Show rates for specific destination
rnpath --rates c89b4da064bf66d280f0e4d8abfd9806

Example output:

<c89b4da064bf66d280f0> last heard 2 minutes ago, 4.5 announces/hour in the last 3 hours
<3e12fc71692f8ec47bc5> last heard 30 seconds ago, 12.0 announces/hour in the last 2 hours, 2 active rate violations, new announces allowed in 45 minutes

Drop Paths

Remove paths from the routing table:

# Drop specific path
rnpath --drop c89b4da064bf66d280f0e4d8abfd9806

# Drop all paths via a specific transport instance
rnpath --drop-via 3e12fc71692f8ec47bc5

# Drop all queued announces on all interfaces
rnpath --drop-announces

Remote Management

Query path tables on remote Reticulum instances:

# Get path table from remote instance
# -R: remote transport instance identity hash
# -i: path to management identity file
# -W: timeout for remote queries
rnpath --table -R 9fb6d773498fb3feda407ed8ef2c3229 -i ~/.reticulum/identities/mgmt_id -W 15

# Get announce rates from remote instance
rnpath --rates -R 9fb6d773498fb3feda407ed8ef2c3229 -i ~/.reticulum/identities/mgmt_id

JSON Output

Export path information in JSON format for scripting:

# Export path table as JSON
rnpath --table --json

# Export announce rates as JSON
rnpath --rates --json

Common Options

--config PATH    # Use alternative config directory
-w SECONDS       # Timeout before giving up (default: 15s)
-v, --verbose    # Increase verbosity

rnprobe - Network Probing and RTT Measurement

The rnprobe utility sends probe packets to measure round-trip time (RTT) and verify connectivity.

Basic Probe

Send a probe to a destination:

# Probe a destination with full destination name
# Format: app.aspect1.aspect2... destination_hash
rnprobe lxmf.delivery c89b4da064bf66d280f0e4d8abfd9806

# Output shows:
# Sent probe 1 (16 bytes) to <c89b4da064bf66d280f0e4d8abfd9806> via <3e12fc71692f8ec4> on AutoInterface[wlan0]
# Valid reply from <c89b4da064bf66d280f0e4d8abfd9806>
# Round-trip time is 245.3 milliseconds over 3 hops

Probe with Options

Configure probe parameters:

# Send multiple probes
rnprobe -n 5 lxmf.delivery c89b4da064bf66d280f0e4d8abfd9806

# Send larger probe packet
rnprobe -s 128 lxmf.delivery c89b4da064bf66d280f0e4d8abfd9806

# Wait between probes
rnprobe -n 10 -w 2 lxmf.delivery c89b4da064bf66d280f0e4d8abfd9806

# Set custom timeout
rnprobe -t 30 lxmf.delivery c89b4da064bf66d280f0e4d8abfd9806

Verbose Output

Show detailed path information:

# Verbose output shows next hop and interface details
rnprobe -v lxmf.delivery c89b4da064bf66d280f0e4d8abfd9806

# Example output:
# Sent probe 1 (16 bytes) to <c89b4da064bf66d280f0e4d8abfd9806> via <3e12fc71692f8ec4> on AutoInterface[wlan0]
# Valid reply from <c89b4da064bf66d280f0e4d8abfd9806>
# Round-trip time is 245.3 milliseconds over 3 hops [RSSI -67 dBm] [SNR 18.5 dB] [Link Quality 94%]

Probe Statistics

When sending multiple probes, statistics are shown:

rnprobe -n 10 lxmf.delivery c89b4da064bf66d280f0e4d8abfd9806

# Output shows:
# ... (individual probe results) ...
# Sent 10, received 9, packet loss 10.0%

Exit Codes

rnprobe returns meaningful exit codes for scripting:

• 0: All probes successful
• 1: Path request timed out
• 2: Some packets lost
• 3: Probe packet exceeds MTU

Common Options

-s SIZE          # Probe packet size in bytes (default: 16)
-n COUNT         # Number of probes to send (default: 1)
-t SECONDS       # Timeout before giving up (default: 12s + hop latency)
-w SECONDS       # Time between each probe (default: 0)
-v, --verbose    # Show detailed output
--config PATH    # Use alternative config directory

rnir - Identity Recall (Announce Database)

The rnir utility runs a simple Identity Recall service, making the announce database available for inspection. This is primarily used for diagnostic purposes.

Start Identity Recall Service

# Run Identity Recall service with default config
rnir

# Use alternative config directory
rnir --config /path/to/config

# Verbose output
rnir -v

# Quiet mode
rnir -q

The Identity Recall service maintains the announce database, allowing other utilities and applications to query received announces and recalled identities. This is automatically handled by the Reticulum daemon in most deployments.

Purpose

The rnir utility serves these functions:

• Maintains the announce database
• Makes identity information available for recall
• Provides network-wide identity distribution
• Enables destination lookups by identity hash

In practice, rnir functionality is usually provided by rnsd (the Reticulum daemon), and this utility is mainly used for testing and debugging announce propagation.

rnid - Identity Management

The rnid utility provides comprehensive identity management, including key generation, import/export, signing, encryption, and destination operations.

Generate New Identity

# Create new identity file
rnid --generate ~/.reticulum/identities/my_identity

# Force overwrite if file exists
rnid --generate ~/.reticulum/identities/my_identity --force

Import and Export

# Import identity from hex string
rnid --import 7a2b9c... --write ~/.reticulum/identities/imported_id

# Import from base64
rnid --import ARF3t4w... --base64 --write ~/.reticulum/identities/imported_id

# Import from base32
rnid --import K4HGL... --base32 --write ~/.reticulum/identities/imported_id

# Export identity (private key) in hex
rnid -i ~/.reticulum/identities/my_identity --export

# Export in base64
rnid -i ~/.reticulum/identities/my_identity --export --base64

# Export in base32
rnid -i ~/.reticulum/identities/my_identity --export --base32

Display Identity Information

# Show public key (private key hidden by default)
rnid -i ~/.reticulum/identities/my_identity --print-identity

# Show both public and private keys
rnid -i ~/.reticulum/identities/my_identity --print-identity --print-private

# Output shows:
# Public Key  : 2c0461f1c6f3a6aef3971f38e2dbd663b783c8f5ad5f2eb0e9772da88d4d1ce5
# Private Key : Hidden

Calculate Destination Hashes

# Calculate destination hash for specific aspects
rnid -i ~/.reticulum/identities/my_identity --hash lxmf.delivery

# Output shows:
# The lxmf.delivery destination for this Identity is <c89b4da064bf66d2>
# The full destination specifier is <lxmf.delivery/c89b4da064bf66d280f0e4d8abfd9806>

Announce Destination

# Announce a destination based on identity
rnid -i ~/.reticulum/identities/my_identity --announce lxmf.delivery

# Output shows:
# Created destination <lxmf.delivery/c89b4da064bf66d280f0e4d8abfd9806>
# Announcing destination <c89b4da064bf66d280f0e4d8abfd9806>

File Signing and Verification

# Sign a file
rnid -i ~/.reticulum/identities/my_identity --sign document.pdf

# Creates document.pdf.rsg (signature file)

# Verify signature
rnid -i ~/.reticulum/identities/my_identity --validate document.pdf.rsg

# Output shows:
# Signature document.pdf.rsg for file document.pdf made by Identity <2c0461f1c6f3a6ae> is valid

# Sign with custom output path
rnid -i ~/.reticulum/identities/my_identity --sign document.pdf --write signature.rsg

# Verify with explicit paths
rnid -i ~/.reticulum/identities/my_identity --validate signature.rsg --read document.pdf

File Encryption and Decryption

# Encrypt file for an identity (requires public key)
rnid -i c89b4da064bf66d280f0e4d8abfd9806 --encrypt sensitive.txt

# Creates sensitive.txt.rfe (encrypted file)

# Decrypt file (requires private key)
rnid -i ~/.reticulum/identities/my_identity --decrypt sensitive.txt.rfe

# Encrypt with custom output
rnid -i c89b4da064bf66d280f0e4d8abfd9806 --encrypt sensitive.txt --write encrypted.rfe

# Decrypt with custom output
rnid -i ~/.reticulum/identities/my_identity --decrypt encrypted.rfe --write decrypted.txt

# Force overwrite
rnid -i ~/.reticulum/identities/my_identity --decrypt encrypted.rfe --force

Identity Recall from Network

# Request identity from network if not locally known
rnid -i c89b4da064bf66d280f0e4d8abfd9806 --request --print-identity

# Set custom timeout for request
rnid -i c89b4da064bf66d280f0e4d8abfd9806 --request -t 30 --print-identity

# Output shows:
# Path to <c89b4da064bf66d280f0e4d8abfd9806> requested
# Received Identity <2c0461f1c6f3a6ae> for destination <c89b4da064bf66d280f0e4d8abfd9806> from the network
# Public Key  : 2c0461f1c6f3a6aef3971f38e2dbd663b783c8f5ad5f2eb0e9772da88d4d1ce5

Common Options

-i, --identity PATH    # Path to identity file or identity/destination hash
-g, --generate PATH    # Generate new identity
-m, --import DATA      # Import identity from hex/base32/base64
-x, --export           # Export identity
-p, --print-identity   # Display identity information
-P, --print-private    # Show private key (use with caution)
-H, --hash ASPECTS     # Calculate destination hash
-a, --announce ASPECTS # Announce destination
-e, --encrypt FILE     # Encrypt file
-d, --decrypt FILE     # Decrypt file
-s, --sign FILE        # Sign file
-V, --validate FILE    # Validate signature
-R, --request          # Request unknown identity from network
-t SECONDS             # Identity request timeout
-f, --force            # Force overwrite of existing files
-r, --read FILE        # Input file path
-w, --write FILE       # Output file path
-b, --base64           # Use base64 encoding
-B, --base32           # Use base32 encoding
-v, --verbose          # Increase verbosity
-q, --quiet            # Decrease verbosity
--config PATH          # Use alternative config directory

rncp - File Transfer

The rncp utility provides secure file transfer capabilities using Reticulum's Resource API.

Send File

# Send file to destination
rncp document.pdf c89b4da064bf66d280f0e4d8abfd9806

# Silent mode (no progress animation)
rncp --silent document.pdf c89b4da064bf66d280f0e4d8abfd9806

# Show physical layer transfer rates
rncp --phy-rates document.pdf c89b4da064bf66d280f0e4d8abfd9806

# Disable automatic compression
rncp --no-compress large.zip c89b4da064bf66d280f0e4d8abfd9806

# Set custom timeout
rncp -w 60 large_file.dat c89b4da064bf66d280f0e4d8abfd9806

Example output:

Path to <c89b4da064bf66d280f0e4d8abfd9806> requested
Establishing link with <c89b4da064bf66d280f0e4d8abfd9806>
Advertising file resource
Transferring file ⢁ 45.2% - 1.81 MB of 4.00 MB - 125.30 KBps

Receive Files (Listener Mode)

# Start listener to receive files
rncp --listen

# Listen with authentication (only accept from specific identities)
rncp --listen -a c89b4da064bf66d280f0e4d8abfd9806 -a 3e12fc71692f8ec47bc5

# Listen without authentication (accept from anyone - use with caution!)
rncp --listen --no-auth

# Save received files to specific directory
rncp --listen --save ~/downloads

# Allow overwriting existing files
rncp --listen --save ~/downloads --overwrite

# Periodic announce (announce every 300 seconds)
rncp --listen -b 300

# Announce only at startup
rncp --listen -b 0

Fetch File from Listener

# Fetch file from remote listener
rncp --fetch /path/to/remote/file c89b4da064bf66d280f0e4d8abfd9806

# Fetch with custom save location
rncp --fetch /path/to/remote/file c89b4da064bf66d280f0e4d8abfd9806 --save ~/downloads

# Fetch and overwrite local file if it exists
rncp --fetch /path/to/remote/file c89b4da064bf66d280f0e4d8abfd9806 --overwrite

Listener with Fetch Permission

Allow authenticated clients to fetch files:

# Allow fetch from specific directory (jail)
rncp --listen --allow-fetch --jail /shared/files -a c89b4da064bf66d280f0e4d8abfd9806

# The jail restricts fetch requests to files under /shared/files
# Attempts to access files outside the jail are denied

Print Listener Identity

# Display listener destination hash and exit
rncp --print-identity

# Output shows:
# Identity     : <2c0461f1c6f3a6aef3971f38e2dbd663b783c8f5>
# Listening on : <c89b4da064bf66d280f0e4d8abfd9806>

Authentication Configuration

Create an allowed identities file:

# Create file at ~/.config/rncp/allowed_identities
mkdir -p ~/.config/rncp
cat > ~/.config/rncp/allowed_identities << EOF
c89b4da064bf66d280f0e4d8abfd9806
3e12fc71692f8ec47bc5
94b08f2d39ee12cf0922
EOF

# Now rncp --listen will automatically load these allowed identities

Alternative locations (checked in order):

1. /etc/rncp/allowed_identities
2. ~/.config/rncp/allowed_identities
3. ~/.rncp/allowed_identities

Common Options

-l, --listen          # Listen for incoming transfers
-f, --fetch           # Fetch file from remote listener
-F, --allow-fetch     # Allow authenticated clients to fetch files
-j, --jail PATH       # Restrict fetch to specific directory
-s, --save PATH       # Save received files to directory
-O, --overwrite       # Allow overwriting existing files
-C, --no-compress     # Disable automatic compression
-a HASH               # Allow identity (can be used multiple times)
-n, --no-auth         # Accept from anyone (no authentication)
-p, --print-identity  # Print identity and listening destination
-b SECONDS            # Announce interval (0 = only at startup, -1 = never)
-w SECONDS            # Connection timeout (default: 15s)
-P, --phy-rates       # Display physical layer transfer rates
-S, --silent          # Disable transfer progress output
-v, --verbose         # Increase verbosity
-q, --quiet           # Decrease verbosity
--config PATH         # Use alternative config directory

rnx - Remote Execution

The rnx utility enables secure remote command execution over Reticulum networks.

Execute Remote Command

# Execute command on remote system
rnx c89b4da064bf66d280f0e4d8abfd9806 "uname -a"