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