opendht/doc/dhtnode.1

.TH DHTNODE 1 2026-04-18
.SH NAME
.B dhtnode
- a simple OpenDHT command line node runner.
.SH SYNOPSIS
.B dhtnode
[\fB\-h\fR]
[\fB\-V\fR]
[\fB\-v\fR [\fB\-l\fR \fIlogfile\fR] [\fB\-L\fR]]
[\fB\-i\fR [\fB\-I\fR \fIfile\fR]]
[\fB\-c\fR \fIfile\fR]
[\fB\-k\fR \fIfile\fR]
[\fB\-m\fR \fIpassword\fR]
[\fB\-d\fR] [\fB\-s\fR]
[\fB\-D\fR] [\fB\-U\fR] [\fB\-P\fR]
[\fB\-n\fR \fInetwork_id\fR]
[\fB\-p\fR \fIlocal_port\fR]
[\fB\-b\fR \fIbootstrap_host\fR[:\fIport\fR]]
[\fB\-f\fR \fIpath\fR]
[\fB\-S\fR \fIport\fR]
[\fB\-e\fR \fIport\fR]
[\fB\-a\fR \fIaddress\fR]
[\fB\-w\fR \fIfile\fR]
[\fB\-K\fR \fIfile\fR]
[\fB\-M\fR \fIpassword\fR]
[\fB\-C\fR \fIserver\fR]
[\fB\-y\fR \fIendpoint\fR]
[\fB\-z\fR \fIkey\fR]
[\fB\-u\fR \fIbundleid\fR]
[\fB\-\-no\-encryption\fR]
[\fB\-\-transport\-key\fR \fIfile\fR]
[\fB\-\-network\-authority\fR \fIkey\fR]
[\fB\-\-network\-credential\fR \fIfile\fR]
.br
.B dhtnode
\fB\-\-gen\-network\-authority\fR \fIprefix\fR
.br
.B dhtnode
\fB\-\-issue\-credential\fR \fIfile\fR
\fB\-\-authority\-key\fR \fIfile\fR
\fB\-\-transport\-key\fR \fIfile\fR
[\fB\-\-validity\fR \fIdays\fR]
.SH DESCRIPTION
Runs an OpenDHT node, with an interactive CLI (default) or as a daemon (with \fB'-d'\fP or \fB'-s'\fP).
Commands available in the interactive shell are:
.EX
    h, help    Print this help message.
    x, quit    Quit the program.
    log        Start/stop printing DHT logs.

    Node information:
    ll         Print basic information and stats about the current node.
    ls [key]   Print basic information about current search(es).
    ld [key]   Print basic information about currenty stored values on this
               node (or for a specific key).
    lr         Print the full current routing table of this node.

    Operations on the DHT:
    b <ip:port>            Ping potential node at given IP address/port.
    g <key>                Get values at <key>.
    l <key>                Listen for value changes at <key>.
    cl <key> <token>       Cancel listen for <token> and <key>.
    p <key> <str>          Put string value at <key>.
    pp <key> <str>         Put string value at <key> (persistent version).
    cpp <key> <id>         Cancel persistent put operation for <key> and
                           value <id>.
    s <key> <str>          Put string value at <key>, signed with our
                           generated private key.
    e <key> <dest> <str>   Put string value at <key>, encrypted for <dest>
                           with its public key (if found).
    cc                     Trigger connectivity changed signal.

    Operations with the proxy (if compiled with proxy server support):
    pst [port] <pushServer>  Start the proxy interface on port.
    psx [port]               Start the proxy SSL interface on port.
    psp [port]               Stop the proxy interface on port.

    Operations with the proxy (if compiled with proxy client support):
    stt [server_address] <device_key>  Start the proxy client.
    stp                                Stop the proxy client.
    rs  [token]                        Resubscribe to opendht.
    rp  [token]                        Inject a push notification.
