Katzenpost

Quickstart guide

Table of Contents

Systemd commands
Server CLI commands
Management interface
Monitoring

This topic provides collects basic commands for installed Katzenpost server components in a single convenient place. All system commands require superuser privileges.

The commands in this topic do not apply to the Katzenpost Docker image, which has its own controls. For more information, see Using the Katzenpost Docker test network.

Systemd commands

These commands match the suggested systemd setup described in Installing Katzenpost.

Table 1. Systemd control commands for Katzenpost

Task	Command
Start a mix node.	systemctl start katzenpost-mixserver
Stop a mix node.	systemctl stop katzenpost-mixserver
Restart a mix node.	systemctl restart katzenpost-mixserver
Start a diectory authority node.	systemctl start katzenpost-authority
Stop a diectory authority node.	systemctl stop katzenpost-authority
Restart a diectory authority node.	systemctl restart katzenpost-authority

Server CLI commands

The primary Katzenpost server binaries are katzenpost-mixserver, which instantiates a mix node, gateway node, or service provider depending on its configuration, and katzenpost-authority, which instantiates a directory authority.

Table 2. Command options for the Katzenpost server binaries

Task	Command
Control a mix node.	Run katzenpost-mixserver -h for options. `$` katzenpost-mixserver -h Usage of katzenpost-mixserver: -f string Path to the authority config file. (default "katzenpost.toml") -g Generate the keys and exit immediately. -v Get version info. The `-f` parameter can be used to specify a customized path and filename for the server configuration file, which is typically `/etc/katzenpost-mixserver/katzenpost.toml`. The `-g` option is used to generate the public and private signing and link keys. By default, these must be manually copied to the directory defined by the `DataDir` parameter in `/etc/katzenpost-mixserver/katzenpost.toml`.
Control a directory authority.	Run katzenpost-authority -h for options. `$` katzenpost-authority -h Usage of katzenpost-authority: -f string Path to the authority config file. (default "authority.toml") -g Generate the keys and exit immediately. -v Get version info. The `-f` parameter can be used to specify a customized path and filename for the server configuration file, which is typically `/etc/katzenpost-authority/authority.toml`. The `-g` option is used to generate the public and private signing and link keys. By default, these must be manually copied to the directory defined by the `DataDir` parameter in `/etc/katzenpost-authority/authority.toml`.

Task

Command

Control a mix node.

Run katzenpost-mixserver -h for options.

$ katzenpost-mixserver -h
Usage of katzenpost-mixserver:
  -f string
    	Path to the authority config file. (default "katzenpost.toml")
  -g	Generate the keys and exit immediately.
  -v	Get version info.

The -f parameter can be used to specify a customized path and filename for the server configuration file, which is typically /etc/katzenpost-mixserver/katzenpost.toml.

The -g option is used to generate the public and private signing and link keys. By default, these must be manually copied to the directory defined by the DataDir parameter in /etc/katzenpost-mixserver/katzenpost.toml.

Control a directory authority.

Run katzenpost-authority -h for options.

$ katzenpost-authority -h
Usage of katzenpost-authority:
  -f string
    	Path to the authority config file. (default "authority.toml")
  -g	Generate the keys and exit immediately.
  -v	Get version info.

The -f parameter can be used to specify a customized path and filename for the server configuration file, which is typically /etc/katzenpost-authority/authority.toml.

Management interface

Katzenpost provides a management interface that is accessed through a unix domain socket. The interface supports run-time changes to nodes without requiring a restart. By default, the management interface is disabled. To enable it, change the Management section of the node's configuration file so that Enable = true:

[Management]
   Enable = true
   Path = "/node_datadir/management_sock"

For more information about management configuration, see the details for your node type in Components and configuration of the Katzenpost mixnet.

Use the socat command-line utility to connect to the management socket and issue commands, with the following syntax:

# socat unix:/node-datadir/management_sock STDOUT

The following commands are supported.

QUIT - Exit the management socket session.
SHUTDOWN - Shut down the server gracefully.
ADD_USER - Add a user and associate it with a public link key provided in either hexadecimal or Base64 format.
```
ADD_USER userkey
```
UPDATE_USER - Update a user's link key.
```
UPDATE_USER userkey
```
REMOVE_USER - Remove a user.
```
REMOVE_USER user
```
SET_USER_IDENTITY - Set a user's identity key.
```
SET_USER_IDENTITY userkey
```
REMOVE_USER_IDENTITY - Remove a user's identity key. This command must be followed up with a REMOVE_USER command.
```
REMOVE_USER_IDENTITY user
```
USER_IDENTITY - Retrieve a user's identity key.
```
USER_IDENTITY user
```
SEND_RATE - Set the packet rate limit to a per-minute integer value.
```
SEND_RATE value
```
SEND_BURST - Set the packet burst-rate limit to a per-minute integer value.
```
SEND_BURST value
```

Monitoring

Katzenpost logging information can be viewed in real time with the following commands:

# journalctl -u katzenpost-mixserver -f -n 2000

# journalctl -u katzenpost-authority -f -n 2000

Logging levels include ERROR, WARNING, NOTICE, INFO, and DEBUG, with INFO as the default. For information about setting the log level, see the documentation for each node type in Components and configuration of the Katzenpost mixnet.

Last modified March 5, 2025: Revisions per review, spell-checked, link-checked, files regenerated (1e64ace3)