From 6da7d24710fe67c80c4a71f227cd01675eebca88 Mon Sep 17 00:00:00 2001 From: "Chris St. Pierre" Date: Thu, 21 Apr 2011 08:50:06 -0400 Subject: Lots of cleanup for bcfg2-repo-validate rewrite: * Changed all references to bcfg2-repo-validate in the documentation to bcfg2-lint * Wrote man pages for bcfg2-lint and bcfg2-lint.conf * Cleaned up straggling references to bcfg2-repo-validate in Makefiles, spec files, and the POSIX tool * A few minor bug fixes --- man/bcfg2-lint.8 | 169 ++++++++++++++++++++++++++++++++++++++++++++++ man/bcfg2-lint.conf.5 | 155 ++++++++++++++++++++++++++++++++++++++++++ man/bcfg2-repo-validate.8 | 52 -------------- man/bcfg2-server.8 | 2 +- 4 files changed, 325 insertions(+), 53 deletions(-) create mode 100644 man/bcfg2-lint.8 create mode 100644 man/bcfg2-lint.conf.5 delete mode 100644 man/bcfg2-repo-validate.8 (limited to 'man') diff --git a/man/bcfg2-lint.8 b/man/bcfg2-lint.8 new file mode 100644 index 000000000..624082960 --- /dev/null +++ b/man/bcfg2-lint.8 @@ -0,0 +1,169 @@ +.TH "bcfg2-lint" 8 +.SH NAME +bcfg2-lint \- Check Bcfg2 specification for validity, common mistakes, +and style + +.SH SYNOPSIS +.B bcfg2-lint +.I [OPTIONS] +.I [ [...]] + +.SH DESCRIPTION +.PP +.B bcfg2-lint +This script checks the Bcfg2 specification for schema validity, common +mistakes, and other criteria. It can be quite helpful in finding +typos or malformed data. + +.B 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. + +.B bcfg2-lint +is a rewrite of the older +.B bcfg2-repo-validate +tool. + +.SH OPTIONS + +.TP +.BR "-v" +Be verbose. + +.TP +.BR "-C" +Specify path to bcfg2.conf (default /etc/bcfg2.conf) + +.TP +.BR "--lint-config" +Specify path to bcfg2-lint.conf (default /etc/bcfg2-lint.conf) + +.TP +.BR "-Q" +Specify path to Bcfg2 repository (default /var/lib/bcfg2) + +.TP +.BR "--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. + +.TP +.BR "--require-schema" +Require property files to have matching schema files + +.RE + +.SH "PLUGINS" + +See +.BR bcfg-lint.conf(5) +for more information on the configuration of the plugins listed below. + +.TP +.BR Bundles +Check the specification for several issues with Bundler: bundles +referenced in metadata but not found in +.I Bundler/ +; bundles whose +.I name +attribute does not match the filename; and Genshi template bundles +that use the +.I +tag (which is not processed in templated bundles). + +.TP +.BR Comments +Check the specification for VCS keywords and any comments that are +required. By default, this only checks that the +.I $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. + +.TP +.BR Duplicates +Check for several types of duplicatesin the Metadata: duplicate +groups; duplicate clients; and multiple default groups. + +.TP +.BR InfoXML +Check that certain attributes are specified in +.I info.xml +files. By default, requires that +.I owner +, +.I group +, and +.I perms +are specified. Can also require that an +.I info.xml +exists for all Cfg files, and that paranoid mode be enabled for all +files. + +.TP +.BR Pkgmgr +Check for duplicate packages specified in Pkgmgr. + +.TP +.BR RequiredAttrs +Check that all +.I +and +.I +tags have the attributes that are required by their type. (E.g., a +path of type +.I "symlink" +must have +.I name +and +.I to +specified to be valid. This sort of validation is beyond the scope of +an XML schema. + +.TP +.BR Validate +Validate the Bcfg2 specification against the XML schemas. + +Property files are freeform XML, but if a +.I .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 +.I ntp.xml +then by placing a schema for that file in +.I ntp.xsd +schema validation will be performed on +.I ntp.xml +. + + +.SH "SEE ALSO" +.BR bcfg2(1), +.BR bcfg2-server(8), +.BR bcfg2-lint.conf(5) + +.SH "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. diff --git a/man/bcfg2-lint.conf.5 b/man/bcfg2-lint.conf.5 new file mode 100644 index 000000000..2c89a1161 --- /dev/null +++ b/man/bcfg2-lint.conf.5 @@ -0,0 +1,155 @@ +.TH bcfg2-lint.conf 5 + +.SH NAME +bcfg2-lint.conf - configuration parameters for bcfg2-lint + +.SH DESCRIPTION +.TP +bcfg2-lint.conf includes configuration parameters for +.I bcfg2-lint + +.SH 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. + +.SH GLOBAL OPTIONS +These options apply to +.I bcfg2-lint +generally, and must be in the +.I [main] +section. + +.TP +.BR 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 +.B bcfg2-lint(1) +for a list of the available plugins. + +.SH 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 +.I [InfoXML] +. + +If a plugin is not listed below, then it has no configuration. + +.TP +.BR Comments + +The +.I Comments +plugin configuration specifies which VCS keywords and comments are +required for which file types. The valid types of file are +.I "global" +(all file types), +.I "bundler" +(non-templated bundle files), +.I "sgenshi" +(templated bundle files), +.I "properties" +(property files), +.I "cfg" +(non-templated Cfg files), +.I "tgenshi" +(templated Cfg files), +.I "infoxml" +(info.xml files), and +.I "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.: + +.nf +cfg_keywords = +.fi + +By default, the +.I $Id$ +keyword is checked for and nothing else. + +Multiple keywords or comments should be comma-delimited. + +\(bu +.B _keywords + +Ensure that files of the specified type have the given VCS keyword. +Do +.I not +include the dollar signs. I.e.: + +.nf +infoxml_keywords = Revision +.fi + +.I not: + +.nf +infoxml_keywords = $Revision$ +.fi + +\(bu +.B _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. + +.TP +.BR InfoXML + +\(bu +.B required_attrs +A comma-delimited list of attributes to require on +.I +tags. Default is "owner,group,perms". + +\(bu +.B require_paranoid +Ensure that paranoid mode is on for all files. This can be +accomplished by either setting the global paranoid value (and not +overriding it. Default is false. + +\(bu +.B require +Require an +.I info.xml +file for all Cfg files. Default is false. + +.TP +.BR Validate + +\(bu +.B schema +The full path to the XML Schema files. Default is +"/usr/share/bcfg2/schema". This can be overridden with the +.I --schema +command-line option + +\(bu +.B properties_schema +If set to +.I "warn" +, will warn if a property files does not have a matching schema file. +If set to +.I "require" +, will produce an error if a property files does not have a matching +schema file. Default is to neither warn nor require. + +.SH SEE ALSO +.BR bcfg2-lint(1) + diff --git a/man/bcfg2-repo-validate.8 b/man/bcfg2-repo-validate.8 deleted file mode 100644 index 1bf74a206..000000000 --- a/man/bcfg2-repo-validate.8 +++ /dev/null @@ -1,52 +0,0 @@ -.TH "bcfg2-repo-validate" 8 -.SH NAME -bcfg2-repo-validate \- Check Bcfg2 repository data against data schemas -.SH SYNOPSIS -.B bcfg2-repo-validate -.I [OPTIONS] -.SH DESCRIPTION -.PP -.B bcfg2-repo-validate -This script checks data against schemas, and it quite helpful in -finding typos or malformed data. -.SH OPTIONS - -.TP -.BR "-v" -Be verbose about checks that have succeeded. This also enables -checking for missing bundles. - -.TP -.BR "-C" -Specify path to bcfg2.conf (default /etc/bcfg2.conf) - -.TP -.BR "-Q" -Specify path to Bcfg2 repository (default /var/lib/bcfg2) - -.TP -.BR "--schema" -Specify path to Bcfg2 XML Schemas (default /usr/share/bcfg2/schema) - -.TP -.BR "--stdin" -Rather than validating all XML files in the Bcfg2 specification, only -validate a list of files supplied on stdin. This makes a few -assumptions: - -Files included using XInclude will only be validated if they are -included on stdin; XIncludes will not be followed. - -Property files will only be validated if both the property file itself -and its matching schema are included on stdin. - -.TP -.BR "--require-schema" -Require property files to have matching schema files - -.RE -.SH "SEE ALSO" -.BR bcfg2(1), -.BR bcfg2-server(8) -.SH "BUGS" -None currently known diff --git a/man/bcfg2-server.8 b/man/bcfg2-server.8 index a6bffc1fa..2d132ce6d 100644 --- a/man/bcfg2-server.8 +++ b/man/bcfg2-server.8 @@ -53,6 +53,6 @@ Set path to SSL key. .RE .SH "SEE ALSO" .BR bcfg2(1), -.BR bcfg2-repo-validate(8) +.BR bcfg2-lint(8) .SH "BUGS" None currently known -- cgit v1.2.3-1-g7c22