Skip to content

Automated

Sherpa can be installed via a convenience installation script.

Danger

Piping to sudo can be dangerous. You are strongly encouraged to review the below script before executing the below command.

sudo privileges are requried. Run the following command to start the installation.

curl -fsSL https://raw.githubusercontent.com/bwks/sherpa/refs/heads/main/scripts/sherpa_install.sh | sudo bash

The script installs Docker from Docker's apt repository, once Docker's signing key matches the one the script pins. A key that does not match stops the install before apt trusts it.

No database server is installed: sherpad keeps its data in an embedded database, /opt/sherpa/db/sherpa.sqlite, which sherpad init creates. See Database.

File Permissions

/opt/sherpa, the binaries in /opt/sherpa/bin and /opt/sherpa/libvirt are owned by root and 755: systemd runs sherpad from there, so neither sherpa nor members of the sherpa group can change them. sherpa owns only the folders sherpad writes to, which the install and update scripts create, as sherpad cannot create a folder in /opt/sherpa. The scripts change these folders' owners and modes only, never what is in them, and stop without changing a path that has a symlink in it.

Members of the sherpa group can read the lab folders and the log, and can write the images folder, /opt/sherpa/images, and its blank disk folder; nothing else.

The install script, sherpad init and the update script give Sherpa's configuration and log files these modes, all owned by sherpa:sherpa. The files that can hold secrets are readable by the sherpa user only, not by members of the sherpa group: sherpa.toml can hold passwords, and sherpa.env whatever you add to it, such as OTEL_EXPORTER_OTLP_HEADERS for an OpenTelemetry collector that needs a token.

Path Mode Set by
/opt/sherpa, /opt/sherpa/bin, /opt/sherpa/libvirt 755, root's install, update
/opt/sherpa/bin/sherpad, /opt/sherpa/bin/sherpa 755, root's install, update
/opt/sherpa/config 750 install, update
/opt/sherpa/config/sherpa.toml 600 sherpad init, update
/opt/sherpa/env 750 install, update
/opt/sherpa/env/sherpa.env 600 install, update
/opt/sherpa/env/sherpa.env.example 600 install, update
/opt/sherpa/logs 750 install, update, sherpad
/opt/sherpa/logs/sherpad.log 640 sherpad, update
/opt/sherpa/.secret 700 install, update, sherpad
/opt/sherpa/.certs 700 install, update, sherpad
/opt/sherpa/db 750 install, update, sherpad
/opt/sherpa/images 775 install, update
/opt/sherpa/containers, /opt/sherpa/bins, /opt/sherpa/run 755 install, update

Run sherpad init as sherpa (sudo -u sherpa -H sherpad init): sherpad runs as sherpa and cannot read a sherpa.toml another account owns. sherpad init refuses any other account, root included. systemd reads sherpa.env as root. To edit either file, use sudoedit or sudo -u sherpa. Members of the sherpa group can read the log, /opt/sherpa/logs/sherpad.log, which sherpad writes when it is not run by systemd; under systemd it logs to the journal.

Blank Disks

Some nodes boot with a small configuration disk, which sherpad copies from a blank disk template in /opt/sherpa/images/blank_disk/ and writes the node's config onto:

File Disk Used by
fat32.img 64 MiB, FAT32 Cumulus Linux USB, MikroTik CHR config disk
junos.img 64 MiB, FAT16, label vmm-data Juniper vEvolved USB
iosv.img 64 MiB, FAT16 Cisco IOSv and IOSvL2 config disk
ise.img 10 MiB, ext4, label ISE-ZTP Cisco ISE config disk
ext4-500mb.img 500 MiB, ext4, label data-disk Flatcar Linux data disk

The install script creates them, as sherpa, with base.img, fat16.img and ext4 data-disk disks of 100 MiB, 200 MiB and 1 to 5 GiB that no node uses yet. Each is 644, owned by sherpa:sherpa, in a folder 775. It installs the tools that make them, qemu-utils, dosfstools and e2fsprogs, with its other packages.

The script only creates a disk that is missing, and never changes one that is there. The update script does the same on every run, so running it again restores a disk that was deleted.

Before the First Lab

Each user sets a device password, with sherpa server user device-password or on the web UI Profile page, and registers an SSH key, before the first sherpa up. sherpad init sets neither password for you, and sherpa up refuses to start a lab without a device password.

Server Key Pin

sherpad makes its TLS key when it first starts and keeps it. 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 a restart renews the certificate and follows a changed address; see [tls].

Clients trust the server's key, not one certificate. The first time a client connects, it shows the key pin, the SHA-256 of the server's public key, and asks the user to check it. A renewed certificate has the same key, so clients do not ask again. Read the key pin on the server and give it to your users:

sudo -u sherpa -H sherpad status

sherpad also logs it each time it starts, as TLS key pin (SHA-256 of the server's public key).

Transparent Hugepages

The script sets the host's transparent hugepages to madvise, so QEMU can back VM memory with 2 MiB pages. It sets it for the running system and adds a boot rule, /etc/tmpfiles.d/sherpa-thp.conf, so it stays set after a reboot. A host already set to always is left as it is, and a kernel without transparent hugepages is skipped with a warning.

madvise gives huge pages only to programs that ask for them, such as QEMU. To go back to the kernel's default, delete /etc/tmpfiles.d/sherpa-thp.conf and reboot. The uninstall script deletes it too.