The node installer is install.sh from the agent. The panel's install command runs it with the options it needs (token, CA, download address, port, checksums). You add the optional ones yourself, before running the command. The same script upgrades an installed node with --upgrade.
# New install (the panel's command, with options added at the end)
curl -fsSL 'https://panel.example.com/downloads/install.sh' | VMSTACK_TOKEN=<token> bash -s -- \
--ca <base64 CA> --agent-url 'https://panel.example.com/downloads/vmstack-agent' --port 8443 \
--with-containers --with-zfs
# Upgrade an installed node, adding a component
curl -fsSL 'https://panel.example.com/downloads/install.sh' | bash -s -- --upgrade \
--agent-url 'https://panel.example.com/downloads/vmstack-agent' --with-ceph
Run bash install.sh --help to print the usage on the node.
All options#
| Option | New install | --upgrade |
What it does |
|---|---|---|---|
--token <hex> |
required | – | The one-time enrolment token from the panel (64 hex characters). The panel passes it as VMSTACK_TOKEN=… instead, which keeps it out of the process list. |
--ca <base64 PEM> |
required | – | The panel's CA certificate. |
--agent-url <https url> |
one of these two | one of these two | Where to download the agent binary (the linux-amd64 one). On an arm64 node the installer fetches the arm64 binary beside it (the URL with -arm64). |
--binary <path> |
A vmstack-agent binary already on the node, instead of a download. |
||
--sha256 <hex> |
optional | optional | The expected SHA-256 of the binary (amd64 when downloading). |
--sha256-arm64 <hex> |
optional | optional | The expected SHA-256 of the arm64 binary. On an arm64 node with --sha256 but without this, nothing is installed. |
--port <n> |
optional | – | The agent's port, 8443 by default. Must match the node's port in the panel. |
--panel-ip <ip> |
optional | optional | The panel's IPv4 or IPv6 address, written to agent.yaml as panel_addresses (with --upgrade only when none is there). On a new install it also restricts the agent port to it in ufw or firewalld, when one is active. |
--backup-local-root <dir> |
optional, repeatable | optional, repeatable | A directory local backup targets may use. See Local backup directories. |
--pbs-client |
optional | optional | Installs proxmox-backup-client for Proxmox Backup Server destinations. See Proxmox Backup client. |
--with-zfs |
optional | optional | Installs ZFS. See ZFS. |
--with-containers |
optional | optional | Installs LXC for containers. See Containers. |
--with-ceph |
optional | optional | Installs the Ceph client. See Ceph client. |
--setup-storage |
optional | refused | Turns empty disks into the servers' storage before the agent is installed. See Storage setup. |
--licensing enforce |
optional | optional | The node enforces the panel's licence from its first start. See Licensing. |
--force |
optional | – | Enrols a node that was enrolled before, discarding its key and certificate. See Enrolment. |
--upgrade |
– | required | Replaces the agent binary on an installed node and keeps its enrolment, certificate and settings. |
-h, --help |
Prints the usage. |
Optional components are never fatal: if a package cannot be installed, the installer prints a warning with the command to install it by hand, and the node reports the feature as unavailable until it is.
ZFS#
--with-zfs installs zfs-dkms and zfsutils-linux from Debian's contrib component, with the headers of the running kernel. If apt has no zfs-dkms, the installer adds contrib in /etc/apt/sources.list.d/vmstack-contrib.list. The kernel module is built on the node, which takes a few minutes, then loaded; the import services are enabled.
No pool is made. To make one, use the panel's Add storage page or run vmstack-agent storage zfs create-pool --key <name> on the node. See ZFS storages.
Note: With Secure Boot on, the module loads only once the DKMS signing key is enrolled.
dkms statusshows why a module did not load.
Containers#
--with-containers installs lxc, lxcfs, uidmap and apparmor, disables and masks lxc-net (the agent puts containers on its own bridges), starts lxcfs, and gives root the containers' id range root:1000000000:1000000000 in /etc/subuid and /etc/subgid. If root already has an entry there, or another range overlaps, nothing is changed and a warning says what to set. See KVM and containers.
Ceph client#
--with-ceph installs ceph-common (the rbd and ceph commands) and QEMU's RBD driver (qemu-block-extra), and loads the rbd kernel module. It configures nothing: VMStack never builds a Ceph cluster, it uses a pool of an existing one. See Ceph RBD storage.
Proxmox Backup client#
--pbs-client adds Proxmox's pbs-client repository for the node's Debian release and installs proxmox-backup-client. Proxmox's archive key is fetched over HTTPS and taken only when its checksum is the one Proxmox publishes. Proxmox builds the client for amd64 only: on an arm64 node the option only warns. Without this option nothing from Proxmox is added to apt. See Backup destinations.
Local backup directories#
--backup-local-root /backup allows local backup targets in /backup or below it, for example a second disk mounted there. Give it once per directory. Without any, local backup targets on the node are refused. The path must be absolute and plain, and may not be a system directory (/etc, /usr, /boot, /var/lib/vmstack, /var/lib/libvirt, …). With --upgrade the directories are added to those already allowed.
Storage setup#
--setup-storage runs vmstack-agent storage setup after the binary is in place and before the agent starts. It lists the node's empty disks, asks which to use and how (linear, mirror or RAID 10), shows the exact plan and the disks it will erase, and changes nothing until you type yes. It asks on the terminal, also when the script is piped into bash. The result is one LVM volume with an XFS file system mounted at /var/lib/vmstack/images, the default storage.
If the setup does not complete, the install stops; the log is /var/log/vmstack-storage-setup.log. Run the install again without --setup-storage to install on the current storage. On a node that is already installed, run vmstack-agent storage setup yourself, or add storages from the panel: see Local file storage.
Licensing#
--licensing enforce writes licensing: enforce to /etc/vmstack/agent.yaml. From its first start the node then refuses enrolment and new servers without a valid licence token from the panel. The panel adds this option to its install and upgrade commands by itself when it enforces its licence, and says so under the command.
Without the option, a node enforces only once it has received a valid token. Running servers never depend on the licence: without a valid token the node refuses only new servers (and enrolment), never power, backups, moves or anything else on existing servers. With --upgrade the line is added when it is not there. See Licensing.
Upgrade#
--upgrade replaces the agent binary and keeps the node's enrolment, certificate and settings. It also:
- installs packages a newer agent needs that are missing (only missing ones: QEMU and libvirt are never upgraded under running servers);
- installs the components you name (
--with-zfs,--with-ceph,--with-containers,--pbs-client); - installs the units that roll back a failed self-update, and cancels a self-update that was under way, so a manual upgrade is never rolled back.
Running servers are not touched. Agents from 0.18 update themselves, so --upgrade is mostly for adding a component or for an agent too old to update itself. See Agent updates on a node.
Files the installer writes#
| Path | What |
|---|---|
/usr/local/bin/vmstack-agent |
the agent |
/etc/vmstack/agent.yaml |
its configuration (mode 0600) |
/etc/vmstack/panel-ca.pem |
the panel's CA |
/var/lib/vmstack/ |
state, key and certificate; images/ is the default storage |
vmstack-agent.service, vmstack-agent-rollback.timer |
systemd units |