Agent commands

Every vmstack-agent command you can run on a node: version, storage list, setup, add, grow and remove, bridge rollback and node-firewall off.

The vmstack-agent binary on each node (/usr/local/bin/vmstack-agent) is both the agent and a small set of commands for the node's console. Day to day the panel drives everything; these commands are for setting up storage without the panel, and for getting a node back when a network or firewall change has cut it off. Run them as root.

The agent refuses any word it does not know: it prints its usage and exits with status 2 without starting anything, so a mistyped command never starts a second agent.

Command What it does
vmstack-agent [-config <agent.yaml>] Runs the agent. This is what the vmstack-agent systemd unit runs; do not start it by hand while the unit runs.
vmstack-agent version Prints the version (also -version or --version).
vmstack-agent help Prints the list of commands (also -h or --help).
vmstack-agent storage … Lists the node's disks and makes, grows or removes storages. vmstack-agent storage alone prints its usage.
vmstack-agent bridge rollback [-config <agent.yaml>] Undoes a change of the uplink bridge that was not confirmed yet.
vmstack-agent node-firewall off [-config <agent.yaml>] [-state-dir <dir>] Turns the node firewall off, from the provider's console.

The configuration defaults to /etc/vmstack/agent.yaml and the state directory to /var/lib/vmstack.

The agent service#

The agent runs as vmstack-agent.service. Useful commands:

systemctl status vmstack-agent
systemctl restart vmstack-agent
journalctl -u vmstack-agent -n 200 --no-pager

Restarting the agent does not touch running servers. Agent updates are installed by the panel; vmstack-agent-rollback.timer checks a new version 3 minutes after an update (and after a boot) and puts the previous binary back if it did not come up healthy. See Agent updates.

Storage commands#

All storage commands run as root, take the agent's lock, and check the servers' disks as the agent does. Nothing is erased before you confirm: the command prints its plan and asks you to type yes. With --yes it asks nothing, but a disk that may hold data (its first or last MiB is not all zeros, shown as MAY HOLD DATA) is erased only if you also give --erase-data. The running agent sees a storage added this way at once. Everything the commands run is logged to /var/log/vmstack-storage-setup.log.

The panel does the same from the node's Storage tab; see Storage.

storage list#

vmstack-agent storage list [--config /etc/vmstack/agent.yaml]

Lists the node's disks with size, SSD or HDD, model and serial, and says for each one why it is not offered when it is not: it holds the system, is mounted or swap, is an LVM physical volume, an md or ZFS member, has partitions or a signature, is used by a libvirt domain, is removable, or is smaller than 10 GiB. It also lists volume groups with free space. It changes nothing.

storage setup#

vmstack-agent storage setup [--config /etc/vmstack/agent.yaml] [--storage-path <dir>]
    [--disks /dev/sdb,/dev/sdc | --vg <group>] [--layout linear|mirror|raid10]
    [--percent N] [--yes [--erase-data]] [--dry-run]

Makes spare disks, or the free part of a volume group, the node's main storage: one LVM volume with an XFS file system made for reflink copies, mounted at the agent's storage path (default /var/lib/vmstack/images) and added to /etc/fstab. Without --disks or --vg it asks which to use, the layout and the share of the free space.

Option Meaning
--disks The disks to use, comma-separated. They are erased.
--vg An existing volume group with free space, instead of disks.
--layout linear (sizes added up), mirror (2 disks or more) or raid10 (4 disks or more, an even number).
--percent The share of the group's free space to use, 1 to 100 (default 100).
--storage-path Where to mount it, if not the configuration's storage path.
--dry-run Print the plan and stop.

The agent is stopped during the setup and started again afterwards. It is refused when servers already have disks under the storage path. install.sh --setup-storage runs this command during a new node install.

storage add#

vmstack-agent storage add --key <key> [--config /etc/vmstack/agent.yaml] [--kind file|lvm-thin|zfs]
    (--disks /dev/sdb,/dev/sdc [--layout linear|mirror|raid10|raidz1] [--percent N]
     | --vg <group> [--percent N | --size-gb N] | --zpool <pool> | --directory <dir>) [--yes [--erase-data]]

Adds a storage named <key> beside the default one:

  • --kind file (default): an XFS volume on new disks or in a volume group's free space, or an existing directory mounted by hand (--directory; not one on the system disk).
  • --kind lvm-thin: an LVM thin pool on new disks or in a group's free space.
  • --kind zfs: a dataset in an existing pool (--zpool), or a new pool on disks (raidz1 needs three disks or more).

storage zfs create-pool#

vmstack-agent storage zfs create-pool --key <key> [--config /etc/vmstack/agent.yaml]
    [--disks /dev/sdb,/dev/sdc [--layout linear|mirror|raid10|raidz1]] [--yes [--erase-data]]

Without --disks it lists the empty disks and changes nothing. With them it shows each disk and the pool it will make, and asks you to type the disks' names back (for example sdb,sdc), not just yes.

storage grow#

vmstack-agent storage grow --key <key> [--config /etc/vmstack/agent.yaml]
    (--percent N | --size-gb N | --disk /dev/sdc) [--yes [--erase-data]]

Grows a storage from its group's free space (--percent or --size-gb), or onto another disk (--disk; storages with a linear layout only).

storage remove#

vmstack-agent storage remove --key <key> [--config /etc/vmstack/agent.yaml] [--erase] [--yes]

Removes a storage that no server uses. Without --erase the data stays where it is. With --erase it also erases what the storage was made on: for a file storage its volume, then its volume group and disks when nothing else is on them; for LVM-thin its pool, then the group and disks VMStack made; for ZFS its dataset, then the pool VMStack made. A group or pool that holds anything else is left. --erase is refused for a storage that is not mounted.

bridge rollback#

vmstack-agent bridge rollback [-config /etc/vmstack/agent.yaml]

When the panel sets up the uplink bridge for bridged servers, the agent arms a rollback timer (vmstack-bridge-rollback) before it changes the network. If the panel does not confirm the change in time (300 seconds by default), the timer runs this command, which writes the network files back as they were, runs netplan apply and removes vmbr2. If the agent's binary itself fails, the timer falls back to a plain shell script in /var/lib/vmstack/bridged/.

You only need to run it by hand when a node is cut off right after a bridge change and you do not want to wait for the timer. It does nothing when no change is pending. See Bridged networking.

node-firewall off#

vmstack-agent node-firewall off [-config /etc/vmstack/agent.yaml] [-state-dir /var/lib/vmstack]

Turns the node firewall off when the node can no longer be reached, for example after a rule shut out your SSH address or the panel. Run it from the provider's KVM, IPMI or rescue console. It first deletes the firewall table (nft delete table inet vmstack_node), whatever else is broken, then records that it was turned off on the node. It works even when the configuration cannot be read; the state directory is then taken from -state-dir, or /var/lib/vmstack.

The running agent keeps the firewall off, and the panel never turns it back on by itself. Fix the rules on the node's page in the panel, then turn the firewall on again there. See Node firewall.

Note: A firewall change made from the panel is already protected: it is applied with a rollback timer and kept only once the panel confirms it can still reach the node. node-firewall off is for a firewall that was confirmed and later turned out to lock you out.

Installer options#

Installing, upgrading and re-enrolling a node is done by install.sh, not by the agent binary. See Node installer options.