summaryrefslogtreecommitdiffstats
path: root/tools/manpagegen/bcfg2.conf.5.ronn
blob: e71bdb73a9794f8869d5bc61da5ae6f6c67af376 (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
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
bcfg2.conf(5) -- configuration parameters for Bcfg2
===================================================

## DESCRIPTION

`bcfg2.conf` includes configuration parameters for the Bcfg2 server and
client.

## 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.

## SERVER OPTIONS

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

  * `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.

  * `filemonitor`:
    The file monitor used to watch for changes in the repository. The
    default is the best available monitor. The following values are
    valid:

    `inotify`,
    `gamin`,
    `fam`,
    `pseudo`

  * `ignore_files`:
    A comma-separated list of globs that should be ignored by the file
    monitor. Default values are:

    `*~`,
    `*#`,
    `.#*`,
    `*.swp`,
    `.*.swx`,
    `SCCS`,
    `.svn`,
    `4913`,
    `.gitignore`

  * `listen_all`:
    This setting tells the server to listen on all available
    interfaces. The default is to only listen on those interfaces
    specified by the bcfg2 setting in the components section of
    `bcfg2.conf`.

  * `plugins`:
    A comma-delimited list of enabled server plugins. Currently
    available plugins are:

    `Account`,
    `Actions`,
    `BB`,
    `Base`,
    `Bundler`,
    `Bzr`,
    `Cfg`,
    `Cvs`,
    `Darcs`,
    `DBStats`,
    `Decisions`,
    `Deps`,
    `Editor`,
    `Fossil`,
    `Git`,
    `GroupPatterns`,
    `Hg`,
    `Hostbase`,
    `Metadata`,
    `NagiosGen`,
    `Ohai`,
    `Packages`,
    `Pkgmgr`,
    `Probes`,
    `Properties`,
    `Rules`,
    `SGenshi`,
    `Snapshots`,
    `SSHbase`,
    `Svn`,
    `Svn2`,
    `TCheetah`,
    `TGenshi`,
    `Trigger`

    Descriptions of each plugin can be found in their respective
    sections below.

  * `prefix`:
    Specifies a prefix if the Bcfg2 installation isn’t placed in the
    default location (e.g. /usr/local).

### Account Plugin

The account plugin manages authentication data, including the following.

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

### BB Plugin

The BB plugin maps users to machines and metadata to machines.

### Base Plugin

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.

### Bundler Plugin

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.

### Bzr Plugin

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.

### Cfg Plugin

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.

### Cvs Plugin (experimental)

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.

### Darcs Plugin (experimental)

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.

### DBStats Plugin

Direct to database statistics plugin.

### Decisions Plugin

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.

### Deps Plugin

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

### Editor Plugin

The Editor plugin attempts to allow you to partially manage
configuration for a file. Its use is not recommended and not well
documented.

### Fossil Plugin

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.

### Git Plugin

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.

### GroupPatterns Plugin

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

### Hg Plugin (experimental)

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.

### Hostbase Plugin

The Hostbase plugin is an IP management system built on top of Bcfg2.

### Metadata Plugin

The Metadata plugin is the primary method of specifying Bcfg2 server
metadata.

### NagiosGen Plugin

NagiosGen is a Bcfg2 plugin that dynamically generates Nagios
configuration files based on Bcfg2 data.

### Ohai Plugin (experimental)

The Ohai plugin is used to detect information about the client operating
system. The data is reported back to the server using JSON.

### Packages Plugin

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.

### Pkgmgr Plugin

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.

### Probes Plugin

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.

### Properties Plugin

The Properties plugin is a connector plugin that adds information from
properties files into client metadata instances.

### Rules Plugin

The Rules plugin provides literal configuration entries that resolve the
abstract configuration entries normally found in the Bundler and Base
plugins. The literal entries in Rules are suitable for consumption by
the appropriate client drivers.

### Snapshots Plugin

The Snapshots plugin stores various aspects of a client’s state when the
client checks in to the server.

### SSHbase Plugin

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.

### Svn Plugin

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.

### Svn2 Plugin

The Svn2 plugin extends on the capabilities in the Svn plugin. It
provides Update and Commit methods which provide hooks for modifying
subversion-backed Bcfg2 repositories.

### TCheetah Plugin

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.

### TGenshi Plugin

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.

### Trigger Plugin

The Trigger plugin provides a method for calling external scripts when
clients are configured.

## CLIENT OPTIONS

These options only affect client functionality, specified in the
`[client]` section.

  * `decision`:
    Specify the server decision list mode (whitelist or blacklist).
    (This settiing will be ignored if the client is called with the -f
    option.)

  * `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.

  * `paranoid`:
    Run the client in paranoid mode.

## COMMUNICATION OPTIONS

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

  * `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.

  * `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.

  * `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.

  * `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.

  * `protocol`:
    Communication protocol to use. Defaults to xmlrpc/ssl.

  * `retries`:
    A client-only option. Number of times to retry network
    communication.

  * `serverCommonNames`:
    A client-only option. A colon-separated list of Common Names the
    client will accept in the SSL certificate presented by the server.

  * `user`:
    A client-only option. The UUID of the client.

## COMPONENT OPTIONS

Specified in the `[components]` section.

  * `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.

    e.g. `bcfg2 = https://10.3.1.6:6789`

  * `encoding`:
    Text encoding of configuration files. Defaults to UTF-8.

## LOGGING OPTIONS

Specified in the `[logging]` section. These options control the server
logging functionality.

  * `path`:
    Server log file path.

## MDATA OPTIONS

These options affect the default metadata settings for Paths with
type=’file’.

  * `owner`:
    Global owner for Paths (defaults to root)

  * `group`:
    Global group for Paths (defaults to root)

  * `perms`:
    Global permissions for Paths (defaults to 644)

  * `paranoid`:
    Global paranoid settings for Paths (defaults to false)

  * `sensitive`:
    Global sensitive settings for Paths (defaults to false)

## PACKAGES OPTIONS

The following options are specified in the `[packages]` section of the
configuration file.

  * `resolver`:
    Enable dependency resolution. Default is 1 (true).

  * `metadata`:
    Enable metadata processing. Default is 1 (true). If metadata is
    disabled, it’s implied that resolver is also disabled.

  * `yum_config`:
    The path at which to generate Yum configs. No default.

  * `apt_config`:
    The path at which to generate APT configs. No default.

  * `gpg_keypath`:
    The path on the client where RPM GPG keys will be copied before they
    are imported on the client. Default is `/etc/pki/rpm-gpg`.

  * `version`:
    Set the version attribute used when binding Packages. Default is
    auto.

The following options are specified in the `[packages:yum]` section of
the configuration file.

  * `use_yum_libraries`:
    By default, Bcfg2 uses an internal implementation of Yum’s
    dependency resolution and other routines so that the Bcfg2 server
    can be run on a host that does not support Yum itself. If you run
    the Bcfg2 server on a machine that does have Yum libraries, however,
    you can enable use of those native libraries in Bcfg2 by setting
    this to 1.

  * `helper`:
    Path to bcfg2-yum-helper. By default, Bcfg2 looks first in $PATH and
    then in `/usr/sbin/bcfg2-yum-helper` for the helper.

  All other options in the `[packages:yum]` section will be passed along
  verbatim to the Yum configuration if you are using the native Yum
  library support.

The following options are specified in the `[packages:pulp]` section of
the configuration file.

  * `username`:
    The username of a Pulp user that will be used to register new
    clients and bind them to repositories.

  * `password`:
    The password of a Pulp user that will be used to register new
    clients and bind them to repositories.

## 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.

  * `path`:
    Custom path for backups created in paranoid mode. The default is in
    `/var/cache/bcfg2`.

  * `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.

## SNAPSHOTS OPTIONS

Specified in the `[snapshots]` section. These options control the server
snapshots functionality.

  * `driver`:
    sqlite

  * `database`:
    The name of the database to use for statistics data.

    eg: `$REPOSITORY_DIR/etc/bcfg2.sqlite`

## SSLCA OPTIONS

These options are necessary to configure the SSLCA plugin and can be
found in the `[sslca_default]` section of the configuration file.

  * `config`:
    Specifies the location of the openssl configuration file for your
    CA.

  * `passphrase`:
    Specifies the passphrase for the CA’s private key (if necessary).
    If no passphrase exists, it is assumed that the private key is
    stored unencrypted.

  * `chaincert`:
    Specifies the location of your ssl chaining certificate. This is
    used when pre-existing certifcate hostfiles are found, so that they
    can be validated and only regenerated if they no longer meet the
    specification. If you’re using a self signing CA this would be the
    CA cert that you generated.

## STATISTICS OPTIONS

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

  * `database_engine`:
    The database engine used by the statistics module. One of the
    following:
    
    `postgresql`,
    `mysql`,
    `sqlite3`,
    `ado_mssql`

  * `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`.

  * `database_user`:
    User for database connections. Not used for sqlite3.

  * `database_password`:
    Password for database connections. Not used for sqlite3.

  * `database_host`:
    Host for database connections. Not used for sqlite3.

  * `database_port`:
    Port for database connections. Not used for sqlite3.

  * `time_zone`:
    Specify a time zone other than that used on the system. (Note that
    this will cause the Bcfg2 server to log messages in this time zone
    as well).

## SEE ALSO

bcfg2(1), bcfg2-server(8)