UPDATE: Tag-Based-Automation Plugin
WHAT: The xo-tag-automation plugin is a native xo-server plugin that enforces VM performance tiers, manages group permissions, and synchronizes VM metadata -- all driven by VM tags and NFS-hosted CSV files (see below for more details). In general only apply one performance and/or permission action tag per VM. Currently XO only allows one ACL assignment per VM (e.g. assigning "Dept1-Operator", and" Dept3-Admin" to the same VM does not work).
FEATURES
PERFORMANCE SYNC
Automatically applies CPU weights and IO priorities (sched-pri) based on VM performance tier tags:
0-core -- CPU weight: 2048 IO priority: 7
1-high -- CPU weight: 1024 IO priority: 7
2-normal -- CPU weight: 512 IO priority: 5
3-low -- CPU weight: 256 IO priority: 2
All tier weights and IO priorities are fully configurable in the plugin UI. An optional pool-specific tag suffix (e.g. -1=POOL1, -2=POOL2, etc.) allows you to manage multiple pools from a single XO instance without tag collisions.
Note: Under normal conditions these performance settings do not affect anything. It's only when system resources are under high-load that the tiering levels ensure important VMs get priority over non-critical workloads, etc.
PERMISSION SYNC
VM tags ending in -Admin, -Operator, or -Viewer (e.g. "Dept1-Operator", "Dept2-Admin", etc.) automatically trigger appropriate XO Group creation and ACL assignments for the designated VM.
CSV PERMISSION MANAGEMENT FILES
Two CSV files on your NFS share drive the workflow:
current-vms.csv
A live export of your entire VM inventory. Contains UUID, Name, CurrentTags, NewTags, CurrentNotes, and NewNotes columns. Edit the NewTags and NewNotes columns and run the plugin (e.g. push the [Test plugin] button) to apply changes in bulk. The CSV auto-refreshes after each run. A staleness warning fires if the CSV has not been updated
within a configurable number of days.
preload-vms.csv
Pre-stage tag and notes configurations for VMs that do not exist yet -- before they are migrated or created. The moment a VM matching a preload entry appears in XO, the plugin applies (on next scheduled interval) its tags and notes automatically and removes the entry from the preload file.
PERMISSION AUTOPILOT
Designed for active migration and onboarding projects. Automatically applies permission settings on scheduled interval, based on preload-vms.csv contents. Note: Should be disabled when not actively involved in migration projects.
DRY-RUN / EXPORT-CSV MODE
When Dry-Run is ON (the default), the plugin previews all changes in the XO logs without applying any changes, and simultaneously exports a fresh copy of all VM metadata to current-vms.csv with blank NewTags and NewNotes columns ready to fill in. Turn Dry-Run OFF to apply changes for real.
RUN NOW (e.g. The [Test plugin] button)
Trigger a full enforcement cycle instantly from the XO plugin UI without waiting for the next scheduled run.
NFS LOGGING
All activity is written to structured log files on your NFS share:
xo-tag-automation.log -- full run log (auto-rotates at 2MB)
xo-tag-automation.log.1 -- previous log backup
xo-tag-automation-summary.log -- run summary entries only
daily-summary.log -- nightly VM count and new VM report
Logs are also available via xo-cli API methods (see below).
LEGACY MIGRATION
If you have an existing vm_metadata.csv from an older version, the plugin automatically renames it to current-vms.csv on first run. No manual migration needed.
SECURITY -- PLEASE READ CAREFULLY
This plugin automates infrastructure changes. Security is not optional. Please take both of the following seriously before enabling Permission Sync or Autopilot.
-- REST API SERVICE ACCOUNT --
The plugin uses the XO JSON-RPC API internally. Use a dedicated service account -- never your personal admin credentials.
Recommended setup (generic -- adapt to your environment):
Create a dedicated XO user account for the service (e.g. a non-admin account with only the minimal access permissions required)
Generate a scoped API token via xo-cli:
xo-cli --register
xo-cli token.create
Store the token securely -- treat it like a password!
Refer to the official Vates REST API documentation for full token management guidance:
https://xen-orchestra.com/docs/restapi.html
-- NFS SHARE SECURITY --
The NFS share hosts your CSV files and logs. Anyone with write access to the share can modify VM tags and permissions.
STRONGLY RECOMMENDED
Run the NFS share from a dedicated VM -- not a general-purpose NFS server.
Restrict NFS exports to the XOA IP address only:
/srv/nfs/share<XOAIP>/32(rw,sync,no_subtree_check,no_root_squash)
Do NOT expose the NFS share to the general network or to end-user access.
Admins who need to edit CSV files can SCP them to/from the XOA:
EXAMPLE:
Download CSV from XOA to your workstation
scp <xoa-user>@<xoa-ip>:/path/to/current-vms.csv ./
Upload edited CSV back to XOA
scp ./current-vms.csv <xoa-user>@<xoa-ip>:/path/to/current-vms.csv
Use firewall rules to enforce NFS access at the network level in addition to the exports configuration
Failure to secure the NFS share is a serious security risk.
UPGRADING FROM THE STANDALONE SCRIPT
If you installed the old standalone set-performance.sh script, you can remove it before enabling the plugin as follows:
Remove the script:
sudo rm /usr/local/bin/set-performance.sh
Remove the crontab entry:
crontab -e
(delete the line referencing set-performance.sh)
Note: The plugin handles its own scheduling via the XO UI. No manual cron configuration is required.
INSTALLATION
Download the latest airgap release tarball from GitHub:
https://github.com/johnezero/xo-tag-automation_plugin/releases
SCP the tarball to your XOA:
scp xo-tag-automation-airgap-vX.X.X.tar.gz <xoa-user>@<xoa-ip>:/tmp/
Create the plugin folder:
sudo mkdir -p /usr/local/lib/node_modules/xo-server-tag-automation
Extract directly into the plugin directory:
sudo tar -xzvf /tmp/xo-tag-automation-airgap-vX.X.X.tar.gz -C /usr/local/lib/node_modules/xo-server-tag-automation/ --strip-components=1
Restart xo-server:
sudo systemctl restart xo-server
Verify registration:
sudo journalctl -u xo-server -n 100 --no-pager | grep -A3 "tag-automation"
You should see:
[INFO] xo-tag-automation: Plugin factory called -- xo context: YES
[INFO] xo-tag-automation: Plugin loaded -- waiting for core started.
xo:plugin INFO successfully register tag-automation
Enable and configure the plugin options in XO:
Settings -> Plugins -> tag-automation -> Enable
XO-CLI API METHODS
The plugin exposes several API methods accessible via xo-cli:
xo-cli xo-server-tag-automation.exportCsv
Export current VM inventory to current-vms.csv
xo-cli xo-server-tag-automation.downloadCsvApi
Print CSV content to stdout
xo-cli xo-server-tag-automation.uploadCsvApi content@./current-vms.csv
Push an edited CSV back to the NFS share
xo-cli xo-server-tag-automation.getLog lines=100
View the last N lines of the plugin log
xo-cli xo-server-tag-automation.getDailySummary
View the nightly VM count summary
xo-cli xo-server-tag-automation.getFilePaths
Show all configured file paths
LINKS
GitHub: https://github.com/johnezero/xo-tag-automation_plugin
Vates REST API docs: https://xen-orchestra.com/docs/restapi.html
STANDARD DISCLAIMER HERE
This software is provided "AS-IS" without any express or implied warranty. While this plugin is being used in a production environment managing live VMs, you should always review the code and test it in a non-production environment before full deployment.
Note: The plugin is designed to ONLY take action on VMs with specific tags assigned (e.g. untagged VMs are never modified).
Use Dry-Run mode to preview all changes (via log file output) before applying them.
That said, as always - your mileage may vary...
[image: 1780884996846-johnezero-logo.jpg]
