doc: Add man pages to Sphinx documentation

This allows you to generate our manpages directly from the Sphinx
documentation. This commit is more or less copied directly from the
current man pages.

The goal is to integrate these more closely with the current Sphinx
documentation via include directives to prevent duplication and keep all
documentation consistent.

Signed-off-by: Sol Jerome <sol.jerome@gmail.com>

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)`