WHAT: The xo-tag-automation plugn 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).

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.

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):

1. Create a dedicated XO user account for the service (e.g. a non-admin account with only the minimal access permissions required)

2. Generate a scoped API token via xo-cli:
   xo-cli --register
   xo-cli token.create

3. Store the token securely -- treat it like a password!

4. 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:

1. Remove the script:

   sudo rm /usr/local/bin/set-performance.sh
   

2. Remove the crontab entry:

     crontab -e
     (delete the line referencing set-performance.sh)
   

3. Note: The plugin handles its own scheduling via the XO UI. No manual cron configuration is required.

INSTALLATION

1. Download the latest airgap release tarball from GitHub:
   https://github.com/johnezero/xo-tag-automation_plugin/releases

2. SCP the tarball to your XOA:

   scp xo-tag-automation-airgap-vX.X.X.tar.gz <xoa-user>@<xoa-ip>:/tmp/
   

3. Create the plugin folder:

   sudo mkdir -p /usr/local/lib/node_modules/xo-server-tag-automation
   

4. 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
   

5. Restart xo-server:

   sudo systemctl restart xo-server
   

6. 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
   

7. 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...