summaryrefslogtreecommitdiffstats
path: root/man/bcfg2.conf.5
blob: 394bb347d0b602ec5d1755b2c1b37ec12676d636 (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
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
.TH bcfg2.conf 5

.SH NAME
bcfg2.conf - configuration parameters for Bcfg2

.SH DESCRIPTION
.TP
bcfg2.conf includes configuration parameters for the Bcfg2 server and
client.

.SH FILE FORMAT
The file is INI-style and consists of sections and options. A section
begins with the name of the sections in square brackets and continues
until the next section begins.

Options are specified in the form 'name = value'.

The file is line-based each newline-terminated line represents either
a comment, a section name or an option.

Any line beginning with a hash (#) is ignored, as are lines containing
only whitespace.


.SH SERVER OPTIONS
These options are only necessary on the Bcfg2 server. They are
specified in the [server] section of the configuration file.

.TP
.B repository
Specifies the path to the Bcfg2 repository containing all of the
configuration specifications. The repository should be created
using the 'bcfg2-admin init' command.

.TP
.B filemonitor
The file monitor used to watch for changes in the repository.
Values of 'gamin', 'fam', or 'pseudo' are valid.

.TP
.B plugins
A comma-delimited list of enabled server plugins. Currently available
plugins are:

\(bu
.B Account
The account plugin manages authentication data, including:

 * /etc/passwd
 * /etc/group
 * /etc/security/limits.conf
 * /etc/sudoers
 * /root/.ssh/authorized_keys

\(bu
.B Actions

Action entries are commands that are executed either before bundle
installation, after bundle installation or both. If exit status is
observed, a failing pre-action will cause no modification of the
enclosing bundle to be performed; all entries included in that bundle
will not be modified. Failing actions are reported through Bcfg2's
reporting system, so they can be centrally observed.

\(bu
.B BB
The BB plugin maps users to machines and metadata to machines. 
(experimental)

\(bu
.B Base
A structure plugin that provides the ability to add lists of unrelated
entries into client configuration entry inventories. Base works much
like Bundler in its file format. This structure plugin is good for
the pile of independent configs needed for most actual systems.

\(bu
.B Bundler
Bundler is used to describe groups of inter-dependent configuration
entries, such as the combination of packages, configuration files,
and service activations that comprise typical Unix daemons. Bundles
are used to add groups of configuration entries to the inventory of
client configurations, as opposed to describing particular versions
of those
entries.

\(bu
.B Bzr
The Bzr plugin allows you to track changes to your Bcfg2 repository
using a GNU Bazaar version control backend. Currently, it enables
you to get revision information out of your repository for reporting
purposes.

\(bu
.B Cfg
The Cfg plugin provides a repository to describe configuration file
contents for clients. In its simplest form, the Cfg repository is
just a directory tree modeled off of the directory tree on your client
machines.

\(bu
.B Cvs
The Cvs plugin allows you to track changes to your Bcfg2 repository
using a Concurrent version control backend. Currently, it enables you
to get revision information out of your repository for reporting
purposes. (experimental)

\(bu
.B Darcs
The Darcs plugin allows you to track changes to your Bcfg2 repository
using a Darcs version control backend. Currently, it enables you to
get revision information out of your repository for reporting purposes.
(experimental)

\(bu
.B DBStats
Direct to database statistics plugin. (0.9.6 and later)

\(bu
.B Decisions
The Decisions plugin has support for a centralized set of per-entry
installation decisions. This approach is needed when particular
changes are deemed "high risk"; this gives the ability to centrally
specify these changes, but only install them on clients when
administrator supervision is available. (0.9.6 and later)

\(bu
.B Deps
The Deps plugin allows you to make a series of assertions like
"Package X requires Package Y (and optionally also Package Z etc.)

\(bu
.B Editor
The Editor plugin allows you to partially manage configuration for
a file. Its use is not recommended and not well documented.

\(bu
.B Fossil
The Fossil plugin allows you to track changes to your Bcfg2 repository
using a Fossil SCM version control backend. Currently, it enables
you to get revision information out of your repository for reporting
purposes.

\(bu
.B Git
The Git plugin allows you to track changes to your Bcfg2 repository
using a Git version control backend. Currently, it enables you to
get revision information out of your repository for reporting purposes.

\(bu
.B GroupPatterns
The GroupPatterns plugin is a connector that can assign clients group
membership based on patterns in client hostnames.

\(bu
.B Hg
The Hg plugin allows you to track changes to your Bcfg2 repository
using a Mercurial version control backend. Currently, it enables you
to get revision information out of your repository for reporting
purposes. (experimental)

\(bu
.B Hostbase
The Hostbase plugin is an IP management system built on top of Bcfg2.

\(bu
.B Metadata
The Metadata plugin is the primary method of specifying Bcfg2 server
metadata.

\(bu
.B NagiosGen
NagiosGen is a Bcfg2 plugin that dynamically generates Nagios
configuration files based on Bcfg2 data.

\(bu
.B Ohai
The Ohai plugin is used to detect information about the client
operating system. The data is reported back to the server using
JSON. (experimental)

\(bu
.B POSIXCompat
The POSIXCompat plugin provides a compatibility layer which turns
new-style (1.0) POSIX entries into old-style entries which are
compatible with previous releases.

\(bu
.B Packages
The Packages plugin is an alternative to Pkgmgr for specifying
package entries for clients. Where Pkgmgr explicitly specifies
package entry information, Packages delegates control of package
version information to the underlying package manager, installing
the latest version available from through those channels.

\(bu
.B Pkgmgr
The Pkgmgr plugin resolves the Abstract Configuration Entity
"Package" to a package specification that the client can use to
detect, verify and install the specified package.

\(bu
.B Probes
The Probes plugin gives you the ability to gather information from a
client machine before you generate its configuration. This information
can be used with the various templating systems to generate
configuration based on the results.

\(bu
.B Properties
The Properties plugin is a connector plugin that adds information
from properties files into client metadata instances. (1.0 and later)

\(bu
.B Rules
The Rules plugin resolves Abstract Configuration Entities to literal
configuration entries suitable for the client drivers to consume.

\(bu
.B SGenshi (Deprecated)
See Bundler.

\(bu
.B Snapshots
The Snapshots plugin stores various aspects of a client's state when
the client checks in to the server.

\(bu
.B SSHbase
The SSHbase generator plugin manages ssh host keys (both v1 and v2)
for hosts. It also manages the ssh_known_hosts file. It can integrate
host keys from other management domains and similarly export its keys.

\(bu
.B Svn
The Svn plugin allows you to track changes to your Bcfg2 repository
using a Subversion backend. Currently, it enables you to get revision
information out of your repository for reporting purposes.

\(bu
.B TCheetah
The TCheetah plugin allows you to use the cheetah templating system
to create files. It also allows you to include the results of probes
executed on the client in the created files.

\(bu
.B TGenshi
The TGenshi plugin allows you to use the Genshi templating system to
create files. It also allows you to include the results of probes
executed on the client in the created files.

\(bu
.B Trigger
Trigger is a plugin that calls external scripts when clients are
configured.

.TP
.B prefix
Specifies a prefix if the Bcfg2 installation isn't placed in the
default location (eg. /usr/local).

.SH MDATA OPTIONS
These options affect the default metadata settings for Paths with
type='file'.

.TP
.B owner
Global owner for Paths (defaults to root)

.TP
.B group
Global group for Paths (defaults to root)

.TP
.B perms
Global permissions for Paths (defaults to 644)

.TP
.B paranoid
Global paranoid settings for Paths (defaults to false)


.SH CLIENT OPTIONS
These options only affect client functionality, specified in the
[client] section.

.TP
.B drivers
Specify tool driver set to use. This option can be used to explicitly
specify the client tool drivers you want to use when the client is run.

.TP
.B paranoid
Run the client in paranoid mode.


.SH STATISTICS OPTIONS
Server-only, specified in the [statistics] section. These options
control the statistics collection functionality of the server.

.TP
.B database_engine
The database engine used by the statistics module. One of either
'postgresql', 'mysql', 'sqlite3', or 'ado_mssql'.

.TP
.B database_name
The name of the database to use for statistics data. If
'database_engine' is set to 'sqlite3' this is a file path to
sqlite file and defaults to $REPOSITORY_DIR/etc/brpt.sqlite

.TP
.B database_user
User for database connections. Not used for sqlite3.

.TP
.B database_password
Password for database connections. Not used for sqlite3.

.TP
.B database_host
Host for database connections. Not used for sqlite3.

.TP
.B database_port
Port for database connections. Not used for sqlite3.


.SH COMMUNICATION OPTIONS
Specified in the [communication] section. These options define
settings used for client-server communication.

.TP
.B ca
The path to a file containing the CA certificate. This file is
required on the server, and optional on clients. However, if the
cacert is not present on clients, the server cannot be verified. 

.TP
.B certificate
The path to a file containing a PEM formatted certificate which
signs the key with the ca certificate. This setting is required on
the server in all cases, and required on clients if using client
certificates. 

.TP
.B key
Specifies the path to a file containing the SSL Key. This is required
on the server in all cases, and required on clients if using client
certificates. 

.TP
.B password
Required on both the server and clients. On the server, sets the
password clients need to use to communicate. On a client, sets the
password to use to connect to the server.

.TP
.B protocol
Communication protocol to use. Defaults to xmlrpc/ssl.

.TP
.B retries
A client-only option. Number of times to retry network communication.

.TP
.B user
A client-only option. The UUID of the client.

.SH PARANOID OPTIONS
These options allow for finer-grained control of the paranoid mode
on the Bcfg2 client. They are specified in the [paranoid] section
of the configuration file.

.TP
.B path
Custom path for backups created in paranoid mode. The default is in 
/var/cache/bcfg2.

.TP
.B max_copies
Specify a maximum number of copies for the server to keep when running
in paranoid mode. Only the most recent versions of these copies will
be kept.

.SH COMPONENT OPTIONS
Specified in the [components] section.

.TP
.B bcfg2
URL of the server. On the server this specifies which interface and
port the server listens on. On the client, this specifies where the
client will attempt to contact the server.
eg: bcfg2 = https://10.3.1.6:6789

.TP
.B encoding
Text encoding of configuration files. Defaults to the system default
encoding.


.SH LOGGING OPTIONS
Specified in the [logging] section. These options control the server
logging functionality.

.B path
Server log file path.

.SH SNAPSHOTS OPTIONS
Specified in the [snapshots] section. These options control the server
snapshots functionality.

.B driver
sqlite

.B database
The name of the database to use for statistics data.
eg: $REPOSITORY_DIR/etc/bcfg2.sqlite

.SH SEE ALSO
.BR bcfg2(1),
.BR bcfg2-server(8)