From f186b71ca51e83837db60de13322394bb5e6d348 Mon Sep 17 00:00:00 2001 From: murilo ijanc Date: Tue, 24 Mar 2026 21:41:06 -0300 Subject: Initial commit Import existing tesseras.net website content. --- book/en/running-a-node.html | 314 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 314 insertions(+) create mode 100644 book/en/running-a-node.html (limited to 'book/en/running-a-node.html') diff --git a/book/en/running-a-node.html b/book/en/running-a-node.html new file mode 100644 index 0000000..480a611 --- /dev/null +++ b/book/en/running-a-node.html @@ -0,0 +1,314 @@ + + + + + + Running a Node - Tesseras User Guide + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+

Keyboard shortcuts

+
+

Press ← or → to navigate between chapters

+

Press S or / to search in the book

+

Press ? to show this help

+

Press Esc to hide this help

+
+
+
+
+ + + + + + + + + + + + + +
+ +
+
+ + + + + + + +
+
+

Running a Node

+

The tesseras-daemon binary runs a full Tesseras node that participates in the peer-to-peer network. It listens for connections over QUIC, joins the distributed hash table (DHT), and enables other nodes to discover and find tessera pointers.

+

Starting the daemon

+
tesseras-daemon
+
+

On first run, the daemon:

+
    +
  1. Creates the data directory (~/.local/share/tesseras on Linux, ~/Library/Application Support/tesseras on macOS)
    2. +
  2. Generates a node identity with proof-of-work (takes about 1 second)
    3. +
  3. Binds a QUIC listener on 0.0.0.0:4433
    4. +
  4. Bootstraps into the network by contacting seed nodes
    5. +
  5. Prints daemon ready when fully operational
    6. +
+

Command-line options

+
tesseras-daemon [OPTIONS]
+
+
+ + + + + + + + + + +
OptionDescriptionDefault
-c, --config <PATH>Path to a TOML config fileNone (uses built-in defaults)
-l, --listen <ADDR>Address and port to listen on0.0.0.0:4433
-b, --bootstrap <ADDRS>Comma-separated bootstrap addressesboot1.tesseras.net:4433,boot2.tesseras.net:4433
-d, --data-dir <PATH>Data directoryPlatform-specific (see above)
+
+

CLI options override values from the config file.

+

Examples

+

Run with defaults (join the public network):

+
tesseras-daemon
+
+

Run as a seed node (no bootstrap, other nodes connect to you):

+
tesseras-daemon --bootstrap ""
+
+

Run on a custom port with a specific data directory:

+
tesseras-daemon --listen 0.0.0.0:5000 --data-dir /var/lib/tesseras
+
+

Bootstrap from a specific node:

+
tesseras-daemon --bootstrap "192.168.1.50:4433"
+
+

Join a local network of multiple nodes:

+
tesseras-daemon --bootstrap "192.168.1.10:4433,192.168.1.11:4433"
+
+

Node identity

+

Each node has a unique identity stored in <data-dir>/identity.key. This file contains a 32-byte public key and an 8-byte proof-of-work nonce.

+

The node ID is derived from the public key: BLAKE3(pubkey || nonce) truncated to 20 bytes. The nonce must produce a hash with 8 leading zero bits, which takes about 256 hash attempts. This lightweight proof-of-work makes creating thousands of fake identities expensive while costing legitimate users less than a second.

+

The identity is generated automatically on first run and reused on subsequent runs. If you delete identity.key, a new identity will be generated.

+

Logging

+

The daemon uses structured logging via tracing. Control the log level with the RUST_LOG environment variable:

+
# Default (info level)
+tesseras-daemon
+
+# Debug logging
+RUST_LOG=debug tesseras-daemon
+
+# Only show warnings and errors
+RUST_LOG=warn tesseras-daemon
+
+# Debug for DHT, info for everything else
+RUST_LOG=info,tesseras_dht=debug tesseras-daemon
+
+

Shutting down

+

Press Ctrl+C to initiate graceful shutdown. The daemon will:

+
    +
  1. Stop accepting new connections
    2. +
  2. Finish in-flight operations (up to 5 seconds)
    3. +
  3. Close all QUIC connections
    4. +
  4. Exit cleanly
    5. +
+

Firewall

+

The daemon communicates over UDP port 4433 (QUIC). If you’re behind a firewall, ensure this port is open for both inbound and outbound UDP traffic.

+
# Example: Linux with ufw
+sudo ufw allow 4433/udp
+
+ +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + + + + + + + + + + +
+ + -- cgit v1.2.3