diff --git a/configuration/salt.md b/configuration/salt.md index 9256433b..d1da491e 100644 --- a/configuration/salt.md +++ b/configuration/salt.md @@ -69,6 +69,42 @@ a tool called `qubesctl` that should be run instead of `salt-call --local`. It accepts all arguments of the vanilla tool. +## Configuring system inside of VMs + +Starting with Qubes 3.2, Salt in Qubes can be used to configure VMs. Salt +formulas can be used normal way. Simply set VM name as target minion name in +top file. You can also use `qubes` pillar module to select VMs with a +particular property (see below). Then you need to pass additional arguments to +`qubesctl` tool: + + usage: qubesctl [-h] [--show-output] [--force-color] [--skip-dom0] + [--targets TARGETS | --templates | --app | --all] + ... + + positional arguments: + command Salt command to execute (for example: state.highstate) + + optional arguments: + -h, --help show this help message and exit + --show-output Show output of management commands + --force-color Force color output, allow control characters from VM, + UNSAFE + --skip-dom0 Skip dom0 condifuration (VM creation etc) + --targets TARGETS Coma separated list of VMs to target + --templates Target all templates + --app Target all AppVMs + --all Target all non-disposable VMs (TemplateVMs and AppVMs) + + +To apply the configuration to all the templates, call `qubesctl --templates +state.highstate`. + +Actual configuration is applied using `salt-ssh` (running over `qrexec` instead +of `ssh`). Which means you don't need to install anything special in a VM you +want to manage. Additionally for each target VM, `salt-ssh` is started from a +temporary VM. This way dom0 doesn't directly interact with potentially +malicious target VM. + ## Writing your own configuration Let's start with quick example: @@ -116,6 +152,31 @@ To actually apply the state: qubesctl state.highstate +### Example of VM system configuration + +It is also possible to configure system inside the VM. Lets make sure that `mc` +package is installed in all the templates. Similar to previous example, you +need to create state file (`/srv/salt/mc-everywhere.sls`): + + mc: + pkg.installed: [] + +Then appropriate top file (`/srv/salt/mc-everywhere.top`): + + base: + - qubes:type:template: + - match: pillar + - mc-everywhere + +Now you need to enable the configuration: + + qubesctl top.enable mc-everywhere + +And apply the configuration: + + qubesctl --all state.highstate + + ## All Qubes-specific states ### qvm.present @@ -159,6 +220,29 @@ Ensures the domain is running: qvm.running: - name: salt-test4 +## qubes pillar module + +Additional pillar data is available to ease targeting configuration (for +example all the templates). List here may be subject to changes in future +releases. + +### qubes:type + +VM type. Possible values: + + - `admin` - administration domain (`dom0`) + - `template` - Template VM + - `standalone` - Standalone VM + - `app` - template based AppVM + +### qubes:template + +Template name on which given VM is based (if any). + +### qubes:netvm + +VM which provides network to the given VM + ## Further reading * [Salt documentation][salt-doc]