qubes-apply
python script to automate qubes saltstack
git clone https://9o.is/git/qubes-apply.git
commit f40fc916d69b8249447d54368acfb7dd39aaec95 parent 5586dd48baa46aa1c5defe0041faf500dd47d185 Author: Jul <jul@9o.is> Date: Fri, 27 Feb 2026 13:29:55 +0800 add documentation and licensing Diffstat:
| A | LICENSE | | | 19 | +++++++++++++++++++ |
| A | README.md | | | 46 | ++++++++++++++++++++++++++++++++++++++++++++++ |
| A | qubes-apply.1 | | | 32 | ++++++++++++++++++++++++++++++++ |
3 files changed, 97 insertions(+), 0 deletions(-)
diff --git a/LICENSE b/LICENSE @@ -0,0 +1,19 @@ +Copyright (c) 2026 Julio Cabrera <jul@qh.is> + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md @@ -0,0 +1,46 @@ +# qubes-apply + +Apply user Salt states to Qubes OS VMs with change detection. + +## Overview + +`qubes-apply` is a command-line tool for Qubes OS that manages applying user-defined Salt states to qubes (virtual machines). It tracks state changes and only applies to VMs where states have been modified. This is done by parsing top and sls files to know the dependencies, but qubes-apply only parses yaml files, not jinja, so the layout of files is opinionated. + +State is tracked in `/usr/local/var/qubes-apply/last-run.json`, which is just a json of sha1 hashes of parsed files and non-parsed directories. All top files are scanned and supports glob, pcre, and pillars `qubes:tags` `qubes:type:app` `qubes:type:template`. Only sls files in the `user_salt/base` directory (configurable) are parsed and recognize sls dependencies via the `includes` command. This is useful to group sls that are shared between vms. + +## Installation + +```bash +sudo make install +``` + +## Usage + +Initialize diff state (required before first use): +``` +qubes-apply --init +``` + +Apply changes to VMs with modified states: +``` +qubes-apply +``` + +Or apply only specified VMs: +``` +qubes-apply vm1 vm2 #... +``` + +Dry run (show what would be applied without making changes): +``` +qubes-apply --dry-run +``` + +## Options + +- `-a`, `--all` Apply all defined qubes +- `-n`, `--dry-run` Run without making changes +- `-i`, `--init` Initialize diff state +- `--force-update` Force state update without running +- `--force-color` Force colored output +- `--base-shared` Path to shared salts for dependency gathering diff --git a/qubes-apply.1 b/qubes-apply.1 @@ -0,0 +1,32 @@ +.TH QUBES-APPLY 1 +.SH NAME +qubes-apply \- apply user Salt states to Qubes VMs +.SH SYNOPSIS +.B qubes-apply +[\fIoptions\fR] [\fIqvm\fR ...] +.SH DESCRIPTION +.B qubes-apply +manages applying user-defined Salt states to Qubes OS virtual machines. It tracks state changes using a diff mechanism and only applies to VMs where states have been modified. +.SH OPTIONS +.TP +\fB\-a\fR, \fB\-\-all\fR +Apply all defined qubes. +.TP +\fB\-n\fR, \fB\-\-dry\-run\fR +Run without making changes. +.TP +\fB\-i\fR, \fB\-\-init\fR +Initialize diff state. Must be run before first use. +.TP +\fB\-\-force\-update\fR +Force state update without running. +.TP +\fB\-\-force\-color\fR +Force colored output. +.TP +\fB\-\-base\-shared\fR \fIpath\fR +Path to shared salts iterated for dependency gathering (default: base\..+). +.SH ARGUMENTS +.TP +\fIqvm\fR +A specific qube to apply. If omitted, applies to qubes with modified states.