Operations¶

Updating¶

sudo -u unseenet bash -c 'cd ~/unseenet && git pull && .venv/bin/pip install -q -e .'
sudo systemctl restart unseenet-node

The onion address does not change on restart or update.

Operator contact¶

Give your users a private way to reach you. You need an identity of your own - your normal one, or a separate "operator" identity - in a client vault on your own computer.

Create a local inbox called operator on your node, with the identity you want to receive messages with. With the command line client:

unseenet --vault operator.vault id-new operator --display "Node operator"
unseenet --vault operator.vault node-add <your-node>.onion
unseenet --vault operator.vault group-create operator --type inbox --local
unseenet --vault operator.vault whoami          # shows your key

--local keeps it on this node: messages to you are never replicated.

Add an [operator] section to node.toml with your key and the group ID it printed (see Configuration), and restart the node.
Read your messages with unseenet-tui --vault operator.vault.

Only your identity can read the messages. The node stores them encrypted, so not even someone who seizes the node can read them.

Dropping a group¶

To stop carrying a group on your node - whoever owns it:

sudo -u unseenet /home/unseenet/unseenet/.venv/bin/unseenet-node \
  --data /home/unseenet/node-data --drop-group spam.stuff@ab3k5x7qwe2rtz4m

The group and its posts are deleted, and the node refuses the group from then on, also if peers send it again. Your peers are not told: it is your node's decision only. To allow it again, use --undrop-group with the same group ID. (A group removed by its owner is gone for good and cannot be restored.)

The command works while the node is running.

Getting your node listed¶

Clients offer the nodes in the project's list of known nodes (UN-RFC 0010) to new users. To be listed, fill in the form Add my node on GitHub. You need:

the node's onion address and node key - both are printed when the node starts (journalctl -u unseenet-node | grep -E "reachable|Node key");
optionally your operator key, as in [operator];
a short description for users.

A check runs at once: it connects to your node over Tor, compares the node key the node reports with the one in the form, and comments the result on the issue. Fix what it finds by editing the issue; it checks again.

Because a node key is public, the check also asks you to prove that you run the node: it posts a challenge, which you sign on the node:

sudo bash -c 'set -a; . /etc/unseenet-node.env; cd /home/unseenet && \
  sudo -E -u unseenet unseenet/.venv/bin/unseenet-node --data node-data --sign "unseenet-node-claim ..."'

Paste the ed25519:... line it prints as a comment on the issue. Only the node's passphrase can make that signature. When a maintainer accepts the request, your node is added to src/unseenet/nodes.json, the new list is posted to unseenet.nodes, and clients pick it up the next time they connect.

Listed nodes are reached over Tor every day. If yours does not answer for 3 days, you get a note on your request; after 10 days it is taken off the list. Ask again when it is back.

(A pull request that edits src/unseenet/nodes.json works too.)

Being listed means more users and more responsibility - read Your responsibility first.

Backup¶

To move or restore a node with the same onion address, you need:

/home/unseenet/node-data/onion_key.vault - the onion key, encrypted, and
the passphrase in /etc/unseenet-node.env.

Keep them separately. Without both, a restored node gets a new address and its peers must be told.

The posts themselves (articles.sqlite) are replicated across the network, so losing them is less serious; a fresh node gets new posts from its peers.

Security¶

Encrypt the disk¶

The node's data directory should be on an encrypted disk (e.g. LUKS), unlocked by you at boot. Then a powered-off machine that is stolen or seized reveals nothing.

The passphrase file

The installer stores the onion key passphrase in /etc/unseenet-node.env so the node can start unattended. That protects the key if only the data directory is copied, but not if the whole disk is. Disk encryption is what closes that gap. Alternatively, remove the file and enter the passphrase when the node starts.

What a node can and cannot see¶

The node sees	The node never sees
Open, moderated and channel groups in full	The content of closed groups
For closed groups: group ID, number of members, sizes and times of posts, author keys	Group secrets or member keys
Which groups a client reads	A client's IP address (Tor hides it)

Keep the clock right¶

Nodes reject posts dated more than an hour in the future. Make sure the machine's clock is synchronized (NTP; Proxmox containers use the host's clock).

Exposure¶

The node listens on 127.0.0.1:1119 only; Tor forwards onion traffic to it. Do not change --listen to a public interface.

Resources¶

RAM: about 300 MB at peak during start (unlocking the onion key uses Argon2id), much less afterwards.
Disk: posts are at most 64 KB and text only. A busy group with a thousand posts a day uses a few hundred MB over 90 days.
Tor log: node-data/tor/tor.log. It grows slowly; rotate or delete it now and then.

Troubleshooting¶

tor failed to start - the last lines of Tor's log are shown in the error. Also look in node-data/tor/tor.log. Common causes: the tor package is missing, or the data directory is not writable by the unseenet user.

No onion address after several minutes - Tor cannot reach the network. Check the machine's internet connection and clock. Some networks block Tor; Tor bridges are not supported by Unseenet yet.

Peer unreachable - shown as a warning in the journal. The peer may be down, or its address may be wrong. Posts stay queued and are delivered when it comes back.

the node answered with key ..., not the configured ... - the key you have for that peer is wrong, or the peer has a new node key. Ask its operator for the key ("Node key:" in their journal).

the peer did not accept our key - the peer does not have your node key in its [[peer]] section (or has an old one). Send it your key; see Peering.

authentication failed (password peering) - the peer's name and password do not match on both sides.

A post is rejected - the client shows why: postage (too little proof-of-work), permission (not allowed in that group type), group (the node does not carry that group), date (clock problem).