From db60e20ca7a328509da99862a1634639dd45cf5d Mon Sep 17 00:00:00 2001 From: Sol Jerome Date: Wed, 7 Nov 2012 13:05:47 -0600 Subject: man: Migrate generate-manpages.bash to sphinx Signed-off-by: Sol Jerome --- tools/generate-manpages.bash | 11 + tools/manpagegen/bcfg2-admin.8.ronn | 220 ---------- tools/manpagegen/bcfg2-build-reports.8.ronn | 34 -- tools/manpagegen/bcfg2-crypt.8.ronn | 116 ------ 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-reports.8.ronn | 82 ---- tools/manpagegen/bcfg2-server.8.ronn | 43 -- tools/manpagegen/bcfg2.1.ronn | 158 -------- tools/manpagegen/bcfg2.conf.5.ronn | 596 ---------------------------- tools/manpagegen/generate-manpages.bash | 17 - 12 files changed, 11 insertions(+), 1609 deletions(-) create mode 100644 tools/generate-manpages.bash delete mode 100644 tools/manpagegen/bcfg2-admin.8.ronn delete mode 100644 tools/manpagegen/bcfg2-build-reports.8.ronn delete mode 100644 tools/manpagegen/bcfg2-crypt.8.ronn delete mode 100644 tools/manpagegen/bcfg2-info.8.ronn delete mode 100644 tools/manpagegen/bcfg2-lint.8.ronn delete mode 100644 tools/manpagegen/bcfg2-lint.conf.5.ronn delete mode 100644 tools/manpagegen/bcfg2-reports.8.ronn delete mode 100644 tools/manpagegen/bcfg2-server.8.ronn delete mode 100644 tools/manpagegen/bcfg2.1.ronn delete mode 100644 tools/manpagegen/bcfg2.conf.5.ronn delete mode 100644 tools/manpagegen/generate-manpages.bash (limited to 'tools') diff --git a/tools/generate-manpages.bash b/tools/generate-manpages.bash new file mode 100644 index 000000000..0bc13123d --- /dev/null +++ b/tools/generate-manpages.bash @@ -0,0 +1,11 @@ +#!/bin/bash + +# This makes building our manpages easier and more consistent. + +if [ ! -d man -o ! -d tools -o ! -d doc ] +then + echo "Must be in the top-level bcfg2 source directory" + exit 1 +fi + +sphinx-build -b man -D copyright="" doc man diff --git a/tools/manpagegen/bcfg2-admin.8.ronn b/tools/manpagegen/bcfg2-admin.8.ronn deleted file mode 100644 index f90865d9c..000000000 --- a/tools/manpagegen/bcfg2-admin.8.ronn +++ /dev/null @@ -1,220 +0,0 @@ -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. - - * `-E` : - Specify the encoding of Cfg files. - - * `-Q` : - Specify the path to the server repository. - - * `-S` : - Manually specify the server location (as opposed to using the value - in bcfg2.conf). - - * `-d`: - Enable debugging output. - - * `-h`: - Print Usage information. - - * `-o` : - Writes a log to the specified path. - - * `-v`: - Enable verbose output. - - * `-x` : - Use ’password’ for client communication. - - * `--ssl-key=`: - Specifiy the path to the SSL key. - -## MODES - - * `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). - - * `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). - - * `init`: - Initialize a new repository (interactive). - - * `minestruct` [-f xml-file] [-g groups]: - Build structure entries based on client statistics extra entries - (See [`MINESTRUCT OPTIONS`](###MINESTRUCT OPTIONS) below). - - * `perf`: - Query server for performance data. - - * `pull` : - Install configuration information into repo based on client bad - entries (See [`PULL OPTIONS`](###PULL 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). - - * `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). - - * `syncdb`: - Sync the Django ORM with the configured database. - - * `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). - - * `xcmd`: - Provides a XML-RPC Command Interface to the bcfg2-server. - -### 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 - - * `b=bundle`: - Specify a bundle to search for within client metadata. - - * `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 deleted file mode 100644 index 43fca5755..000000000 --- a/tools/manpagegen/bcfg2-build-reports.8.ronn +++ /dev/null @@ -1,34 +0,0 @@ -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-crypt.8.ronn b/tools/manpagegen/bcfg2-crypt.8.ronn deleted file mode 100644 index 64077ec3b..000000000 --- a/tools/manpagegen/bcfg2-crypt.8.ronn +++ /dev/null @@ -1,116 +0,0 @@ -bcfg2-crypt(8) -- Bcfg2 encryption and decryption utility -========================================================= - -## SYNOPSIS - -`bcfg2-crypt` [<-C configfile>] [--decrypt|--encrypt] [--cfg|--properties] [--stdout] [--remove] [--xpath ] [-p ] [-v] [-I] [...] - -## DESCRIPTION - -`bcfg2-crypt` performs encryption and decryption of Cfg and Properties -files. It's often sufficient to run `bcfg2-crypt` with only the name -of the file you wish to encrypt or decrypt; it can usually figure out -what to do. - -## OPTIONS - - * `-C` : - Specify alternate bcfg2.conf location - - * `--decrypt`, `--encrypt`: - Specify which operation you'd like to perform. `bcfg2-crypt` can - usually determine which is necessary based on the contents of each - file. - - * `--cfg`: - Tell `bcfg2-crypt` that an XML file should be encrypted in its - entirety rather than element-by-element. This is only necessary - if the file is an XML file whose name ends with `.xml` and whose - top-level tag is ``. See [MODES] below for details. - - * `--properties`: - Tell `bcfg2-crypt` to process a file as an XML Properties file, - and encrypt the text of each element separately. This is - necessary if, for example, you've used a different top-level tag - than `` in your Properties files. See [MODES] below - for details. - - * `--stdout`: - Print the resulting file to stdout instead of writing it to a - file. - - * `--remove`: - Remove the plaintext file after it has been encrypted. Only - meaningful for Cfg files. - - * `--xpath `: - Encrypt the character content of all elements that match the - specified XPath expression. The default is `*[@encrypted]` - or `*`; see [MODES] below for more details. Only meaningful for - Properties files. - - * `-p `: - Specify the name of a passphrase specified in the `[encryption]` - section of `bcfg2.conf`. See [SELECTING PASSPHRASE] below for - more details. - - * `-v`: - Be verbose. - - * `-I`: - When encrypting a Properties file, interactively select the - elements whose data should be encrypted. - - * `-h`: - Display help and exit. - -## MODES - -`bcfg2-crypt` can encrypt Cfg files or Properties files; they are -handled very differently. - - * Cfg: - When `bcfg2-crypt` is used on a Cfg file, the entire file is - encrypted. This is the default behavior on files that are not - XML, or that are XML but whose top-level tag is not - ``. This can be enforced by use of the `--cfg` - option. - - * Properties: - When `bcfg2-crypt` is used on a Properties file, it encrypts the - character content of elements matching the XPath expression given - by `--xpath`. By default the expression is `*[@encrypted]`, which - matches all elements with an `encrypted` attribute. If you are - encrypting a file and that expression doesn't match any elements, - then the default is `*`, which matches everything. When - `bcfg2-crypt` encrypts the character content of an element, it - also adds the `encrypted` attribute, set to the name of the - passphrase used to encrypt that element. When it decrypts an - element it does not remove `encrypted`, though; this lets you - easily and efficiently run `bcfg2-crypt` against a single - Properties file to encrypt and decrypt it without needing to - specify a long list of options. See the online Bcfg2 docs on - Properties files for more information on how this works. - -## SELECTING PASSPHRASE - -The passphrase used to encrypt or decrypt a file is discovered in the -following order: - - * First, the passphrase given on the command line using `-p` is - used. - - * Next, if exactly one passphrase is specified in `bcfg2.conf`, it - will be used. - - * Next, if operating in Properties mode, `bcfg2-crypt` will attempt - to read the name of the passphrase from the encrypted elements. - - * Next, if decrypting, all passphrases will be tried sequentially. - - * If no passphrase has been determined at this point, an error is - produced and the file being encrypted or decrypted is skipped. - -## SEE ALSO - -bcfg2-server(8) diff --git a/tools/manpagegen/bcfg2-info.8.ronn b/tools/manpagegen/bcfg2-info.8.ronn deleted file mode 100644 index e19149ca8..000000000 --- a/tools/manpagegen/bcfg2-info.8.ronn +++ /dev/null @@ -1,110 +0,0 @@ -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 deleted file mode 100644 index f3c9771e8..000000000 --- a/tools/manpagegen/bcfg2-lint.8.ronn +++ /dev/null @@ -1,119 +0,0 @@ -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 *mode* 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 deleted file mode 100644 index 60266d9b2..000000000 --- a/tools/manpagegen/bcfg2-lint.conf.5.ronn +++ /dev/null @@ -1,114 +0,0 @@ -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), -*genshibundler* (templated bundle files), *properties* (property files), -*cfg* (non-templated Cfg files), *genshi* or *cheetah* (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,mode". - -### 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-reports.8.ronn b/tools/manpagegen/bcfg2-reports.8.ronn deleted file mode 100644 index 1cb999dc7..000000000 --- a/tools/manpagegen/bcfg2-reports.8.ronn +++ /dev/null @@ -1,82 +0,0 @@ -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 deleted file mode 100644 index c306fa6a4..000000000 --- a/tools/manpagegen/bcfg2-server.8.ronn +++ /dev/null @@ -1,43 +0,0 @@ -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 deleted file mode 100644 index 8b3ea1e60..000000000 --- a/tools/manpagegen/bcfg2.1.ronn +++ /dev/null @@ -1,158 +0,0 @@ -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 - - * `-B`: - Configure everything except the given bundle(s). - - * `-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). - - * `-Z`: - Do not configure independent entries. - - * `-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 deleted file mode 100644 index f0359d0d3..000000000 --- a/tools/manpagegen/bcfg2.conf.5.ronn +++ /dev/null @@ -1,596 +0,0 @@ -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`, - `Base`, - `Bundler`, - `Bzr`, - `Cfg`, - `Cvs`, - `Darcs`, - `DBStats`, - `Decisions`, - `Deps`, - `Editor`, - `Fossil`, - `Git`, - `GroupPatterns`, - `Hg`, - `Hostbase`, - `Metadata`, - `NagiosGen`, - `Ohai`, - `Packages`, - `Pkgmgr`, - `Probes`, - `Properties`, - `Rules`, - `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). - - * `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. - -### 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 - -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. - - * `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, and - anything else is probably not a good idea. - - -## 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. - -## 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 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 - -bcfg2(1), bcfg2-server(8) diff --git a/tools/manpagegen/generate-manpages.bash b/tools/manpagegen/generate-manpages.bash deleted file mode 100644 index 62006c953..000000000 --- a/tools/manpagegen/generate-manpages.bash +++ /dev/null @@ -1,17 +0,0 @@ -#!/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