Setup Guide

Guides

Choose between two types of setup, a manual setup where you create the configurations yourself, or a hymn based one which manages configurations and naming for you.

Manual setup
Hymn based setup

Manual setup

This guide is aimed at people wanting to manually set up Sanctum between two machines where at least one machine has a public IP — let's call this a client-to-server setup.

For this example we will use the following parameters:

• server ip = 1.2.3.4
• client tunnel net = 10.0.0.1/24
• server tunnel net = 10.0.0.2/24

Building

Make sure you read the README.md to see what dependencies you want. On both client and server:

$ git clone https://github.com/jorisvink/sanctum
$ cd sanctum
$ less README.md
$ make
# make install

Environment

Create a directory for Sanctum and set the right permissions on it. You will want to do this on both client and server.

# mkdir -p /etc/sanctum
# chmod 0700 /etc/sanctum

The shared secret

Generate the shared secret on either the client or the server and figure out a way to securely transfer it to the other peer.

# dd if=/dev/urandom of=/etc/sanctum/secret bs=32 count=1

Sanctum will automatically combine this symmetric key with an asymmetric key exchange that consists of ECDH (x25519) and MLKEM-1024.

Configurations

We will configure both the client and server so that the process talking to the outside world (purgatory-*) runs as a separate user, while the others run as root.

Configuring the client

Create the following configuration file under /etc/sanctum/client.conf. Replace user with the user you want these processes to run as (either your own, or a dedicated one).

instance to-server

tunnel 10.0.0.1/24 1422
secret /etc/sanctum/secret

peer 1.2.3.4:1234

run heaven-rx as user
run heaven-tx as user
run purgatory-rx as user
run purgatory-tx as user

run control as user
control /tmp/sanctum.control user

run bless as root
run chapel as root
run confess as root

Now start it:

# sanctum -d -c /etc/sanctum/client.conf

Configuring the server

Create the following configuration file under /etc/sanctum/server.conf, again replacing user as needed.

instance to-client

tunnel 10.0.0.2/24 1422
secret /etc/sanctum/secret

local 1.2.3.4:1234

run heaven-rx as user
run heaven-tx as user
run purgatory-rx as user
run purgatory-tx as user

run control as user
control /tmp/sanctum.control user

run bless as root
run chapel as root
run confess as root

Now start it:

# sanctum -d -c /etc/sanctum/server.conf

Up and running

If everything went well you now have a tunnel between both devices and can ping each other's tunnel addresses.

$ ping 10.0.0.1
64 bytes from 10.0.0.1: icmp_seq=0 ttl=255 time=21 ms
64 bytes from 10.0.0.1: icmp_seq=1 ttl=255 time=22 ms
64 bytes from 10.0.0.1: icmp_seq=2 ttl=255 time=21 ms

Hymn setup

You can also use the hymn tool to get up and running faster. Hymn is part of the Sanctum repository and acts as a system configuration tool. The next few steps assume you've already generated and shared the secret as described above.

Tunnel configuration

Configure the client using the hymn tool:

$ sudo hymn add 01-02 tunnel 10.10.0.1/24 mtu 1422 peer 1.2.3.4:1234 \
    secret /etc/sanctum/secret

And now the server side:

$ sudo hymn add 02-01 tunnel 10.10.0.2/24 mtu 1422 local 1.2.3.4:1234 \
    peer 0.0.0.0:0 secret /etc/sanctum/secret

Tunnel up

Bring the instances up with the hymn up command and the correct instance name. On the client:

$ sudo hymn up 01-02

And on the server side:

$ sudo hymn up 02-01

After a few seconds the tunnel will be alive.

Tunnel status

You can see tunnel status using the hymn status command.

$ hymn status 01-02
hymn-01-02:
  local         0.0.0.0:0
  tunnel        10.0.0.1/24 (mtu 1422)
  peer          1.2.3.4:1234

  routes
    10.0.0.0/24

  accepts
    10.0.0.0/24

  tx
    spi            0x0201c23d (age: 1943 seconds)
    pkt            9929
    bytes          1034939
    last packet    3 seconds ago

  rx
    spi            0x0102a866 (age: 1943 seconds)
    pkt            6151
    bytes          2050832
    last packet    6 seconds ago

Useful hymn commands

• hymn down — Bring down a tunnel.
• hymn list — Show all configured instances.
• hymn route add — Route a new network over the tunnel.
• hymn route del — Remove a previously added route.