Skip to content

Configuration

Sherpa uses TOML configuration files for both the server and client.

Server Configuration

The server configuration file is located at /opt/sherpa/config/sherpa.toml.

It can hold secrets, so only the sherpa user can read it: the file is mode 600 and its folder 750, both owned by sherpa. Members of the sherpa group cannot read it. Edit it as sherpa, which keeps the owner and mode:

sudo -u sherpa -H nano /opt/sherpa/config/sherpa.toml

or with sudoedit /opt/sherpa/config/sherpa.toml. sherpad init writes it as 600; the update script sets the owner and mode of an existing file and leaves its contents alone. See file permissions.

Example

name = "sherpa-server"
server_ipv4 = "10.0.0.1"
ws_port = 3030
http_port = 3031
vm_provider = "libvirt"
qemu_bin = "/usr/bin/qemu-system-x86_64"
management_prefix_ipv4 = "172.31.0.0/16"
images_dir = "/opt/sherpa/images"
containers_dir = "/opt/sherpa/containers"
bins_dir = "/opt/sherpa/bins"
allow_signup = false

[tls]
enabled = true
self_generate_cert = true
cert_validity_days = 365

[otel]
enabled = false

[scanner]
enabled = true
interval_secs = 30

[tailscale]
image = "tailscale/tailscale:v1.102.3"
socket_path = "/run/tailscale/tailscaled.sock"
exec_timeout_secs = 75
daemon_ready_timeout_secs = 20
enrollment_timeout_secs = 60
connection_timeout_secs = 30
stop_timeout_secs = 10

[host_memory]
reserve_mib = 4096
overcommit_percent = 100

Base Fields

Property Type Default Description
name string Server name (required)
server_ipv4 string 127.0.0.1 Server IPv4 address
server_ipv6 string Server IPv6 address
ws_port int 3030 WebSocket port
http_port int 3031 HTTP port
vm_provider string VM provider — "libvirt" (required)
qemu_bin string Path to QEMU binary (required)
management_prefix_ipv4 string 172.31.0.0/16 Management network IPv4 CIDR, /24 or shorter, not a x.x.0.0/24. sherpad init --management-prefix-ipv4 sets it when it writes the config
management_prefix_ipv6 string fd00:b00b::/48 when unset Management network IPv6 CIDR, /63 or shorter. sherpad init --management-prefix-ipv6 sets it when it writes the config. See IP Addressing
images_dir string Directory for VM/unikernel images (required)
containers_dir string Directory for container images (required)
bins_dir string Directory for binary files (required)
allow_signup bool false Let anyone create an account on the web UI's signup page. Off, the page returns 404 and only admins create accounts, with sherpa server user create

[server_connection]

Internal server connection settings.

Property Type Default Description
url string WebSocket URL override
http_port int 3031 The server's HTTP port, which serves its certificate on first connect
timeout_secs int 3 Connection timeout in seconds
validate_certs bool true Trust a server certificate a public CA issued without asking; see below
ca_cert_path string Path to custom CA certificate for self-signed certs
insecure bool false Skip certificate validation (development only)

With validate_certs = true, the client first trusts the public certificate authorities. A server with a publicly issued certificate is trusted without a prompt. For any other certificate, such as the self-signed one Sherpa generates, the client shows the certificate and its key pin, the SHA-256 of the server's public key, and asks you to trust it. Later connections trust the server while it presents the same public key, whatever certificate it carries (see Certificate Commands). With validate_certs = false, the client trusts only certificates you have trusted, and asks about every new server. ca_cert_path and insecure take precedence over both.

[tls]

TLS configuration for the server.

Property Type Default Description
enabled bool true Enable TLS for connections
cert_path string /opt/sherpa/.certs/server.crt Path to server certificate (PEM)
key_path string /opt/sherpa/.certs/server.key Path to server private key (PEM)
self_generate_cert bool true Whether sherpad owns the certificate and key; see below
cert_validity_days int 365 Validity in days of the certificate sherpad writes when self_generate_cert is on
san list<string> [] Subject Alternative Names (DNS names, IPs) of the certificate sherpad writes; without them, the server's addresses, localhost and its host name

With self_generate_cert = true, sherpad owns the files at cert_path and key_path. It keeps the key, and makes a new one only when the key file is missing or does not load. On every start it writes a new self-signed certificate for that key, valid for cert_validity_days and naming the server's current addresses, so restarting sherpad renews the certificate and follows a changed address. Clients trust the key, so they do not ask again. A new key, made when the old one is lost, is a new identity, and each client must trust the server again.

With self_generate_cert = false, you provide the certificate and key, and sherpad never writes them. It does not start when either file is missing, and names the missing file. It starts with a warning in its log, and sherpad status shows the same warning, when the certificate expires within 30 days or does not name server_ipv4 or server_ipv6. Replace the files and restart sherpad to serve a new certificate.

[otel]

OpenTelemetry observability configuration. When enabled, Sherpa exports distributed traces via OTLP.

Property Type Default Description
enabled bool false Enable OpenTelemetry trace export
endpoint string http://localhost:4317 OTLP collector endpoint, over gRPC
service_name string sherpad Service name reported to the collector
sample_ratio float 1.0 Trace sampling ratio (0.0 - 1.0)

To see traces on the Sherpa server, run Jaeger all-in-one, which takes OTLP over gRPC on port 4317 and serves its UI on port 16686:

docker run -d --name jaeger \
  -p 16686:16686 \
  -p 4317:4317 \
  jaegertracing/all-in-one:latest

Set enabled = true with the default endpoint, restart sherpad, run some commands, then open http://localhost:16686 and select the sherpad service.

[scanner]

