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.