path: root/doc/man/bcfg2.conf.txt

.. -*- mode: rst -*-
.. 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
	pseudo

fam_blocking
    Whether the server should block at startup until the file monitor
    backend has processed all events. This can cause a slower startup,
    but ensure that all files are recognized before the first client
    is handled. Defaults to True.

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::

        ACL
	Bundler
	Bzr
	Cfg
	Cvs
	Darcs
	Decisions
        Defaults
	Deps
	FileProbes
	Fossil
	Git
        GroupLogic
	GroupPatterns
	Guppy
	Hg
	Ldap
	Metadata
	NagiosGen
	Ohai
	Packages
	Pkgmgr
	POSIXCompat
	Probes
	Properties
	PuppetENC
	Reporting
	Rules
	SEModules
	ServiceCompat
	SSHbase
	Svn
	TemplateHelper
	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.

umask
    The umask to set for the server.  Default is *0077*.

Server Plugins
--------------

This section has a listing of all the plugins currently provided with
Bcfg2.

ACL Plugin
++++++++++

The ACL plugin controls which hosts can make which XML-RPC calls.

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
++++++++++

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
++++++++++++

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.

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.)"

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.

GroupLogic Plugin
+++++++++++++++++

The GroupLogic plugin lets you flexibly assign group membership with a
Genshi template.

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
+++++++++

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.

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
+++++++++++

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

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.

Trigger Plugin
++++++++++++++

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

Caching options
---------------

These options are specified in the **[caching]** section.

    client_metadata
        The following four caching modes are available for client
        metadata:

        * off: No caching of client metadata objects is performed. This
          is the default.
        * initial: Only initial metadata objects are cached. Initial
          metadata objects are created only from the data in the
          Metadata plugin, before additional groups from other plugins
          are merged in.
        * cautious: Final metadata objects are cached, but each client’s
          cache is cleared at the start of each client run, immediately
          after probe data is received. Cache is also cleared as in
          aggressive mode. *on* is a synonym for cautious.
        * aggressive: Final metadata objects are cached. Each plugin is
          responsible for clearing cache when appropriate.

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/tlsv1.

    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.

    backends
        Comma separated list of backends for the dependency resolution.
        Default is "Yum,Apt,Pac,Pkgng".

    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.

SSL CA options
--------------

These options are necessary to configure the SSL CA feature of the Cfg
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 server plugins. One of the
        following::

            postgresql
            mysql
            sqlite3
            ado_mssql

    name
        The name of the database to use for server data. If
        'database_engine' is set to 'sqlite3' this is a file path to
        the sqlite file and defaults to ``$REPOSITORY_DIR/etc/bcfg2.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.

    options
        Various options for the database connection. The value expected
        is the literal value of the django OPTIONS setting.

    reporting_engine
        The database engine used by the Reporting plugin. One of the
        following::

            postgresql
            mysql
            sqlite3
            ado_mssql

         If reporting_engine is not specified, the Reporting plugin uses
         the same database as the other server plugins.

    reporting_name
        The name of the database to use for reporting data. If
        'database_engine' is set to 'sqlite3' this is a file path to
        the sqlite file and defaults to 
        ``$REPOSITORY_DIR/etc/reporting.sqlite``.

    reporting_user
        User for reporting database connections. Not used for sqlite3.

    reporting_password
        Password for reporting database connections. Not used for sqlite3.

    reporting_host
        Host for reporting database connections. Not used for sqlite3.

    reporting_port
        Port for reporting database connections. Not used for sqlite3.

    reporting_options
        Various options for the database connection. The value expected
        is the literal value of the django OPTIONS setting.

Reporting options
-----------------

    config
        Specifies the location of the reporting configuration (default
        is /etc/bcfg2-web.conf.

    time_zone
        Specifies 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).

    web_debug
        Turn on Django debugging.

    max_children
        Maximum number of children for the reporting collector. Use 0 to
        disable the limit. (default is 0)

See Also
--------

:manpage:`bcfg2(1)`, :manpage:`bcfg2-server(8)`