From 9a6cae4e5ed2c8615c17d462d5aa5b7828cdb23b Mon Sep 17 00:00:00 2001 From: Sol Jerome Date: Sun, 3 Jun 2012 16:58:00 -0500 Subject: man: Clean up man pages Created new rst files with man page information so that generating man pages is easier and more consistent throughout bcfg2. Signed-off-by: Sol Jerome --- tools/manpagegen/bcfg2-admin.8.ronn | 180 +++++++++ tools/manpagegen/bcfg2-build-reports.8.ronn | 34 ++ tools/manpagegen/bcfg2-info.8.ronn | 110 ++++++ tools/manpagegen/bcfg2-lint.8.ronn | 119 ++++++ tools/manpagegen/bcfg2-lint.conf.5.ronn | 114 ++++++ tools/manpagegen/bcfg2-ping-sweep.8.ronn | 16 + tools/manpagegen/bcfg2-reports.8.ronn | 82 +++++ tools/manpagegen/bcfg2-server.8.ronn | 43 +++ tools/manpagegen/bcfg2.1.ronn | 152 ++++++++ tools/manpagegen/bcfg2.conf.5.ronn | 545 ++++++++++++++++++++++++++++ tools/manpagegen/generate-manpages.bash | 17 + 11 files changed, 1412 insertions(+) create mode 100644 tools/manpagegen/bcfg2-admin.8.ronn create mode 100644 tools/manpagegen/bcfg2-build-reports.8.ronn create mode 100644 tools/manpagegen/bcfg2-info.8.ronn create mode 100644 tools/manpagegen/bcfg2-lint.8.ronn create mode 100644 tools/manpagegen/bcfg2-lint.conf.5.ronn create mode 100644 tools/manpagegen/bcfg2-ping-sweep.8.ronn create mode 100644 tools/manpagegen/bcfg2-reports.8.ronn create mode 100644 tools/manpagegen/bcfg2-server.8.ronn create mode 100644 tools/manpagegen/bcfg2.1.ronn create mode 100644 tools/manpagegen/bcfg2.conf.5.ronn create mode 100644 tools/manpagegen/generate-manpages.bash (limited to 'tools/manpagegen') diff --git a/tools/manpagegen/bcfg2-admin.8.ronn b/tools/manpagegen/bcfg2-admin.8.ronn new file mode 100644 index 000000000..d517bdabc --- /dev/null +++ b/tools/manpagegen/bcfg2-admin.8.ronn @@ -0,0 +1,180 @@ +bcfg2-admin(8) -- Perform repository administration tasks +========================================================= + +## SYNOPSIS + +`bcfg2-admin` [-C ] [] [] + +## DESCRIPTION + +`bcfg2-admin` is used to perform Bcfg2 repository administration + +## OPTIONS + + * `-C` : + Specify alternate bcfg2.conf location + +## MODES + + * `init`: + Initialize a new repository (interactive). + + * `backup`: + Create an archive of the entire Bcfg2 repository. + + * `bundle` : + Display details about the available bundles (See [`BUNDLE + OPTIONS`](###BUNDLE OPTIONS) below). + + * `client` [attribute=value]: + Add, edit, or remove clients entries in metadata (See [`CLIENT + OPTIONS`](###CLIENT OPTIONS) below). + + * `query` [g=group] [p=profile] [-f output-file] [-n] [-c]: + Search for clients based on group or profile (See [`QUERY + OPTIONS`](###QUERY OPTIONS) below). + + * `compare` : + Compare two client configurations. Can be used to verify consistent + behavior between releases. Determine differences between files or + directories (See [`COMPARE OPTIONS`](###COMPARE OPTIONS) below). + + * `minestruct` [-f xml-file] [-g groups]: + Build structure entries based on client statistics extra entries + (See [`MINESTRUCT OPTIONS`](###MINESTRUCT OPTIONS) below). + + * `pull` : + Install configuration information into repo based on client bad + entries (See [`PULL OPTIONS`](###PULL OPTIONS) below). + + * `reports` [init|load_stats|purge|scrub|update]: + Interact with the dynamic reporting system (See [`REPORTS + OPTIONS`](###REPORTS OPTIONS) below). + + * `snapshots` [init|dump|query|reports]: + Interact with the Snapshots database (See [`SNAPSHOTS + OPTIONS`](###SNAPSHOTS OPTIONS) below). + + * `tidy`: + Remove unused files from repository. + + * `viz` [-H] [-b] [-k] [-o png-file]: + Create a graphviz diagram of client, group and bundle information + (See [`VIZ OPTIONS`](###VIZ OPTIONS) below). + +### BUNDLE OPTIONS + + * `mode`: + List all available xml bundles ’list-xml’ or for all available + genshi bundles ’list-genshi’. ’show’ provides an interactive + dialog to get details about the available bundles. + +### CLIENT OPTIONS + + * `mode`: + Add a client ’add’, delete a client ’del’, or ’list’ + all client entries. + + * `client`: + Specify the client’s name. + + * `attribute=value`: + Set attribute values when adding a new client. Allowed attributes + are ’profile’, ’uuid’, ’password’, ’location’, + ’secure’, and ’address’. + +### QUERY OPTIONS + + * `g=group`: + Specify a group to search within. + + * `p=profile`: + Specify a profile to search within. + + * `-f` : + Write the results of the query to a file. + + * `-n`: + Print the results, one on each line. + + * `-c`: + Print the results, separated by commas. + +### COMPARE OPTIONS + + * `old`: + Specify the location of the old configuration file. + + * `new`: + Specify the location of the new configuration file. + +### MINESTRUCT OPTIONS + + * `client`: + Client whose metadata is to be searched for extra entries. + + * `-g` : + Hierarchy of groups in which to place the extra entries in. + + * `-f` : + Specify the xml file in which to write the extra entries. + +### PULL OPTIONS + + * `client`: + Specify the name of the client to search for. + + * `entry type`: + Specify the type of the entry to pull. + + * `entry name`: + Specify the name of the entry to pull. + +### REPORTS OPTIONS + + * `init`: + Initialize the database. + + * `load_stats` [-s] [-c] [-03]: + Load statistics data. + + * `purge` [--client [n]] [--days [n]] [--expired]: + Purge historic and expired data. + + * `scrub`: + Scrub the database for duplicate reasons and orphaned entries. + + * `update`: + Apply any updates to the reporting database. + +### SNAPSHOTS OPTIONS + + * `init`: + Initialize the snapshots database. + + * `query`: + Query the snapshots database. + + * `dump`: + Dump some of the contents of the snapshots database. + + * `reports` [-a] [-b] [-e] [--date=]: + Generate reports for clients in the snapshots database. + +### VIZ OPTIONS + + * `-H`: + Include hosts in diagram. + + * `-b`: + Include bundles in diagram. + + * `-o` : + Write to outfile file instead of stdout. + + * `-k`: + Add a shape/color key. + +## SEE ALSO + +bcfg2-info(8), bcfg2-server(8) diff --git a/tools/manpagegen/bcfg2-build-reports.8.ronn b/tools/manpagegen/bcfg2-build-reports.8.ronn new file mode 100644 index 000000000..43fca5755 --- /dev/null +++ b/tools/manpagegen/bcfg2-build-reports.8.ronn @@ -0,0 +1,34 @@ +bcfg2-build-reports(8) -- Generate state reports for Bcfg2 clients +================================================================== + +## SYNOPSIS + +`bcfg2-build-reports` [<-A>] [<-c>] [<-s>] [<-N>] + +## DESCRIPTION + +`bcfg2-build-reports` is used to build all client state reports. See the +Bcfg2 manual for report setup information. + +## OPTIONS + + * `-A`: + Displays all data. + + * `-c` : + Specify an alternate report configuration path. The default is + repo/etc/reports-configuration.xml. + + * `-h`: + Produce a help message. + + * `-s` : + Use an alternative path for the statistics file. The default is + repo/etc/statistics.xml. + + * `-N`: + No pinging. + +## SEE ALSO + +bcfg2(1), bcfg2-server(8) diff --git a/tools/manpagegen/bcfg2-info.8.ronn b/tools/manpagegen/bcfg2-info.8.ronn new file mode 100644 index 000000000..e19149ca8 --- /dev/null +++ b/tools/manpagegen/bcfg2-info.8.ronn @@ -0,0 +1,110 @@ +bcfg2-info(8) -- Creates a local version of the Bcfg2 server core for state observation +======================================================================================= + +## SYNOPSIS + +`bcfg2-info` [<-C configfile>] [-E ] [-Q ] +[-h] [-p] [-x ] [] [] [] + +## DESCRIPTION + +`bcfg2-info` instantiates an instance of the Bcfg2 core for data +examination and debugging purposes. + +## OPTIONS + + * `-C` : + Specify alternate bcfg2.conf location + + * `-E` : + Specify the encoding of config files. + + * `-Q` : + Specify the server repository path. + + * `-d`: + Run in debug mode. + + * `-h`: + Give a bit of help about the command line arguments and options. + After this bcfg2-info exits. + + * `-p`: + Specify a profile. + + * `-x` : + Set the communication password. + +## MODES + + + * `build` : + Build config for hostname, writing to filename. + + * `buildall` : + Build configs for all clients in directory. + + * `buildallfile` []: + Build config file for all clients in directory. + + * `buildbundle` : + Build bundle for hostname (not written to disk). If filename is a + bundle template, it is rendered. + + * `builddir` : + Build config for hostname, writing separate files to dirname. + + * `buildfile` [--altsrc=] : + Build config file for hostname (not written to disk). + + * `bundles`: + Print out group/bundle information. + + * `clients`: + Print out client/profile information. + + * `config`: + Print out the configuration of the Bcfg2 server. + + * `debug`: + Shell out to native python interpreter. + + * `event_debug`: + Display filesystem events as they are processed. + + * `groups`: + List groups. + + * `help`: + Print the list of available commands. + + * `mappings` [] []: + Print generator mappings for optional type and name. + + * `packageresolve` [...]: + Resolve the specified set of packages. + + * `packagesources` : + Show package sources. + + * `profile` : + Profile a single bcfg2-info command. + + * `quit`: + Exit bcfg2-info command line. + + * `showentries` : + Show abstract configuration entries for a given host. + + * `showclient` : + Show metadata for given hosts. + + * `update`: + Process pending file events. + + * `version`: + Print version of this tool. + +## SEE ALSO + +bcfg2(1), bcfg2-server(8) diff --git a/tools/manpagegen/bcfg2-lint.8.ronn b/tools/manpagegen/bcfg2-lint.8.ronn new file mode 100644 index 000000000..e089bf2e7 --- /dev/null +++ b/tools/manpagegen/bcfg2-lint.8.ronn @@ -0,0 +1,119 @@ +bcfg2-lint(8) -- Check Bcfg2 specification for validity, common mistakes, and style +=================================================================================== + +## SYNOPSIS + +`bcfg2-lint` [] [ [...]] + +## DESCRIPTION + +`bcfg2-lint` checks the Bcfg2 specification for schema validity, common +mistakes, and other criteria. It can be quite helpful in finding typos +or malformed data. + +`bcfg2-lint` exits with a return value of 2 if errors were found, and 3 +if warnings (but no errors) were found. Any other non-0 exit value +denotes some failure in the script itself. + +`bcfg2-lint` is a rewrite of the older bcfg2-repo-validate tool. + +## OPTIONS + + * `-C` : + Specify alternate bcfg2.conf location. + + * `-Q`: + Specify the server repository path. + + * `-v`: + Be verbose. + + * `--lint-config`: + Specify path to bcfg2-lint.conf (default `/etc/bcfg2-lint.conf`). + + * `--stdin`: + Rather than operating on all files in the Bcfg2 specification, only + validate a list of files supplied on stdin. This mode is + particularly useful in pre-commit hooks. + + This makes a few assumptions: + + Metadata files will only be checked if a valid chain of XIncludes + can be followed all the way from clients.xml or groups.xml. Since + there are multiple formats of metadata stored in Metadata/ (i.e., + clients and groups), there is no way to determine which sort of + data a file contains unless there is a valid chain of XIncludes. + It may be useful to always specify all metadata files should be + checked, even if not all of them have changed. + + Property files will only be validated if both the property file + itself and its matching schema are included on stdin. + + * `require-schema`: + Require property files to have matching schema files. + +## PLUGINS + +See `bcfg2-lint.conf`(5) for more information on the configuration of +the plugins listed below. + + * `Bundles`: + Check the specification for several issues with Bundler: bundles + referenced in metadata but not found in `Bundler/`; bundles whose + *name* attribute does not match the filename; and Genshi template + bundles that use the ** tag (which is not processed in + templated bundles). + + * `Comments`: + Check the specification for VCS keywords and any comments that are + required. By default, this only checks that the *$Id$* keyword is + included and expanded in all files. You may specify VCS keywords to + check and comments to be required in the config file. (For instance, + you might require that every file have a "Maintainer" comment.) + + In XML files, only comments are checked for the keywords and + comments required. + + * `Duplicates`: + Check for several types of duplicates in the Metadata: duplicate + groups; duplicate clients; and multiple default groups. + + * `InfoXML`: + Check that certain attributes are specified in `info.xml` files. By + default, requires that *owner*, *group*, and *perms* are specified. + Can also require that an `info.xml` exists for all Cfg files, and + that paranoid mode be enabled for all files. + + * `MergeFiles`: + Suggest that similar probes and config files be merged into single + probes or TGenshi templates. + + * `Pkgmgr`: + Check for duplicate packages specified in Pkgmgr. + + * `RequiredAttrs`: + Check that all *Path* and *BoundPath* tags have the attributes that + are required by their type (e.g., a path of type symlink must have + name and to specified to be valid). This sort of validation is + beyond the scope of an XML schema. + + * `Validate`: + Validate the Bcfg2 specification against the XML schemas. + + Property files are freeform XML, but if a `.xsd` file with a + matching filename is provided, then schema validation will be + performed on property files individually as well. For instance, if + you have a property file named `ntp.xml` then by placing a schema + for that file in `ntp.xsd` schema validation will be performed on + `ntp.xml`. + +## BUGS + +`bcfg2-lint` may not handle some older plugins as well as it handles +newer ones. For instance, there may be some places where it expects all +of your configuration files to be handled by Cfg rather than by a mix of +Cfg and TGenshi or TCheetah. + +## SEE ALSO + +bcfg2(1), bcfg2-server(8), bcfg2-lint.conf(5) diff --git a/tools/manpagegen/bcfg2-lint.conf.5.ronn b/tools/manpagegen/bcfg2-lint.conf.5.ronn new file mode 100644 index 000000000..657ea6e74 --- /dev/null +++ b/tools/manpagegen/bcfg2-lint.conf.5.ronn @@ -0,0 +1,114 @@ +bcfg2-lint.conf(5) -- configuration parameters for bcfg2-lint +============================================================= + +## DESCRIPTION + +`bcfg2-lint.conf` includes configuration parameters for `bcfg2-lint`. + +## 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. + +The file consists of one `[lint]` section, up to one `[errors]` section, +and then any number of plugin-specific sections, documented below. +(Note that this makes it quite feasible to combine your +`bcfg2-lint.conf` into your `bcfg2.conf`(5) file, if you so desire). + +## GLOBAL OPTIONS + +These options apply to `bcfg2-lint` generally, and must be in the +`[lint]` section. + + * `plugins`: + A comma-delimited list of plugins to run. By default, all plugins + are run. This can be overridden by listing plugins on the command + line. See `bcfg2-lint`(8) for a list of the available plugins. + +## ERROR HANDLING + +Error handling is configured in the `[errors]` section. Each option +should be the name of an error and one of *error*, *warning*, or +*silent*, which tells `bcfg2-lint`(8) how to handle the warning. Error +names and their defaults can be displayed by running `bcfg2-lint`(8) +with the `--list-errors` option. + +## PLUGIN OPTIONS + +These options apply only to a single plugin. Each option should be in a +section named for its plugin; for instance, options for the InfoXML +plugin would be in a section called `[InfoXML]`. + +If a plugin is not listed below, then it has no configuration. + +In many cases, the behavior of a plugin can be configured by modifying +how errors from it are handled. See [`ERROR HANDLING`](### ERROR +HANDLING), above. + +### Comments + +The `Comments` plugin configuration specifies which VCS keywords and +comments are required for which file types. The valid types of file are +*global* (all file types), *bundler* (non-templated bundle files), +*sgenshi* (templated bundle files), *properties* (property files), *cfg* +(non-templated Cfg files), *tgenshi* (templated Cfg files), *infoxml* +(info.xml files), and *probe* (probe files). + +The specific types (i.e., types other than "global") all supplement +global; they do not override it. The exception is if you specify an +empty option, e.g.: + + cfg_keywords = + +By default, the *$Id$* keyword is checked for and nothing else. + +Multiple keywords or comments should be comma-delimited. + +· `_keywords` + +Ensure that files of the specified type have the given VCS keyword. Do +*not* include the dollar signs. I.e.: + + infoxml_keywords = Revision + +*not*: + + infoxml_keywords = $Revision$ + +`· _comments` + +Ensure that files of the specified type have a comment containing the +given string. In XML files, only comments are checked. In plain text +files, all lines are checked since comment characters may vary. + +### InfoXML + + * `required_attrs`: + A comma-delimited list of attributes to require on `` tags. + Default is "owner,group,perms". + +### MergeFiles + + * `threshold`: + The threshold at which MergeFiles will suggest merging config files + and probes. Default is 75% similar. + +### Validate + + * `schema`: + The full path to the XML Schema files. Default is + `/usr/share/bcfg2/schema`. This can be overridden with the + *--schema* command-line option + +## SEE ALSO + +bcfg2-lint(8) diff --git a/tools/manpagegen/bcfg2-ping-sweep.8.ronn b/tools/manpagegen/bcfg2-ping-sweep.8.ronn new file mode 100644 index 000000000..815e0af5b --- /dev/null +++ b/tools/manpagegen/bcfg2-ping-sweep.8.ronn @@ -0,0 +1,16 @@ +bcfg2-ping-sweep(8) -- Update pingable and pingtime attributes in clients.xml +============================================================================= + +## SYNOPSIS + +`bcfg2-ping-sweep` + +## DESCRIPTION + +`bcfg2-ping-sweep` traverses the list of clients in Metadata/clients.xml +and updates their pingable/pingtime attributes. The pingtime value is +set to the last time the client was pinged (not the RTT value). + +## SEE ALSO + +bcfg2(1), bcfg2-server(8) diff --git a/tools/manpagegen/bcfg2-reports.8.ronn b/tools/manpagegen/bcfg2-reports.8.ronn new file mode 100644 index 000000000..1cb999dc7 --- /dev/null +++ b/tools/manpagegen/bcfg2-reports.8.ronn @@ -0,0 +1,82 @@ +bcfg2-reports(8) -- Query reporting system for client status +============================================================ + +## SYNOPSIS + +`bcfg2-reports` [-a] [-b ] [-c] [-d] [-e ] [-h] [-m ] +[-s ] [-x ] [--badentry=] +[--extraentry=] [--fields=] +[--modifiedentry=] [--sort=] [--stale] [-v] + +## DESCRIPTION + +`bcfg2-reports` allows you to retrieve data from the database about +clients, and the states of their current interactions. It also allows +you to change the expired/unexpired states. The utility runs as a +standalone application. It does, however, use the models from +`/src/lib/Server/Reports/reports/models.py`. + +## OPTIONS + + * `-a`: + Specify alternate bcfg2.conf location + + * `-b` : + Single host mode - shows bad entries from the current interaction of + *hostname*. + + * `-c`: + Shows only clean hosts. + + * `-d`: + Shows only dirty hosts. + + * `-e` : + Single host mode - shows extra entries from the current interaction + of *hostname*. + + * `-h`: + Shows help and usage info about `bcfg2-reports`. + + * `-m` : + Single host mode - shows modified entries from the current + interaction of *hostname*. + + * `-s` : + Single host mode - shows bad, modified, and extra entries from the + current interaction of *hostname*. + + * `-x` : + Toggles expired/unexpired state of *hostname*. + + * `--badentry=`: + Shows only hosts whose current interaction has bad entries of type + *entry type* and name *entry name*. If a single argument ARG1 is + given, then *entry type*,*entry name* pairs will be read from a file + of name ARG1. + + * `--extraentry=`: + Shows only hosts whose current interaction has extra entries of type + *entry type* and name *entry name*. If a single argument ARG1 is + given, then *entry type*,*entry name* pairs will be read from a file + of name ARG1. + + * `--fields=`: + Only displays the fields *ARG1,ARG2,...* (name, time, state, total, + good, bad). + + * `--modifiedentry=`: + Shows only hosts whose current interaction has modified entries of + type *entry type* and name *entry name*. If a single argument ARG1 + is given, then *entry type*,*entry name* pairs will be read from a + file of name ARG1. + + * `--sort=`: + Sorts output on ARG1,ARG2,... (name, time, state, total, good, bad). + + * `--stale`: + Shows hosts which haven’t run in the last 24 hours. + +## SEE ALSO + +bcfg2(1), bcfg2-server(8) diff --git a/tools/manpagegen/bcfg2-server.8.ronn b/tools/manpagegen/bcfg2-server.8.ronn new file mode 100644 index 000000000..c306fa6a4 --- /dev/null +++ b/tools/manpagegen/bcfg2-server.8.ronn @@ -0,0 +1,43 @@ +bcfg2-server(8) -- Server for client configuration specifications +================================================================= + +## SYNOPSIS + +`bcfg2-server` [-d] [-v] [-C ] [-D ] [-E +] [-Q ] [-S ] [-o ] [-x +] [--ssl-key=] + +## DESCRIPTION + +`bcfg2-server` is the daemon component of Bcfg2 which serves +configurations to clients based on the data in its repository. + +## OPTIONS + + * `-C` : + Specify alternate bcfg2.conf location. + + * `-D` : + Daemonize, placing the program pid in the specified pidfile. + + * `-E` : + Specify alternate encoding (default is UTF-8). + + * `-Q` : + Set repository path. + + * `-S` : + Set server address. + + * `-d`: + Run `bcfg2-server` in debug mode. + + * `-v`: + Run `bcfg2-server` in verbose mode. + + * `--ssl-key=`: + Set path to SSL key. + +## SEE ALSO + +bcfg2(1), bcfg2-lint(8) diff --git a/tools/manpagegen/bcfg2.1.ronn b/tools/manpagegen/bcfg2.1.ronn new file mode 100644 index 000000000..c801c833d --- /dev/null +++ b/tools/manpagegen/bcfg2.1.ronn @@ -0,0 +1,152 @@ +bcfg2(1) -- Bcfg2 client tool +============================= + +## SYNOPSIS + +`bcfg2` [_options_][_..._] + +## DESCRIPTION + +`bcfg2` runs the Bcfg2 configuration process on the current host. This +process consists of the following steps. + +* Fetch and execute probes +* Upload probe results +* Fetch the client configuration +* Check the current client state +* Attempt to install the desired configuration +* Upload statistics about the Bcfg2 execution and client state + +## OPTIONS + + * `-C` : + Specify alternate bcfg2.conf location + + * `-D` [,]: + Specify a set of Bcfg2 tool drivers. + + *NOTE: only drivers listed will be loaded. (e.g., if you do not + include POSIX, you will be unable to verify/install Path entries).* + + * `-E` : + Specify the encoding of Cfg files. + + * `-I`: + Run bcfg2 in interactive mode. The user will be prompted before + each change. + + * `-O`: + Omit lock check + + * `-P`: + Run bcfg2 in paranoid mode. Diffs will be logged for configuration + files marked as paranoid by the Bcfg2 server. + + * `-R` : + Specify the number of times that the client will attempt to retry + network communication. + + * `-S` : + Manually specify the server location (as opposed to using the value + in bcfg2.conf). + + * `-b` [_bundle1:bundle2_]: + Run bcfg2 against one or multiple bundles in the configuration. + + * `-c` : + Cache a copy of the configuration in cachefile. + + * `--ca-cert=`: + Specifiy the path to the SSL CA certificate. + + * `-d`: + Run bcfg2 in debug mode. + + * `-e`: + When in verbose mode, display extra entry information (temporary + until verbosity rework). + + * `-f` : + Configure from a file rather than querying the server. + + * `-h`: + Print Usage information. + + * `-k`: + Run in bulletproof mode. This currently only affects behavior in + the debian toolset; it calls apt-get update and clean and dpkg + --configure --pending. + + * `-l` : + Run the client in the server decision list mode (unless "none" + is specified, which can be done in order to override the decision + list mode specified in bcfg2.conf). This approach is needed when + particular changes are deemed "high risk". It gives the ability to + centrally specify these changes, but only install them on clients + when administrator supervision is available. Because collaborative + configuration is one of the remaining hard issues in configuration + management, these issues typically crop up in environments with + several administrators and much configuration variety. (This setting + will be ignored if the -f option is also specified). + + * `-n`: + Run bcfg2 in dry-run mode. No changes will be made to the system. + + * `-o` : + Writes a log to the specified path. + + * `-p` : + Assert a profile for the current client. + + * `-q`: + Run bcfg2 in quick mode. Package checksum verification won’t be + performed. This mode relaxes the constraints of correctness, and + thus should only be used in safe conditions. + + * `-Q`: + Run bcfg2 in "bundle quick" mode, where only entries in a bundle are + verified or installed. This runs much faster than -q, but doesn’t + provide statistics to the server at all. In order for this option to + work, the -b option must also be provided. This option is incompatible + with -r. + + * `-r` : + Cause bcfg2 to remove extra configuration elements it detects. Mode is + one of all, Services, or Packages. All removes all entries. Likewise, + Services and Packages remove only the extra configuration elements + of the respective type. + + * `-s` : + Set bcfg2 interaction level for services. Default behavior is to + modify all services affected by reconfiguration. build mode attempts + to stop all services started. disabled suppresses all attempts to + modify services + + * `--ssl-cert=`: + Specifiy the path to the SSL certificate. + + * `--ssl-cns=`[_CN1:CN2_]: + List of acceptable SSL server Common Names. + + * `--ssl-key=`: + Specifiy the path to the SSL key. + + * `-u` : + Attempt to authenticate as ’user’. + + * `-x` : + Use ’password’ for client communication. + + * `-t` : + Set the timeout (in seconds) for client communication. Default is + 90 seconds. + + * `-v`: + Run bcfg2 in verbose mode. + + * `-z`: + Only configure independent entries, ignore bundles. + +## SEE ALSO + +bcfg2-server(8), bcfg2-info(8) diff --git a/tools/manpagegen/bcfg2.conf.5.ronn b/tools/manpagegen/bcfg2.conf.5.ronn new file mode 100644 index 000000000..e71bdb73a --- /dev/null +++ b/tools/manpagegen/bcfg2.conf.5.ronn @@ -0,0 +1,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) diff --git a/tools/manpagegen/generate-manpages.bash b/tools/manpagegen/generate-manpages.bash new file mode 100644 index 000000000..62006c953 --- /dev/null +++ b/tools/manpagegen/generate-manpages.bash @@ -0,0 +1,17 @@ +#!/bin/bash + +# This makes building our manpages easier and more consistent. More +# information about the tool used to do this can be found at: +# +# https://github.com/rtomayko/ronn + +if [ ! -d man -o ! -d tools ] +then + echo "Must be in the top-level bcfg2 source directory" + exit 1 +fi + +for f in $(ls man) +do + ronn -r --pipe tools/manpagegen/${f}.ronn | grep -iv ronn > man/${f} +done -- cgit v1.2.3-1-g7c22