Liturgy Guide

Liturgy mode

Sanctum has a full mesh mode called liturgy, built on the basic principle that you don't set up tunnels manually. With the help of cathedrals, clients discover each other and automatically set up tunnels. This can be used for fault-tolerant networking or P2P chat, among other things.

There is a hymn subcommand (hymn liturgy) that can set up liturgy for you, but this guide goes through the manual configuration to properly explain what's happening.

Discoverable (hub) example

Here is a basic liturgy mode configuration for a client that is discoverable:

spi 01
mode liturgy
instance liturgy-example-discoverable
pidfile /run/hymn/cafebabe-01-00.pid
kek /home/sanctum/cafebabe/kek-0x01

liturgy_prefix 172.12.0.0
liturgy_discoverable yes

local 0.0.0.0:0
cathedral_id 12345678
cathedral_flock cafebabe
cathedral_secret /home/sanctum/cafebabe/id-12345678
cathedral_cosk /home/sanctum/cafebabe/cosk-12345678
cathedral 1.2.3.4:4500

run heaven-rx as sanctum-server
run heaven-tx as sanctum-server
run purgatory-rx as sanctum-server
run purgatory-tx as sanctum-server
run liturgy as sanctum-server

run control as root
control /tmp/cafebabe-01-00.control root

run bishop as root
run bless as root
run confess as root

Configuration options

spi is the local device's KEK id — 0x01 here, though the 0x prefix can be omitted.

mode instructs Sanctum that this instance runs in liturgy mode.

pidfile is where Sanctum writes its pidfile. For compatibility with the hymn tool, it's best kept under /run/hymn.

kek points at the KEK itself. See the cryptography documentation for what a KEK is and what it's used for.

liturgy_prefix is the network prefix liturgy uses for IP addresses on auto-configured tunnels. Only the first two octets matter — the third and fourth are replaced by the source and destination KEK id respectively.

liturgy_discoverable controls whether this client should be discoverable (a hub) or not (a spoke).

local is the local IP address Sanctum binds to. 0.0.0.0:0 binds to all interfaces with a randomly picked ephemeral port (usually 32768 and above, OS dependent).

cathedral_id is the id this client presents to the cathedral, tied to what KEK id and flocks the client is allowed to use.

cathedral_flock is the flock this liturgy belongs to. See the reliquary guide for what a flock is.

cathedral_secret is the path to the shared key between cathedral and client — called CS in the cryptography documentation.

cathedral_cosk is the path to the private key this client uses to sign the offers it sends to the cathedral — called COSK in the cryptography documentation.

cathedral is the IP address and port of the cathedral.

control is the path to the control socket, and the user that owns it.

run <process> as <user> configures which user a given process runs as — this applies to every such line in the configuration.

Non-discoverable (spoke) example

A client that should only connect to discoverable clients, without being discoverable itself, looks almost identical, except liturgy_discoverable is set to no. Here's one that could connect to the hub example above:

spi 02
mode liturgy
instance liturgy-example-non-discoverable
pidfile /run/hymn/cafebabe-02-00.pid
kek /home/sanctum/cafebabe/kek-0x02

liturgy_prefix 172.12.0.0
liturgy_discoverable no

local 0.0.0.0:0
cathedral_id 87654321
cathedral_flock cafebabe
cathedral_secret /home/sanctum/cafebabe/id-87654321
cathedral_cosk /home/sanctum/cafebabe/cosk-87654321
cathedral 1.2.3.4:4500

run heaven-rx as sanctum-client
run heaven-tx as sanctum-client
run purgatory-rx as sanctum-client
run purgatory-tx as sanctum-client
run liturgy as sanctum-client

run control as root
control /tmp/cafebabe-02-00.control root

run bishop as root
run bless as root
run confess as root

In this scenario, both peers set up their part of the tunnel and the first client sets the IP address 172.12.1.2 on its endpoint, while the second client sets the IP address 172.12.2.1.