diff options
Diffstat (limited to 'doc/man/bcfg2.conf.txt')
| -rw-r--r-- | doc/man/bcfg2.conf.txt | 714 |
1 files changed, 714 insertions, 0 deletions
diff --git a/doc/man/bcfg2.conf.txt b/doc/man/bcfg2.conf.txt new file mode 100644 index 000000000..1c085e0c5 --- /dev/null +++ b/doc/man/bcfg2.conf.txt @@ -0,0 +1,714 @@ +.. vim: ft=rst + +bcfg2.conf +========== + +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 + *.swpx + *.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 + Base + Bundler + Bzr + Cfg + Cvs + Darcs + DBStats + Decisions + Deps + Editor + FileProbes + Fossil + Git + GroupPatterns + Guppy + Hg + Hostbase + Ldap + Metadata + NagiosGen + Ohai + Packages + Pkgmgr + POSIXCompat + Probes + Properties + PuppetENC + Reporting + Rules + SEModules + ServiceCompat + Snapshots + SSHbase + SSLCA + Statistics + Svn + TCheetah + TemplateHelper + 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`). + +backend + Specifies which server core backend to use. Current available + options are:: + + cherrypy + builtin + best + + The default is *best*, which is currently an alias for *builtin*. + More details on the backends can be found in the official + documentation. + +user + The username or UID to run the daemon as. Default is *0*. + +group + The group name or GID to run the daemon as. Default is *0*. + +vcs_root + Specifies the path to the root of the VCS working copy that holds + your Bcfg2 specification, if it is different from *repository*. + E.g., if the VCS repository does not hold the bcfg2 data at the top + level, you may need to set this option. + +Server Plugins +-------------- + +This section has a listing of all the plugins currently provided with +Bcfg2. + +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` + +Base Plugin ++++++++++++ + +The Base plugin is 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 +++++++++++++++ + +The Bundler plugin 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. + +Defaults Plugin ++++++++++++++++ + +The Defaults plugin can be used to populate default attributes for +entries. Defaults is *not* a Generator plugin, so it does not actually +bind an entry; Defaults are applied after an entry has been bound, +and only populate attributes that are not yet set. + +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. + +FileProbes Plugin ++++++++++++++++++ + +The FileProbes plugin allows you to probe a client for a file, which is +then added to the Cfg specification. If the file changes on the client, +FileProbes can either update it in the specification or allow Cfg to +replace it. + +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. + +Guppy Plugin +++++++++++++ + +The Guppy plugin is used to trace memory leaks within the bcfg2-server +process using Guppy. + +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. + +Ldap Plugin ++++++++++++ + +The Ldap plugin makes it possible to fetch data from an LDAP directory, +process it and attach it to your metadata. + +Metadata Plugin ++++++++++++++++ + +The Metadata plugin is the primary method of specifying Bcfg2 server +metadata. + +NagiosGen Plugin +++++++++++++++++ + +The NagiosGen plugin 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. + +POSIXCompat Plugin +++++++++++++++++++ + +The POSIXCompat plugin provides a compatibility layer for 1.3 POSIX +Entries so that they are compatible with older clients. + +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. + +PuppetENC Plugin +++++++++++++++++ + +The PuppetENC plugin is a connector plugin that adds support for Puppet +External Node Classifiers. + +Reporting Plugin +++++++++++++++++ + +The Reporting plugin enables the collection of data for use with Bcfg2's +dynamic reporting system. + +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. + +SEModules Plugin +++++++++++++++++ + +The SEModules plugin provides a way to distribute SELinux modules via +Bcfg2. + +ServiceCompat Plugin +++++++++++++++++++++ + +The ServiceCompat plugin converts service entries for older clients. + +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. + +SSLCA Plugin +++++++++++++ + +The SSLCA plugin is designed to handle creation of SSL privatekeys and +certificates on request. + +Statistics +++++++++++ + +The Statistics plugin is deprecated (see Reporting). + +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. + +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. They can be 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. + + profile + Assert the given profile for the host. + +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. Default is 3 retries. + + retry_delay + A client-only option. Number of seconds to wait in between + retrying network communication. Default is 1 second. + + serverCommonNames + A client-only option. A colon-separated list of Common Names the + client will accept in the SSL certificate presented by the server. + + timeout + A client-only option. The network communication timeout. + + 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. + + lockfile + The path to the client lock file, which is used to ensure that + only one Bcfg2 client runs at a time on a single client. + +Logging options +--------------- + +Specified in the **[logging]** section. These options control the server +logging functionality. + + debug + Whether or not to enable debug-level log output. Default is false. + + path + Server log file path. + + syslog + Whether or not to send logging data to syslog. Default is true. + + verbose + Whether or not to enable verbose log output. Default is false. + +MDATA options +------------- + +Specified in the **[mdata]** section. 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) + + mode + Global permissions for Paths (defaults to 644) + + secontext + Global SELinux context for Path entries (defaults to + *__default__*, which restores the expected context) + + paranoid + Global paranoid settings for Paths (defaults to false) + + sensitive + Global sensitive settings for Paths (defaults to false) + + important + Global important settings for Paths. Defaults to false. + +Packages options +---------------- + +The following options are specified in the **[packages]** section. + + 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. + + 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. + +The following options are specified in the **[packages:pulp]** section. + + 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. + +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. + +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. + + e.g.: `$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. + +Database options +---------------- + +Server-only, specified in the **[database]** section. These options +control the database connection of the server. + + engine + The database engine used by the statistics module. One of the + following:: + + postgresql + mysql + sqlite3 + ado_mssql + + name + The name of the database to use for statistics data. If + 'database_engine' is set to 'sqlite3' this is a file path to + the sqlite file and defaults to `$REPOSITORY_DIR/etc/brpt.sqlite`. + + user + User for database connections. Not used for sqlite3. + + password + Password for database connections. Not used for sqlite3. + + host + Host for database connections. Not used for sqlite3. + + 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 +-------- + +:manpage:`bcfg2(1)`, :manpage:`bcfg2-server(8)` |