mirror of
https://github.com/savoirfairelinux/opendht.git
synced 2026-11-08 12:28:42 +00:00
Adrien Beraud
a32acbfa08
With persist_path, a transport key generated by the node is saved in the state (owner-only file permissions) and restored on start, keeping the node ID across restarts. Configured keys are never written to the state.
258 lines
9.1 KiB
Groff
258 lines
9.1 KiB
Groff
.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).
|
|
.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.
|
|
.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>
|