.EE
.SH OPTIONS
.TP
\fB\-h\fP, \fB\-\-help\fP
Prints help and exits.
.TP
\fB\-V\fP, \fB\-\-version\fP
Prints version information and exits.
.TP
\fB\-v\fP, \fB\-\-verbose\fP
Enable verbose mode (log to stdout/stderr by default).
.TP
\fB\-l\fP \fIlogfile\fP, \fB\-\-logfile\fP \fIlogfile\fP
Write log to file instead of stdout/stderr.
.TP
\fB\-L\fP, \fB\-\-syslog\fP
Write log to syslog instead of stdout/stderr (enables verbose mode).
.TP
\fB\-i\fP, \fB\-\-identity\fP
Generate a cryptographic identity (RSA key pair and self-signed certificate)
for the node. Required to perform cryptographic operations (encrypt/sign values)
if no private key file is provided.
.TP
\fB\-I\fP \fIfile\fP, \fB\-\-save\-identity\fP \fIfile\fP
Save generated identity (certificate and private key) to given file prefix.
Files are saved as \fIfile\fP and \fIfile\fP_ca.
.TP
\fB\-c\fP \fIfile\fP, \fB\-\-certificate\fP \fIfile\fP
Load identity certificate from given file. If specified, the certificate is
published on the DHT.
.TP
\fB\-k\fP \fIfile\fP, \fB\-\-privkey\fP \fIfile\fP
Load identity private key from given file. Required to perform cryptographic
operations if no identity is generated.
.TP
\fB\-m\fP \fIpassword\fP, \fB\-\-privkey\-password\fP \fIpassword\fP
Password to use for private key encryption or decryption (optional).
.TP
\fB\-d\fP, \fB\-\-daemonize\fP
Run the program in daemon mode (will fork in the background). When verbose mode
is enabled, logs to syslog by default.
.TP
\fB\-s\fP, \fB\-\-service\fP
Run the program in service mode (non\-forking daemon).
.TP
\fB\-D\fP, \fB\-\-peer\-discovery\fP
Enables multicast automatic local peer discovery.
.TP
\fB\-U\fP, \fB\-\-no\-rate\-limit\fP
Disable rate limiting (allows unlimited requests and storage).
.TP
\fB\-P\fP, \fB\-\-public\-stable\fP
Enable public stable mode.
.TP
\fB\-f\fP \fIpath\fP, \fB\-\-persist\fP \fIpath\fP
Specify a file path to persist/load the node state (routing table, values and
generated transport key). State is written to a temporary file and renamed
over the destination only after the write succeeds. Save failures are logged.
.TP
\fB\-n\fP \fInetwork_id\fP, \fB\-\-net\fP \fInetwork_id\fP
Specify the network id. This lets you connect to distinct networks and prevents
the merge of two different networks. Defaults to 0 (the main public network).
.TP
\fB\-p\fP \fIlocal_port\fP, \fB\-\-port\fP \fIlocal_port\fP
Use UDP port \fIlocal_port\fP for the program to bind to. If not set, will use
any available port. The default OpenDHT port for public nodes is 4222.
.TP
\fB\-b\fP \fIbootstrap_host\fP[:\fIport\fP], \fB\-\-bootstrap\fP \fIbootstrap_host\fP[:\fIport\fP]
Specify a bootstrap node address to connect to the network.
.TP
\fB\-S\fP \fIlocal_port\fP, \fB\-\-proxyserver\fP \fIlocal_port\fP
Run a REST API proxy server bound to this DHT node on HTTP port \fIlocal_port\fP.
.TP
\fB\-e\fP \fIlocal_port\fP, \fB\-\-proxyserverssl\fP \fIlocal_port\fP
Run a REST API proxy server with SSL bound to this DHT node on HTTPS port \fIlocal_port\fP.
.TP
\fB\-a\fP \fIaddress\fP, \fB\-\-proxy\-addr\fP \fIaddress\fP
Proxy server bind address.
.TP
\fB\-w\fP \fIfile\fP, \fB\-\-proxy\-certificate\fP \fIfile\fP
Load proxy SSL certificate from given file.
.TP
\fB\-K\fP \fIfile\fP, \fB\-\-proxy\-privkey\fP \fIfile\fP
Load proxy SSL private key from given file.
.TP
\fB\-M\fP \fIpassword\fP, \fB\-\-proxy\-privkey\-password\fP \fIpassword\fP
Password for the proxy private key encryption or decryption (optional).
.TP
\fB\-C\fP \fIserver\fP, \fB\-\-proxyclient\fP \fIserver\fP
Run this DHT node in proxy client mode, and connect to \fIserver\fP.
.TP
\fB\-y\fP \fIendpoint\fP, \fB\-\-pushserver\fP \fIendpoint\fP
Push notification server endpoint.
.TP
\fB\-z\fP \fIkey\fP, \fB\-\-devicekey\fP \fIkey\fP
Device key for push notifications.
.TP
\fB\-u\fP \fIbundleid\fP, \fB\-\-bundleid\fP \fIbundleid\fP
Bundle ID for push notifications.
.SH TRANSPORT ENCRYPTION
The DHT protocol is encrypted with nodes supporting it, and stays in plaintext
with older nodes. The node ID derives from the transport key.
.TP
\fB\-\-no\-encryption\fP
Disable protocol encryption, using a random node ID like older versions.
.TP
\fB\-\-transport\-key\fP \fIfile\fP
Load the transport key from \fIfile\fP, or create it if it doesn't exist.
Keeps the same node ID across restarts. Otherwise, a key is generated and kept
in the node state if \fB\-\-persist\fP is used, or generated on each start.
.TP
\fB\-\-network\-authority\fP \fIkey\fP
Join a private network: only accept nodes with a credential issued by the
authority with public key \fIkey\fP (hexadecimal). Can be repeated.
Requires \fB\-\-network\-credential\fP and \fB\-\-transport\-key\fP.
.TP
\fB\-\-network\-credential\fP \fIfile\fP
Credential of our transport key, issued by a network authority.
.TP
\fB\-\-gen\-network\-authority\fP \fIprefix\fP
Generate a network authority, save its secret key to \fIprefix\fP.key and its
public key to \fIprefix\fP.pub, and exit. Refuses to overwrite either existing
output path, including a dangling symlink.
.TP
\fB\-\-issue\-credential\fP \fIfile\fP
Issue a credential for the key in \fB\-\-transport\-key\fP (created if needed),
signed with \fB\-\-authority\-key\fP, save it to \fIfile\fP and exit.
.TP
\fB\-\-authority\-key\fP \fIfile\fP
Network authority secret key used to issue credentials.
.TP
\fB\-\-validity\fP \fIdays\fP
Validity of issued credentials (default: 365 days).
.SH EXAMPLES
Run a node using bootstrap.jami.net as a bootstrap:
.PP
.EX
dhtnode -b bootstrap.jami.net:4222
.EE
.PP
Run a node as a non-forking daemon on port 4222:
.PP
.EX
dhtnode -b bootstrap.jami.net -p 4222 -s
.EE
.PP
Run a proxy server on port 8000:
.PP
.EX
dhtnode -b bootstrap.jami.net:4222 --proxyserver 8000
.EE
.PP
Use a proxy client to connect to a proxy server:
.PP
.EX
dhtnode --proxyclient dhtproxy.jami.net:80
.EE
.PP
Create a private network and run one of its nodes:
.PP
.EX
dhtnode --gen-network-authority net
dhtnode --issue-credential node1.cred --authority-key net.key --transport-key node1.key
dhtnode --transport-key node1.key --network-credential node1.cred \\
        --network-authority $(cat net.pub) -b 192.0.2.1:4222
.EE
.SH AUTHORS
.TP
Program written by
.IP \(bu
.\}
Adrien Béraud <adrien.beraud@savoirfairelinux.com>
.TP
Man page written by
.IP \(bu
.\}
Simon Désaulniers <sim.desaulniers@gmail.com>