mirror of
https://github.com/QubesOS/qubes-doc.git
synced 2024-10-01 01:25:40 -04:00
425 lines
15 KiB
Markdown
425 lines
15 KiB
Markdown
---
|
|
layout: doc
|
|
title: Management stack
|
|
permalink: /doc/salt/
|
|
---
|
|
# Management infrastructure
|
|
|
|
Since Qubes R3.1 release we have included `salt` (also called SaltStack)
|
|
management engine in dom0 as default with some states already configured. salt
|
|
allows administrators to easily configure their systems. In this guide we will
|
|
show how it is set up and how you can modify it for your own purpose.
|
|
|
|
In the current form the **API is provisional** and subject to change between
|
|
*minor* releases.
|
|
|
|
## Understanding `salt`
|
|
|
|
This document is not meant to be comprehensive salt documentation, however
|
|
before writing anything it is required you have at least *some* understanding of
|
|
basic salt-related vocabulary. For more exhaustive documentation, visit
|
|
[official site][salt-doc], though we must warn you that it is not easy to read
|
|
if you just start working with salt and know nothing.
|
|
|
|
### The architecture
|
|
|
|
Salt has client-server architecture, where server (called *master*) manages its
|
|
clients (called *minions*). In typical situation it is intended that
|
|
administrator interacts only with master and keeps the configuration there. In
|
|
Qubes OS we don't have master though, since we have only one minion, which
|
|
resides in `dom0` and manages domains from there. This is also supported by
|
|
salt.
|
|
|
|
Salt is a management engine, that enforces particular state of the system, where
|
|
minion runs. A *state* is an end effect *declaratively* expressed by the
|
|
administrator. This is the most important concept in the whole package. All
|
|
configuration (ie. the states) are written in YAML.
|
|
|
|
A *pillar* is a data back-end declared by administrator. When states became
|
|
repetitive, instead of pure YAML they can be written with help of some template
|
|
engine (preferably jinja2), which can use data structures specified in pillars.
|
|
|
|
A *formula* is a ready to use, packaged solution that combines state and pillar,
|
|
possibly with some file templates and other auxiliary files. There are many of
|
|
those made by helpful people all over the Internet.
|
|
|
|
A *grain* is some data that is also available in templates, but its value is not
|
|
directly specified by administrator. For example the distribution (like
|
|
`"Debian"` or `"Gentoo"`) is a value of the grain `"os"`. It also contains other
|
|
info about kernel, hardware etc.
|
|
|
|
A *module* is a Python extension to salt that is responsible for actually
|
|
enforcing the state in a particular area. It exposes some *imperative* functions
|
|
for administrator. For example there is `system` module that has `system.halt`
|
|
function that, when issued, will immediately halt the computer. There is another
|
|
function called `state.highstate` which will synchronize the state of the system
|
|
with the administrator's will.
|
|
|
|
### Configuration
|
|
|
|
#### States
|
|
|
|
The smallest unit of configuration is a state.
|
|
A state is written in yaml and looks like this:
|
|
|
|
stateid:
|
|
cmd.run: #this is the execution module. in this case it will execute a command on the shell
|
|
- name: echo 'hello world' #this is a parameter of the state.
|
|
|
|
The stateid has to be unique over all states running for a minion and can be used
|
|
to order the execution of states.
|
|
`cmd.run` is the execution module. It decides which action will be executed.
|
|
`name: echo 'hello world'` is a parameter for the execution module. It depends on
|
|
the module which parameters are accepted.
|
|
|
|
There is list of [officially available states][salt-doc-states].
|
|
There are many very useful states:
|
|
|
|
* For [managing files][salt-doc-states-file]: Use this to create files or
|
|
directories and change them (append lines, replace text, set their content etc.)
|
|
* For [installing and uninstalling][salt-doc-states-pkg] packages.
|
|
* To [execute shell commands][salt-doc-states-cmd].
|
|
|
|
With these three states you can do most of the configuration inside of a vm.
|
|
|
|
You also can [order the execution][salt-doc-states-order] of your states:
|
|
|
|
D:
|
|
cmd.run:
|
|
- name: echo 1
|
|
- order: last
|
|
C:
|
|
cmd.run:
|
|
- name: echo 1
|
|
B:
|
|
cmd.run:
|
|
- name: echo 1
|
|
- require:
|
|
- cmd: A
|
|
- require_in:
|
|
- cmd:C
|
|
A:
|
|
cmd.run:
|
|
- name: echo 1
|
|
- order: 1
|
|
|
|
The order of execution will be `A, B, C, D`.
|
|
The official documentation has more details on the [require][salt-doc-states-req] and
|
|
[order][salt-doc-states-ord] arguments.
|
|
|
|
#### State files
|
|
|
|
When configuring a system you will write one or several state files (`*.sls`) and
|
|
put (or symlink) them in the salt main directory `/srv/salt/`.
|
|
Each state file contains one multiple states and should describe some unit of
|
|
configuration (e.g.: A state file `mail.sls` could setup a vm for mailing).
|
|
|
|
#### Top files
|
|
|
|
After you have state several state files, you need something to assign them to a
|
|
vm. This is done by `*.top` files ([official documentation][salt-doc-top]).
|
|
Their structure looks like this:
|
|
|
|
environment:
|
|
target_matching_clause:
|
|
- statefile1
|
|
- folder2.statefile2
|
|
|
|
The environment will be in most cases `base`.
|
|
The `target_matching_clause` will be used to select your minions (vms).
|
|
It can be just the name of a vm or a regular expression.
|
|
If you are using a regular expression, you need to give salt a hint you are doing
|
|
so:
|
|
|
|
environment:
|
|
^app-(work|(?!mail).*)$:
|
|
- match: pcre
|
|
- statefile
|
|
|
|
For each target you can write a list of state files.
|
|
Each line is a path to a state file (without the `.sls`) relative to the main
|
|
directory. Each `/` is exchanged by a dot, so you can't reference files or
|
|
directories with a dot in their name.
|
|
|
|
### Enabling top files and applying the configuration
|
|
|
|
Now because we use custom extension to manage top files (instead of just
|
|
enabling them all) to enable the particular top file you should issue command:
|
|
|
|
qubesctl top.enable my-new-vm
|
|
|
|
To list all enabled tops:
|
|
|
|
qubesctl top.enabled
|
|
|
|
And to disable one:
|
|
|
|
qubesctl top.disable my-new-vm
|
|
|
|
To actually apply the states to dom0 and all vms:
|
|
|
|
qubesctl --all state.highstate
|
|
|
|
(More information on the command is further down.)
|
|
|
|
### Templating files
|
|
|
|
You will sometimes find your self writing repetitive states. To solve this,
|
|
there is the ability to template files or states.
|
|
This can be done with [jinja][jinja].
|
|
Jinja is similar to python and behaves in many cases similar, but there
|
|
sometimes are differences (e.g. If you set some variable inside a loop,
|
|
the variable outside will not get changed. Unless you use a do statement).
|
|
So you should take a look at the [jinja api documentation][jinja-tmp].
|
|
How you can use jinja to directly call salt functions and get data about
|
|
your system is documented in the [salt documentation][jinja-call-salt-functions].
|
|
|
|
## Salt configuration, Qubes OS layout
|
|
|
|
All salt configuration in `/srv/` directory, as usual. The main directory is
|
|
`/srv/salt/` where all state files reside. States are contained in `*.sls`
|
|
files. However the states that are part of standard Qubes distribution are
|
|
mostly templates and the configuration is done in pillars from formulas.
|
|
|
|
The formulas are in `/srv/formulas`, including stock formula for domains in
|
|
`/srv/formulas/dom0/virtual-machines-formula/qvm`, which are used by firstboot.
|
|
|
|
Because we use some code that is not found in older versions of salt, there is
|
|
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 a quick example:
|
|
|
|
my new and shiny vm:
|
|
qvm.present:
|
|
- name: salt-test # can be omitted when same as ID
|
|
- template: fedora-21
|
|
- label: yellow
|
|
- mem: 2000
|
|
- vcpus: 4
|
|
- flags:
|
|
- proxy
|
|
|
|
It uses Qubes-specific `qvm.present` state, which ensures that domain is
|
|
created. The name should be `salt-test` (and not `my new and shiny vm`),
|
|
the rest are domains properties, same as in `qvm-prefs`. `proxy` flag informs
|
|
salt that the domain should be a ProxyVM.
|
|
|
|
This should be put in `/srv/salt/my-new-vm.sls` or another `.sls` file. Separate
|
|
`*.top` file should be also written:
|
|
|
|
base:
|
|
dom0:
|
|
- my-new-vm
|
|
|
|
The third line should contain the name of the previous file, without `.sls`.
|
|
|
|
To enable the particular top file you should issue command:
|
|
|
|
qubesctl top.enable my-new-vm
|
|
|
|
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
|
|
|
|
As in example above, it creates domain and sets its properties.
|
|
|
|
### qvm.prefs
|
|
|
|
You can set properties of existing domain:
|
|
|
|
my preferences:
|
|
qvm.prefs:
|
|
- name: salt-test2
|
|
- netvm: sys-firewall
|
|
|
|
Note that `name:` is a matcher, ie. it says the domain which properties will be
|
|
manipulated is called `salt-test2`. This implies that you currently cannot rename
|
|
domains this way.
|
|
|
|
### qvm.service
|
|
|
|
services in my domain:
|
|
qvm.service:
|
|
- name: salt-test3
|
|
- enable:
|
|
- service1
|
|
- service2
|
|
- disable:
|
|
- service3
|
|
- service4
|
|
- default:
|
|
- service5
|
|
|
|
This enables, disables, or sets to default, the services as in qvm-service.
|
|
|
|
### qvm.running
|
|
|
|
|
|
Ensures the domain is running:
|
|
|
|
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
|
|
|
|
## Debugging
|
|
The output for each vm is logged in `/var/log/qubes/mgmt-VM_NAME.log`.
|
|
|
|
If the log does not contain useful information, you can stop `qubesctl` by
|
|
pressing `ctrl+z`.
|
|
|
|
You need to:
|
|
1. run `sudo qubesctl --skip-dom0 --target=VM_NAME state.highstate`
|
|
2. When your vm is being started (yellow) press Ctrl-Z on qubesctl.
|
|
3. Open terminal in disp-mgmt-VM_NAME.
|
|
4. Look at /etc/qubes-rpc/qubes.SaltLinuxVM - this is what is
|
|
executed in the management vm.
|
|
5. Get the last two lines:
|
|
|
|
export PATH="/usr/lib/qubes-vm-connector/ssh-wrapper:$PATH"
|
|
salt-ssh "$target_vm" $salt_command
|
|
|
|
Adjust $target_vm (VM_NAME) and $salt_command (state.highstate).
|
|
6. Execute them, fix problems, repeat.
|
|
|
|
## Known pitfalls
|
|
|
|
### Using fedora-24-minimal
|
|
The fedora-24-minimal package is missing the sudo package.
|
|
You can install it via:
|
|
|
|
qvm-run -p vmname 'dnf install -y sudo'
|
|
|
|
The `-p` is will cause the execution to wait until the package is installed.
|
|
This is important when using a state with `cmd.run`.
|
|
|
|
### Disk quota exceeded (when installing templates)
|
|
If you install multiple templates you may encounter this error.
|
|
The solution is to shut down the updatevm between each install.
|
|
E.g.:
|
|
|
|
{% raw %}
|
|
install template and shutdown updatevm:
|
|
cmd.run:
|
|
- name: sudo qubes-dom0-update -y fedora-24; qvm-shutdown {{salt.cmd.run(qubes-prefs updatevm) }}
|
|
{% endraw %}
|
|
|
|
## Further reading
|
|
|
|
* [Salt documentation][salt-doc]
|
|
* [Salt states][salt-doc-states] ([files][salt-doc-states-file], [commands][salt-doc-states-cmd],
|
|
[packages][salt-doc-states-pkg], [ordering][salt-doc-states-order])
|
|
* [Top files][salt-doc-top]
|
|
* [Jinja templates][jinja]
|
|
* [Qubes specific modules][salt-qvm-doc]
|
|
* [Formula for default Qubes VMs][salt-virtual-machines-doc] ([and actual states][salt-virtual-machines-states])
|
|
|
|
[salt-doc]: https://docs.saltstack.com/en/latest/
|
|
[salt-qvm-doc]: https://github.com/QubesOS/qubes-mgmt-salt-dom0-qvm/blob/master/README.rst
|
|
[salt-virtual-machines-doc]: https://github.com/QubesOS/qubes-mgmt-salt-dom0-virtual-machines/blob/master/README.rst
|
|
[salt-virtual-machines-states]: https://github.com/QubesOS/qubes-mgmt-salt-dom0-virtual-machines/tree/master/qvm
|
|
[salt-doc-states]: https://docs.saltstack.com/en/latest/ref/states/all/
|
|
[salt-doc-states-file]: https://docs.saltstack.com/en/latest/ref/states/all/salt.states.file.html
|
|
[salt-doc-states-pkg]: https://docs.saltstack.com/en/latest/ref/states/all/salt.states.pkg.html
|
|
[salt-doc-states-cmd]: https://docs.saltstack.com/en/latest/ref/states/all/salt.states.file.html
|
|
[salt-doc-states-order]: https://docs.saltstack.com/en/latest/ref/states/ordering.html
|
|
[salt-doc-states-req]: https://docs.saltstack.com/en/latest/ref/states/requisites.html
|
|
[salt-doc-states-ord]: https://docs.saltstack.com/en/latest/ref/states/ordering.html#the-order-option
|
|
[salt-doc-top]:https://docs.saltstack.com/en/latest/ref/states/top.html
|
|
[jinja]: http://jinja.pocoo.org/
|
|
[jinja-tmp]: http://jinja.pocoo.org/docs/2.9/templates/
|
|
[jinja-call-salt-functions]: https://docs.saltstack.com/en/getstarted/config/jinja.html#get-data-using-salt
|