Skip to content

Manifest

A Manifest describes the lab configuration parameters. Manifests are defined in the toml format in a file named manifest.toml in the current directory.

Example Manifest

# manifest.toml
name = "sexy-salamander"

nodes = [
  { name = "dev01", model = "sonic_linux" },
  { name = "dev02", model = "arista_ceos" },
]

links = [
  { src = "dev01::gig4", dst = "dev02::gig4" },
]

Required Parameters

name (string)

The name of the lab.

To avoid naming collisions, the lab name is hashed with the users username to create a lab-id. Resources are suffixed with the lab-id to create unique resource names.

name = "sexy-salamander"

nodes (list<node_object>)

The nodes that will be managed as part of this lab.

nodes = []

Required Node Parameters

name (string)

The name of the device.

name = "dev01"
model (string)

The model of the device.

model = "sonic_linux"

Optional Node Parameters

binary_files (list<object>)

A list of binary files to include with the node.

binary_files = [
  { source = "/path/to/binary" },
]
Property Type Description
source string Source file path on the client
boot_disk_size (int)

Change the size of the boot disk in GigaBytes (GB).

boot_disk_size = 100
commands (list<string>)

A list of commands to execute at boot.

commands = [
  "apt-get update",
  "apt-get install -y curl",
]

This parameter currently only applies to node models that support the cloud-init based ZTP method.

cpu_count (int)

Configure the number of CPUs.

cpu_count = 4
environment_variables (list<string>)

A list of environment variables to pass to a node.

environment_variables = [
  # Supply the token inline. Beware, this is very insecure for sensitive vars.
  "SOME_VAR1=hello_jimmy",
  "MUSICAL_GENIUS='xyz-to-da-1-2-3'",
  # Load variable from your client environment with a dollar sign ($) prefixed variable name.
  "GH_TOKEN=$GH_TOKEN",
  "ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY",
]

This parameter currently only applies to node models that support the cloud-init based ZTP method.

image (string)

Custom image name to use instead of the default for this model.

image = "custom-ubuntu"
ipv4_address (string)

Static IPv4 address for the management interface.

ipv4_address = "10.0.0.10"
ipv6_address (string)

Static IPv6 address for the management interface.

ipv6_address = "fd00::10"
kernel_cmdline (string)

Kernel command line arguments for DirectKernel unikernel nodes. Passed to QEMU via the libvirt <cmdline> XML element. Overrides any auto-injected command line.

kernel_cmdline = "/usr/bin/nginx"

This parameter only applies to unikernel nodes using the direct_kernel boot mode.

memory (int)

Configure the amount of RAM in MegaBytes (MB).

memory = 4096
privileged (bool)

Run the container in privileged mode.

privileged = true
ready_port (int)

TCP port to probe on the node's management IP to verify readiness. When set, Sherpa waits for a successful TCP connection to this port in addition to the libvirt domain reaching the running state.

ready_port = 80

This parameter only applies to unikernel nodes.

shm_size (int)

Shared memory size in bytes.

shm_size = 67108864
skip_ready_check (bool)

Skip the node readiness check after deployment.

skip_ready_check = true
ssh_authorized_key_files (list<object>)

SSH public key file references.

ssh_authorized_key_files = [
  { source = "~/.ssh/id_ed25519.pub" },
]
Property Type Description
source string Path to the public key file
ssh_authorized_keys (list<string>)

SSH public keys to authorize on the node (inline).

ssh_authorized_keys = [
  "ssh-ed25519 AAAA... user@host",
]
startup_scripts (list<string>)

A list of paths to scripts on the client that will run on node startup.

startup_scripts = [
  "/path/to/script1.sh",
  "/path/to/script2.sh",
]

This parameter currently only applies to node models that support the cloud-init based ZTP method.

systemd_units (list<object>)

Systemd units to deploy to the node.

systemd_units = [
  { name = "myservice.service", source = "units/myservice.service", enabled = true },
]
Property Type Description
name string Unit file name
source string Source file path on the client
enabled bool Whether to enable the unit
text_files (list<object>)

A list of text files to pass to a node.

text_files = [
  { src = "~/.claude.json", dst = "/home/sherpa/.claude.json", user = "sherpa", group = "sherpa", permissions = 600 },
]

This parameter currently only applies to node models that support the cloud-init based ZTP method.

Note

The dst should be a fully qualified path.

Property Type Description
src string Source file path on the client
dst string Destination path on the node
user string File owner
group string File group
permissions int File permissions (e.g., 600)
user (string)

Default user for command execution.

user = "admin"
user_scripts (list<string>)

A list of paths to user scripts on the client.

user_scripts = [
  "/path/to/user-script.sh",
]
version (string)

Specific image version to use instead of the default.

version = "22.04"
volumes (list<object>)

Volume mounts for the node.

volumes = [
  { src = "/host/path", dst = "/container/path" },
]
Property Type Description
src string Source path on the host
dst string Destination path in the node
ztp_config (string)

Path to a custom ZTP configuration file on the client.

ztp_config = "configs/dev01.txt"

Optional Parameters

bridges (list<bridge_object>)

Bridges define shared layer 2 network segments that connect multiple node interfaces.

Unlike links which create point-to-point connections between two nodes, bridges allow three or more interfaces to share a common network segment.

Each bridge link is defined with the node name and interface separated by a double colon (::)

bridges = [
  { name = "shared", links = ["dev01::eth2", "dev02::eth2", "dev03::eth1"] },
]
Property Type Description
name string A user-friendly name for the bridge
links list<string> A list of <device>::<interface> mappings to connect to the bridge

For more information on bridge types see the private-bridge architecture documentation.

config_management (object)

Enable configuration management tool integrations. When enabled, Sherpa generates inventory files for the specified tools.

[config_management]
ansible = true
pyats = false
nornir = false
Property Type Default Description
ansible bool false Generate Ansible inventory
pyats bool false Generate pyATS testbed
nornir bool false Generate Nornir inventory

Links define the connectivity relationship between nodes in the topology.

Each device is defined with its name and interface separated by a double colon (::)

links = [
  { src = "dev01::eth0", dst = "dev02::eth1" },
]
Property Type Required Description
src string yes Source <device>::<interface> mapping
dst string yes Destination <device>::<interface> mapping
p2p bool no Enable point-to-point link mode (default: false)
impairment object no Network impairment configuration

Apply network impairment to simulate real-world link conditions.

links = [
  { src = "dev01::eth1", dst = "dev02::eth1", impairment = { delay = 50, jitter = 10, loss_percent = 1.0 } },
]
Property Type Description
delay int One-way delay in milliseconds
jitter int Delay jitter in milliseconds
loss_percent float Packet loss percentage (0.0 - 100.0)
reorder_percent float Packet reordering percentage (0.0 - 100.0)
corrupt_percent float Bit-flip corruption percentage (0.0 - 100.0)

For more information on link types see the point-to-point architecture documentation.

ready_timeout (int)

Global timeout in seconds for node readiness checks. Overrides the default timeout for all nodes in the lab.

ready_timeout = 300

ztp_server (object)

Configure the Zero-Touch Provisioning server settings.

[ztp_server]
enable = true
username = "sherpa"
password = "sherpa"
Property Type Default Description
enable bool true Enable or disable the ZTP server
username string "sherpa" Username for ZTP authentication
password string "sherpa" Password for ZTP authentication