From a732f8499e1b21df4704d2d8b046c0c7dcc4f7a3 Mon Sep 17 00:00:00 2001 From: "Chris St. Pierre" Date: Wed, 7 Nov 2012 13:34:35 -0500 Subject: doc: made format of man page option lists consistent --- doc/man/bcfg2-admin.txt | 43 +++----- doc/man/bcfg2-build-reports.txt | 20 ++-- doc/man/bcfg2-crypt.txt | 82 +++++++-------- doc/man/bcfg2-info.txt | 28 ++---- doc/man/bcfg2-lint.conf.txt | 1 + doc/man/bcfg2-lint.txt | 56 +++++------ doc/man/bcfg2-reports.txt | 96 ++++++++---------- doc/man/bcfg2-server.txt | 36 +++---- doc/man/bcfg2.conf.txt | 1 + doc/man/bcfg2.txt | 214 +++++++++++++++------------------------- doc/man/index.txt | 1 + 11 files changed, 225 insertions(+), 353 deletions(-) (limited to 'doc/man') diff --git a/doc/man/bcfg2-admin.txt b/doc/man/bcfg2-admin.txt index 26e75050f..6169ec537 100644 --- a/doc/man/bcfg2-admin.txt +++ b/doc/man/bcfg2-admin.txt @@ -1,3 +1,4 @@ +.. -*- mode: rst -*- .. vim: ft=rst bcfg2-admin @@ -19,36 +20,18 @@ administration. Options ------- --C *configfile* - Specify alternate bcfg2.conf location. - --E *encoding* - Specify the encoding of Cfg files. - --Q *path* - Specify the path to the server repository. - --S *https://server:port* - Manually specify the server location (as opposed to using the value - in bcfg2.conf). - --d - Enable debugging output. - --h - Print usage information. - --o *logfile* - Writes a log to the specified path. - ---ssl-key=\ *key* - Specify the path to the SSL key. - --v - Enable verbose output. - --x *password* - Use 'password' for client communication. +-C configfile Specify alternate bcfg2.conf location. +-E encoding Specify the encoding of config files. +-Q path Specify the path to the server repository. +-S server Manually specify the server location (as opposed to + using the value in bcfg2.conf). This should be in + the format "https://server:port" +-d Enable debugging output. +-h Print usage information. +-o logfile Writes a log to the specified path. +--ssl-key=key Specify the path to the SSL key. +-v Enable verbose output. +-x password Use 'password' for client communication. Modes ----- diff --git a/doc/man/bcfg2-build-reports.txt b/doc/man/bcfg2-build-reports.txt index eba8244f2..fc5c2e4fa 100644 --- a/doc/man/bcfg2-build-reports.txt +++ b/doc/man/bcfg2-build-reports.txt @@ -1,3 +1,4 @@ +.. -*- mode: rst -*- .. vim: ft=rst bcfg2-build-reports @@ -19,19 +20,12 @@ reports. See the Bcfg2 manual for report setup information. Options ------- --A - Displays all data. - --c *configuration file* - Specify an alternate report configuration path. The default is - ``repo/etc/reports-configuration.xml``. - --h - Produce a help message. - --s *statistics path* - Use an alternative path for the statistics file. The default is - ``repo/etc/statistics.xml``. +-A Displays all data. +-c configfile Specify an alternate report configuration path. The + default is ``repo/etc/reports-configuration.xml``. +-h Print usage information. +-s statsfile Use an alternative path for the statistics file. The + default is ``repo/etc/statistics.xml``. See Also -------- diff --git a/doc/man/bcfg2-crypt.txt b/doc/man/bcfg2-crypt.txt index 37e60482e..34bd1452d 100644 --- a/doc/man/bcfg2-crypt.txt +++ b/doc/man/bcfg2-crypt.txt @@ -1,3 +1,4 @@ +.. -*- mode: rst -*- .. vim: ft=rst bcfg2-crypt @@ -23,54 +24,39 @@ usually figure out what to do. Options ------- --C *configfile* - Specify alternate bcfg2.conf location. - ---decrypt, --encrypt - Specify which operation you'd like to perform. - :program:`bcfg2-crypt` can usually determine which is necessary - based on the contents of each file. - ---cfg - Tell :program:`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 :program:`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 *Properties* 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 *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 *passphrase* - 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. +-C configfile Specify alternate bcfg2.conf location. +--decrypt, --encrypt Select encryption or decryption mode for the + given file(s). This is usually unnecessary, as + :program:`bcfg2-crypt` can often determine which + is necessary based on the contents of each file. +--cfg 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 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 + *Properties* 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 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 passphrase 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 Print usage information. Modes ----- diff --git a/doc/man/bcfg2-info.txt b/doc/man/bcfg2-info.txt index 93d159474..0ce3ddd11 100644 --- a/doc/man/bcfg2-info.txt +++ b/doc/man/bcfg2-info.txt @@ -1,3 +1,4 @@ +.. -*- mode: rst -*- .. vim: ft=rst bcfg2-info @@ -20,26 +21,13 @@ data examination and debugging purposes. Options ------- --C *configfile* - Specify alternate bcfg2.conf location. - --E *encoding* - Specify the encoding of config files. - --Q *repository path* - Specify the server repository path. - --d - Run in debug mode. - --h - Print usage information. - --p *profile* - Specify a profile. - --x *password* - Set the communication password. +-C configfile Specify alternate bcfg2.conf location. +-E encoding Specify the encoding of config files. +-Q path Specify the path to the server repository. +-d Enable debugging output. +-h Print usage information. +-p profile Specify a profile. +-x password Use 'password' for client communication. Modes ----- diff --git a/doc/man/bcfg2-lint.conf.txt b/doc/man/bcfg2-lint.conf.txt index 5b61060f4..0eaa64339 100644 --- a/doc/man/bcfg2-lint.conf.txt +++ b/doc/man/bcfg2-lint.conf.txt @@ -1,3 +1,4 @@ +.. -*- mode: rst -*- .. vim: ft=rst bcfg2-lint.conf diff --git a/doc/man/bcfg2-lint.txt b/doc/man/bcfg2-lint.txt index 1cfedad4e..b7206bd31 100644 --- a/doc/man/bcfg2-lint.txt +++ b/doc/man/bcfg2-lint.txt @@ -1,3 +1,4 @@ +.. -*- mode: rst -*- .. vim: ft=rst bcfg2-lint @@ -27,36 +28,31 @@ tool. Options ------- --C *configfile* - 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. +-C configfile Specify alternate bcfg2.conf location. +-Q path Specify the path to the server repository. +-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. Plugins ------- diff --git a/doc/man/bcfg2-reports.txt b/doc/man/bcfg2-reports.txt index dbc937711..201a379df 100644 --- a/doc/man/bcfg2-reports.txt +++ b/doc/man/bcfg2-reports.txt @@ -1,3 +1,4 @@ +.. -*- mode: rst -*- .. vim: ft=rst bcfg2-reports @@ -25,8 +26,7 @@ standalone application. It does, however, use the models from Options ------- --h - Shows help and usage info about :program:`bcfg2-reports`. +-h Print usage information. Modes ----- @@ -36,74 +36,58 @@ The following are various modes available for :program:`bcfg2-reports`. Single-Host Modes +++++++++++++++++ --b, --bad *hostname* - Shows bad entries from the current interaction of *hostname*. - --e, --extra *hostname* - Shows extra entries from the current interaction of *hostname*. - --m, --modified *hostname* - Shows modified entries from the current interaction of *hostname*. - --s, --show *hostname* - Shows bad, modified, and extra entries from the current interaction - of *hostname*. - --t, --total *hostname* - Shows total number of managed and good entries from the current - interaction of *hostname*. - --x, --expire *hostname* - Toggles expired/unexpired state of *hostname*. - --a, --all - Show all hosts, including expired hosts. +-b, --bad hostname Shows bad entries from the current + interaction of *hostname*. +-e, --extra hostname Shows extra entries from the current + interaction of *hostname*. +-m, --modified hostname Shows modified entries from the current + interaction of *hostname*. +-s, --show hostname Shows bad, modified, and extra entries from + the current interaction of *hostname*. +-t, --total hostname Shows total number of managed and good + entries from the current interaction of + *hostname*. +-x, --expire hostname Toggles expired/unexpired state of + *hostname*. +-a, --all Show all hosts, including expired hosts. Host Selection Modes ++++++++++++++++++++ --a, --all - Show all hosts, including expired hosts. - --c, --clean - Show only clean hosts. - --d, --dirty - Show only dirty hosts. - ---stale - Show hosts that haven't run in the last 24 hours. +-a, --all Show all hosts, including expired hosts. +-c, --clean Show only clean hosts. +-d, --dirty Show only dirty hosts. +--stale Show hosts that haven't run in the last 24 hours. Entry Modes +++++++++++ ---badentry=\ *entry type, entry name* - Shows only hosts whose current interaction has bad entries of type - *entry type* and name *entry name*. - ---extraentry=\ *entry type, entry name* - Shows only hosts whose current interaction has extra entries of type - *entry type* and name *entry name*. - ---entrystatus=\ *entry type, entry name* - Shows the status of entry type *entry type* and name *entry name* - on all hosts. - ---modifiedentry - Shows only hosts whose current interaction has modifiedentries of - type *entry type* and name *entry name*. +The following mode flags require either a comma-delimited list of any +number of *:* arguments describing entries, or +the *--file* option. + +--badentry=entrylist Shows only hosts whose current interaction + has bad entries matching the given entry or + entries. +--extraentry=entrylist Shows only hosts whose current interaction + has extra entries matching the given entry + or entries. +--entrystatus=entry Shows the status of the single entry (given + by *:*) on all + hosts. +--modifiedentry=entrylist Shows only hosts whose current interaction + has modified entries matching the given + entry or entries. Entry Options ^^^^^^^^^^^^^ The following options can be used with the above Entry Modes. ---fields=\ *FIELD,FIELD,...* - Only display the listed fields. - ---file=\ *FILE* - Read TYPE:NAME pairs from the specified file instead of the command - line. +--fields=fields Only display the listed fields. Takes a + comma-delimited list of field names +--file=file Read *:* pairs from the + specified file instead of the command line. See Also -------- diff --git a/doc/man/bcfg2-server.txt b/doc/man/bcfg2-server.txt index dedc86549..d5945cad6 100644 --- a/doc/man/bcfg2-server.txt +++ b/doc/man/bcfg2-server.txt @@ -1,3 +1,4 @@ +.. -*- mode: rst -*- .. vim: ft=rst bcfg2-server @@ -21,29 +22,18 @@ configurations to clients based on the data in its repository. Options ------- --C *configfile* - Specify alternate bcfg2.conf location. - --D *pidfile* - Daemonize, placing the program pid in the specified pidfile. - --E *encoding* - Specify the encoding of config files (default is UTF-8). - --Q *repo path* - Set repository path. - --S *https://server:port* - Set server address. - --d - Run :program:`bcfg2-server` in debug mode. - --v - Run :program:`bcfg2-server` in verbose mode. - ---ssl-key=\ *ssl key* - Set path to SSL key. +-C configfile Specify alternate bcfg2.conf location. +-D pidfile Daemonize, placing the program pid in the specified + pidfile. +-E encoding Specify the encoding of config files. +-Q path Specify the path to the server repository. +-S server Manually specify the server location (as opposed to + using the value in bcfg2.conf). This should be in + the format "https://server:port" +-d Enable debugging output. +-v Run in verbose mode. +-h Print usage information. +--ssl-key=key Specify the path to the SSL key. See Also -------- diff --git a/doc/man/bcfg2.conf.txt b/doc/man/bcfg2.conf.txt index 9756c3891..942ead40d 100644 --- a/doc/man/bcfg2.conf.txt +++ b/doc/man/bcfg2.conf.txt @@ -1,3 +1,4 @@ +.. -*- mode: rst -*- .. vim: ft=rst bcfg2.conf diff --git a/doc/man/bcfg2.txt b/doc/man/bcfg2.txt index 54560127d..6a77a4a3c 100644 --- a/doc/man/bcfg2.txt +++ b/doc/man/bcfg2.txt @@ -1,3 +1,4 @@ +.. -*- mode: rst -*- .. vim: ft=rst bcfg2 @@ -26,139 +27,86 @@ host. This process consists of the following steps. Options ------- --B - Configure everything except the given bundle(s). - --C *configfile* - Specify alternate bcfg2.conf location. - --D [*driver1,driver2*] - 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 *encoding* - Specify the encoding of config 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. - --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 *retrycount* - Specify the number of times that the client will attempt to retry - network communication. - --S *https://server:port* - 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 *cachefile* - Cache a copy of the configuration in cachefile. - ---ca-cert=\ *cacert* - 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 *path* - 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 *whitelist|blacklist|none* - 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 - tocentrally 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 *logfile* - Writes a log to the specified path. - --p *profile* - 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. - --r *mode* - 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 *servicemode* - 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=\ *cert* - Specify the path to the SSL certificate. - ---ssl-cns=\ *CN1:CN2* - List of acceptable SSL server Common Names. - ---ssl-key=\ *key* - Specify the path to the SSL key. - --u *user* - Attempt to authenticate as 'user'. - --t *timeout* - Set the timeout (in seconds) for client communication. Default is - 90 seconds. - --v - Run bcfg2 in verbose mode. - --x *password* - Use 'password' for client communication. - --z - Only configure independent entries, ignore bundles. +-B Configure everything except the given bundle(s). +-C configfile Specify alternate bcfg2.conf location. +-D drivers Specify a comma-delimited 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 encoding Specify the encoding of config 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. +-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 retrycount Specify the number of times that the client will + attempt to retry network communication. +-S server Manually specify the server location (as opposed to + using the value in bcfg2.conf). This should be in + the format "https://server:port" +-Z Do not configure independent entries. +-b bundles Run only the specified colon-delimited set of + bundles. +-c cachefile Cache a copy of the configuration in cachefile. +--ca-cert=cacert Specifiy the path to the SSL CA certificate. +-d Enable debugging output. +-e When in verbose mode, display extra entry + information. +-f path 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 decisionmode Run the client in the specified decision list mode + ("whitelist" or "blacklist"), or "none", which can + be used 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 tocentrally 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 logfile Writes a log to the specified path. +-p profile 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. +-r mode 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 servicemode 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=cert Specify the path to the SSL certificate. +--ssl-cns=CNs Colon-delimited list of acceptable SSL server Common + Names. +--ssl-key=key Specify the path to the SSL key. +-u user Attempt to authenticate as 'user'. +-t timeout Set the timeout (in seconds) for client + communication. Default is 90 seconds. +-v Run bcfg2 in verbose mode. +-x password Use 'password' for client communication. +-z Only configure independent entries, ignore bundles. See Also -------- diff --git a/doc/man/index.txt b/doc/man/index.txt index ae6b88ac2..2df4df8a2 100644 --- a/doc/man/index.txt +++ b/doc/man/index.txt @@ -1,3 +1,4 @@ +.. -*- mode: rst -*- .. vim: ft=rst .. _man-index: -- cgit v1.2.3-1-g7c22