The background scanner keeps node states in line with the virtual machines and containers, for changes made outside Sherpa: a node stopped, started, crashed or removed by hand. It leaves a lab alone while an operation such as sherpa up runs on it, and it is what records a node running once it answers on its ready port after its ready check timed out; until then the node stays starting. It also checks each lab's P2P links, and attaches again the links of a running node whose link ends were made again outside Sherpa, such as a virtual machine started with virsh start or a container restarted with docker restart, so they come back within interval_secs. It also takes the link down on the other end when a node stops or is paused, and brings it back up when the node is back; see When a Neighbour Stops. For a Cisco IOL container started outside Sherpa, it also turns transmit checksum offload off again on its management interface, so TCP to its management address works. With the scanner disabled, nodes keep the states the operations recorded; sherpa inspect still shows a container's state as Docker reports it. Links broken outside Sherpa stay broken until the node is resumed or redeployed, a peer that stops outside Sherpa does not take its neighbour's link down, and sherpa inspect shows the links as not checked until then.

Property Type Default Description
enabled bool true Enable the background scanner service
interval_secs int 30 Interval between scan cycles in seconds

[tailscale]

Server settings for each lab's Tailscale gateway. The section is optional, and a partial section overrides only the listed fields. Restart sherpad after editing the server configuration.

Property Type Default Description
image string tailscale/tailscale:v1.102.3 Gateway container image; pulled if absent
socket_path string /run/tailscale/tailscaled.sock Absolute daemon socket path inside the gateway container
exec_timeout_secs int 75 Maximum wait for each Docker exec command
daemon_ready_timeout_secs int 20 Maximum wait for the daemon socket after starting the gateway
enrollment_timeout_secs int 60 Timeout passed to tailscale up for enrollment
connection_timeout_secs int 30 Maximum wait for the gateway to report connected after enrollment or resume
stop_timeout_secs int 10 Docker stop grace period before the gateway is killed

Timeouts must be positive seconds. stop_timeout_secs must fit a signed 32-bit integer. Keep exec_timeout_secs longer than enrollment_timeout_secs so the Docker command can finish. Socket paths must fit Linux's Unix socket path limit. An empty image, invalid socket path, or invalid timeout prevents server startup.

For example, increase the enrollment wait while keeping the other defaults:

[tailscale]
exec_timeout_secs = 135
enrollment_timeout_secs = 120

Image changes apply to newly created gateways. Before changing socket_path, destroy existing Tailscale-enabled labs and recreate them after restarting the server so the daemon and CLI use the same path. Docker ownership label keys remain fixed to allow safe resource identification and cleanup.

This server section is separate from the lab manifest's [tailscale] section, which enables Tailscale and names the client auth-key environment variable.

[host_memory]

How much memory the server may give its virtual machines, unikernels and containers. Before sherpa up, sherpa redeploy, sherpa resume or a node start in the web UI starts any node, the server adds up the memory already promised and refuses the request if the new nodes do not fit. Nothing is created or started when a request is refused.

Property Type Default Description
reserve_mib int 4096 Memory in MiB kept back for the host: its operating system, sherpad, QEMU's own memory and containers without a memory limit
overcommit_percent int 100 The percentage of the memory left after the reserve guests may be given in total, for example 150 for 1.5 times. Must be at least 1

The memory promised is the configured memory of every running or paused virtual machine and unikernel on the server, Sherpa's and any others libvirt runs, the memory limit of every running or paused container that has one, Sherpa's and any others Docker runs, plus the nodes other requests are starting. It is compared with the server's memory, less any reserved hugepages and reserve_mib, times overcommit_percent percent, rounded down to a whole MiB. Free memory is not used: a guest takes its memory only as it touches it, so a server that looks free when a lab starts can run out later.

A virtual machine with numa.node held strictly (numa.memory_mode = "strict", the default) is also checked against that NUMA node. Its memory cannot move to another node, so the node must have room for it beside the other virtual machines held strictly there, after the node's share of reserve_mib. A virtual machine with numa.memory_mode = "preferred" can take memory from other nodes, so it is checked against the whole server only.

A container node counts its memory limit. Containers without a memory limit are not counted; keep reserve_mib large enough for them. When the server cannot reach Docker, it counts no containers and logs a warning; labs of virtual machines are checked as before, and a lab with containers fails at its first Docker step. With overcommit_percent = 100 the guests are never given more memory than the server has. Raise it only if the guests do not use all their memory, for example idle router labs; if they touch more than the server has, the host's OOM killer stops virtual machines.

A refusal names the numbers that fell short, for example:

Not enough memory on the server: node 'r3' needs 8192 MiB, but only 2048 MiB of guest memory
is left, 6144 MiB short. ...

The refusal has its own error code, so scripts need not read the message: sherpa exits with status 75, and the API returns the INSUFFICIENT_MEMORY error.

An overcommit_percent below 1 prevents server startup, and the error names the setting. Restart sherpad after editing the server configuration.

Client Configuration

The client configuration file is located at ~/.sherpa/config/sherpa.toml. It is created by running sherpa init.

Example

name = "my-client"
server_ipv4 = "10.0.0.1"
ws_port = 3030

[server_connection]
http_port = 3031
timeout_secs = 3
validate_certs = true

[tls]
enabled = true

Client Fields

Property Type Default Description
name string "" Client name
server_ipv4 string 127.0.0.1 Server IPv4 address to connect to
server_ipv6 string Server IPv6 address to connect to
ws_port int 3030 Server WebSocket port

The client also supports the [server_connection] and [tls] sections with the same fields as the server configuration. The server's HTTP port, if it is not 3031, goes in [server_connection] as http_port. A field left out of a section takes its default. timeout_secs limits connecting to the server; a long operation such as sherpa up then runs for as long as it needs.

Without the file, the client uses these defaults. A file that exists but cannot be read or parsed is an error naming the file, rather than being silently replaced by the defaults.