NAME

       propellor - property-based host configuration management in haskell

SYNOPSIS

       propellor [options]

DESCRIPTION

       propellor is a property-based host configuration management program written and configured
       in haskell.

MODES OF OPERATION

       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.

FILES

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

ENVIRONMENT

       Set PROPELLOR_DEBUG=1 to make propellor output each command it runs  and  other  debugging
       information.

GIT CONFIGURATION

       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.

AUTHOR

       Joey Hess <id@joeyh.name>

       <https://propellor.branchable.com/>

                                                                                     propellor(1)