summaryrefslogtreecommitdiff
path: root/doc/usage.mdwn
blob: 569637eeba8f52d99242d706db9d2f276072084f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
# 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/>

Warning: Automatically converted into a man page by mdwn2man. Edit with care.