propellor - property-based host configuration management in
haskell
propellor is a property-based host configuration management
program written and configured in haskell.
- propellor --init
- Get started by initializing a ~/.propellor/ repository.
- After this, you'll edit ~/.propellor/config.hs to configure
propellor.
- propellor
- Once propellor is configured, running it without any options will take
action as needed to satisfy the configured properties of the local
host.
- If there's a central git repository, it will first fetch from it, check
the gpg signature and merge, and rebuild propellor, so that any
configuration changes will immediately take effect.
- If propellor is run by a non-root user without any options, this is the
same as running propellor --spin with the hostname of the local host.
- propellor --spin targethost [targethost ...] [--via relayhost]
- Causes propellor to automatically install itself on the specified target
host, or if it's already installed there, push any updates. Propellor is
then run on the target host, to satisfy its configured properties.
- A signed git commit is made by --spin, so that any changes you have made
get propagated to the target host.
- Multiple target hosts can be specified; propellor will run on each of them
in sequence.
- When run with --via, propellor sshes to the relay host and runs
propellor --spin hostname from there. This can be useful when
propellor is installing itself, since most of the data transfer is done
between relay host and target host. Note that propellor uses ssh agent
forwarding to make this work, and the relay host sees any privdata
belonging to the target host.
- Propellor configuration typically uses the FQDN of hosts. The hostname
given to --spin can be a short name, which is then looked up in the DNS to
find the FQDN.
- propellor --build
- Causes propellor to build itself, checking that your config.hs, etc are
valid.
- You do not need to run this as a separate step; propellor automatically
builds itself when using things like --spin.
- propellor --add-key keyid
- Adds a gpg key, which is used to encrypt the privdata.
- Multiple gpg keys can be added; the privdata will be encrypted so that all
of them can decrypt it.
- If the gpg secret key is present, git is configured to sign commits using
this key. Propellor requires signed commits when pulling from a central
git repository.
- propellor --rm-key keyid
- Stops encrypting the privdata to a gpg key.
- propellor --list-fields
- Lists all privdata fields that are used by your propellor configuration.
The first 2 columns are the field name and context, and are followed by a
list of the hosts that use that privdata value.
- propellor --set field context
- Sets a field of privdata. The content is read in from stdin.
- propellor --unset field context
- Removes a value from the privdata store.
- propellor --unset-unused
- Removes all values from the privdata store that are not currently in
use.
- propellor --dump field context
- Outputs the privdata value to stdout.
- propellor --edit field context
- Opens $EDITOR on the privdata value.
- propellor --merge
- Combine multiple --spin commits into a single, more useful commit.
- When using propellor, you may find yourself repeatedly running
propellor --spin until you get things working the way you like.
This results in a lot of git commits being made, with incremental
changes.
- To clean that up to a single commit, use propellor --merge. A
normal interactive git commit will then be made, consisting of all changes
that have been previously committed by --spin, since the last time a
normal git commit was made.
- (This will result in a trapezoid pattern in gitk.)
- propellor --check
- If propellor is able to run, this simply exits successfully.
- propellor hostname
- When run with a hostname and no other options, propellor will provision
the local host with the configuration of that hostname. This is useful
when the local host doesn't yet have its hostname set correctly.
- ~/.propellor/config.hs
- This is the default config file used by propellor.
- ./config.hs
- If propellor is run in a directory containing a config.hs, it assumes that
the current directory is a propellor repository, and uses the
configuration from the current directory, rather than ~/.propellor/
Set PROPELLOR_DEBUG=1 to make propellor output each command
it runs and other debugging information.
git config propellor.debug 1 will configure propellor to
output debugging information.
git config propellor.spin-branch foo will configure
propellor to refuse to spin when the foo branch is not checked out.
git config propellor.forbid-dirty-spin true will configure
propellor to refuse to spin when there are uncommitted changes in the
~/.propellor repository.
git config propellor.buildsystem stack makes propellor use
stack for building itself, rather than the default cabal. This only controls
the local build of propellor; Hosts can have properties set to control how
propellor is built on them.
The usual git configuration controls which centralized repository
(if any) propellor pushes and pulls from.
Additionally, the url of a remote named "deploy", if it
exists in your ~/.propellor/ repository, is used as the origin url for the
other repositories.
Joey Hess <id@joeyh.name>
<https://propellor.branchable.com/>