Choosing guests

--vmid is required by every command and goes before it. It takes a comma-separated list, without spaces, of:

Pattern	Selects	Example
@all or all	Every VM and container of the cluster	@all
ID	One guest	100
Name	One guest, by exact name	web-server
start:end	IDs in the range, both included	100:110
%text%	Guests whose name contains the text	%web%
text%	Guests whose name starts with the text	web%
%text	Guests whose name ends with the text	%-prod
@node-name	Guests on a node	@node-pve1
@all-name or all-name	Guests on a node, same as @node-	@all-pve1
@pool-name	Guests in a pool and its nested pools	@pool-production
@tag-name	Guests with a tag	@tag-snapshot
- + any of the above	Excludes those guests	@all,-100, @all,-@pool-test, @all,-200:299

Names, nodes, pools and tags are compared without regard to case. A guest selected by two patterns is taken once.

@all,-@node-pve3             everything except the guests on pve3
@tag-snapshot,-@tag-test     the guests tagged "snapshot", without those tagged "test"
@pool-production,-100        the production pool, without guest 100
100:199,-150:159             IDs 100 to 199, except 150 to 159

Exclusions are applied after everything else, whatever their place in the list.

The selection is read at every run

The list is resolved when the tool starts, from the current state of the cluster. A guest that was migrated to another node, added to the pool or given the tag is picked up by the next run, with no change to the command. Only @node-… ties the selection to a node.

Tags work well for this: tag the guests that need snapshots in the web UI and schedule --vmid=@tag-snapshot once. To stop the snapshots of a guest, remove the tag, and run clean --keep=0 on it if you want its old snapshots gone too.

Guests that are skipped

• Templates are always skipped, by snap and by clean.
• Stopped guests are skipped by snap only with --only-running. Without it a stopped guest gets its snapshot like the others.
• Guests on a full storage are skipped by snap: see --max-perc-storage.
• Guests Proxmox VE cannot snapshot are skipped by snap: a container with a bind mount (mp0: /srv/data,mp=/data) or a device (mp0: /dev/sdb1,…), a VM with a physical disk (scsi1: /dev/disk/by-id/…). Proxmox VE refuses their snapshot every time, also for mount points with backup=0: the flag counts for backups, not for snapshots.
• Guests on a node that is offline (Proxmox VE reports their status as unknown) are skipped by snap and clean, and the run exits with 1: they did not get what the schedule asked for.

Templates, stopped guests with --only-running and guests Proxmox VE cannot snapshot do not change the exit code; guests on a full storage or an offline node do.

Check the selection

A dry run prints one ----- VM … ----- line for each selected guest and changes nothing:

cv4pve-autosnap --host=pve1 --api-token='…' --vmid='@pool-production,-@tag-test' --dry-run snap --label=test --keep=1

status is not suited to this: it lists snapshots, so a selected guest without snapshots of the tool does not appear.

Quote the value when it contains characters your shell treats specially.