diff options
Diffstat (limited to 'doc/server/plugins')
| -rw-r--r-- | doc/server/plugins/generators/packages.txt | 216 | ||||
| -rw-r--r-- | doc/server/plugins/generators/pkgmgr.txt | 91 | ||||
| -rw-r--r-- | doc/server/plugins/generators/rules.txt | 479 | ||||
| -rw-r--r-- | doc/server/plugins/generators/semodules.txt | 9 | ||||
| -rw-r--r-- | doc/server/plugins/generators/sslca.txt | 90 | ||||
| -rw-r--r-- | doc/server/plugins/grouping/metadata.txt | 236 | ||||
| -rw-r--r-- | doc/server/plugins/structures/bundler/index.txt | 2 |
7 files changed, 328 insertions, 795 deletions
diff --git a/doc/server/plugins/generators/packages.txt b/doc/server/plugins/generators/packages.txt index 352c88f43..e45864ef9 100644 --- a/doc/server/plugins/generators/packages.txt +++ b/doc/server/plugins/generators/packages.txt @@ -18,14 +18,14 @@ through those channels. Limiting sources to groups ========================== -``Packages/sources.xml`` processes ``<Group>`` and ``<Client>`` tags -just like Bundles. In addition to any groups or clients specified -that way, clients must -be a member of the appropriate architecture group as specified in a -Source stanza. In total, in order for a source to be associated with -a client, the client must be in one of the magic groups (debian, -ubuntu, or nexenta), any explicit groups or clients specified in -``sources.xml``, and any specified architecture groups. +`sources.xml`_ processes ``<Group>`` and ``<Client>`` tags just like +Bundles. In addition to any groups or clients specified that way, +clients must be a member of the appropriate architecture group as +specified in a Source stanza. In total, in order for a source to be +associated with a client, the client must be in any explicit groups or +clients specified in `sources.xml`_, and any specified architecture +groups. If `"Magic Groups"`_ are enabled, then the client must be a +member of a matching magic group as well. Memberships in architecture groups is needed so that Packages can map software sources to clients. There is no other way to handle this than @@ -40,7 +40,7 @@ sources. To recap, a client needs to be a member of the **Architecture** group and any other groups defined in your - ``Packages/sources.xml`` file in order for the client to be + `sources.xml`_ file in order for the client to be associated to the proper sources. If you are using :ref:`server-plugins-generators-packages-magic-groups`, then a client must also be a member of the appropriate OS group. @@ -50,8 +50,7 @@ sources. "Magic Groups" ============== -.. note:: Magic groups are deprecated in 1.3.0 and will be removed in - a future release. They are disabled by default. +.. deprecated:: 1.3.0 Packages has the ability to use a feature known as "magic groups"; it is the only plugin to use that feature. Most plugins operate based on @@ -98,70 +97,31 @@ Setup Three basic steps are required for Packages to work properly. -#. Create ``Packages/sources.xml``. This file should look - approximately like the example below, and describes both which - software repositories should be used, and which clients are eligible - to use each one. +#. Create Packages/`sources.xml`_. This file should look + approximately like the example below, and describes both which + software repositories should be used, and which clients are + eligible to use each one. #. Ensure that clients are members of the proper groups. Each client - should be a member of one of the magic groups listed above, all of - the groups listed in the ``sources.xml`` (like ubuntu-intrepid or - centos-5.2 in the following examples), and one of the architecture - groups listed in the source configuration (i386, amd64 or x86_64 in - the following examples). '''Failure to do this will result in the - source either not applying to the client, or only architecture - independent packages being made available to the client.''' + should be a member of all of the groups listed in the `sources.xml` + (like ubuntu-intrepid or centos-5.2 in the following examples), one + of the architecture groups listed in the source configuration + (i386, amd64 or x86_64 in the following examples), and one of the + magic groups listed above, if magic groups are enabled. '''Failure + to do this will result in the source either not applying to the + client, or only architecture independent packages being made + available to the client.''' #. Add Package entries to bundles. #. Sit back and relax, as dependencies are resolved, and automatically added to client configurations. -Prerequisite Resolution -======================= - -Packages provides a prerequisite resolution mechanism which has no -analogue in Pkgmgr. During configuration generation, all structures are -processed. After this phase, but before entry binding, a list of packages -and the client metadata instance is passed into Packages' resolver. This -process determines a superset of packages that will fully satisfy -dependencies of all package entries included in structures, and reports -any prerequisites that cannot be satisfied. This facility should largely -remove the need to use the :ref:`Base <server-plugins-structures-base>` -plugin. - -Disabling dependency resolution -------------------------------- - -.. versionadded:: 1.1.0 - -Dependency resolution can be disabled by adding the following setting -to ``bcfg2.conf`` in the ``packages`` section:: - - [packages] - resolver=0 - -All metadata processing can be disabled as well:: - - [packages] - metadata=0 - -This setting implies disabling the resolver. - -Blacklisting faulty dependencies --------------------------------- - -If you encounter an issue with faulty dependency resolution due to -Packages, please file a bug report so that we can fix the problem in -future releases. In the meantime, you can work around this issue by -blacklisting the offending Package in your Sources. The blacklist -element should immediately follow the Component section of your source -and should look like the following: +sources.xml +----------- -.. code-block:: xml +``sources.xml`` is where all package sources are configured for the +Packages plugin. It processes ``<Group>`` and ``<Client>`` tags just like +Bundles. The primary element in ``sources.xml`` is the Source tag: - <Blacklist>unwanted-packagename</Blacklist> - -If you use the built-in :ref:`Yum config generator -<generating-client-configs>`, blacklisted packages will be added to -the ``exclude`` list for the source. +.. xml:element:: Source Handling GPG Keys ----------------- @@ -172,7 +132,7 @@ If you have yum libraries installed, Packages can automatically handle GPG signing keys for Yum and Pulp repositories. (You do not need to use the native yum resolver; if yum libraries are available, GPG signing keys can be handled automatically.) Simply specify the URL to -the GPG key(s) for a repository in ``sources.xml``: +the GPG key(s) for a repository with :xml:element:`GPGKey` elements: .. code-block:: xml @@ -201,8 +161,9 @@ You can specify arbitrary options to be added to the repository config on the server side, if you are using the native yum libraries, and on the client side if you are using the ability of Packages to automatically generate your Yum config. To do this, add an -``<Options>`` tag to a Source; all of its attributes will be added -verbatim to the repository in the generated config. For instance: +:xml:element:`Options` tag to a :xml:element:`Source`; all of its +attributes will be added verbatim to the repository in the generated +config. For instance: .. code-block:: xml @@ -212,11 +173,13 @@ verbatim to the repository in the generated config. For instance: </Source> If you are using native yum libraries and need to set options only on -the Bcfg2 server, you can set the ``serveronly`` attribute to "true"; -or, if you need to set options only on the client, you can set the -``clientonly`` attribute to "true". For instance, if your Bcfg2 -server needed to use a proxy to access a repo, and you wanted to -expire metadata caches very quickly on the client, you could do: +the Bcfg2 server, you can set the +:xml:attribute:`RepoOptionsType:serveronly` attribute to "true"; or, +if you need to set options only on the client, you can set the +:xml:attribute:`RepoOptionsType:clientonly` attribute to "true". For +instance, if your Bcfg2 server needed to use a proxy to access a repo, +and you wanted to expire metadata caches very quickly on the client, +you could do: .. code-block:: xml @@ -226,12 +189,61 @@ expire metadata caches very quickly on the client, you could do: <Options clientonly="true" metadata_expire="0"/> </Source> +Prerequisite Resolution +======================= + +Packages provides a prerequisite resolution mechanism which has no +analogue in Pkgmgr. During configuration generation, all structures are +processed. After this phase, but before entry binding, a list of packages +and the client metadata instance is passed into Packages' resolver. This +process determines a superset of packages that will fully satisfy +dependencies of all package entries included in structures, and reports +any prerequisites that cannot be satisfied. This facility should largely +remove the need to use the :ref:`Base <server-plugins-structures-base>` +plugin. + +Disabling dependency resolution +------------------------------- + +.. versionadded:: 1.1.0 + +Dependency resolution can be disabled by adding the following setting +to ``bcfg2.conf`` in the ``packages`` section:: + + [packages] + resolver=0 + +All metadata processing can be disabled as well:: + + [packages] + metadata=0 + +This setting implies disabling the resolver. + +Blacklisting faulty dependencies +-------------------------------- + +If you encounter an issue with faulty dependency resolution due to +Packages, please file a bug report so that we can fix the problem in +future releases. In the meantime, you can work around this issue by +blacklisting the offending Package in your Sources. The +:xml:element:`Blacklist` element should immediately follow the +Component section of your source and should look like the following: + +.. code-block:: xml + + <Blacklist>unwanted-packagename</Blacklist> + +If you use the built-in :ref:`Yum config generator +<generating-client-configs>`, blacklisted packages will be added to +the ``exclude`` list for the source. + .. _packages-exampleusage: Example usage ============= -Create a ``sources.xml`` file in the Packages directory that looks +Create a _`sources.xml` file in the Packages directory that looks something like this: .. code-block:: xml @@ -254,12 +266,13 @@ something like this: .. versionadded:: 1.1.0 The default behavior of the Packages plugin is to not make any - assumptions about which packages you want to have added automatically - [#f1]_. For that reason, neither **Recommended** nor **Suggested** - packages are added as dependencies by default. You will notice - that the default behavior for apt is to add Recommended packages as - dependencies. You can configure the Packages plugin to add recommended - packages by adding the ``recommended`` attribute, e.g.: + assumptions about which packages you want to have added + automatically [#f1]_. For that reason, neither **Recommended** nor + **Suggested** packages are added as dependencies by default. You + will notice that the default behavior for apt is to add + Recommended packages as dependencies. You can configure the + Packages plugin to add recommended packages by adding the + :xml:attribute:`SourceType:recommended` attribute, e.g.: .. code-block:: xml @@ -270,7 +283,8 @@ something like this: .. [#f1] Bcfg2 will by default add **Essential** packages to the client specification. You can disable this behavior by - setting the ``essential`` attribute to *false*: + setting the :xml:attribute:`SourceType:essential` + attribute to *false*: .. code-block:: xml @@ -295,8 +309,8 @@ Yum sources can be similarly specified: </Group> </Sources> -For sources with a **URL** attribute, the **Version** attribute is -also necessary. +For sources with a :xml:attribute:`SourceType:url` attribute, the +:xml:attribute:`SourceType:version` attribute is also necessary. :ref:`Pulp sources <pulp-source-support>` are very simple to specify due to the amount of data that can be queried from Pulp itself: @@ -388,8 +402,7 @@ download only missing sources.:: [0:3711] bcfg2-admin xcmd Packages.Reload True -This is done automatically any time ``Packages/sources.xml`` is -updated. +This is done automatically any time `sources.xml`_ is updated. Availability ============ @@ -397,19 +410,11 @@ Availability Support for clients using yum and apt is currently available. Support for other package managers (Portage, Zypper, IPS, etc) remain to be added. -Validation -========== - -A schema for ``Packages/sources.xml`` is included; ``sources.xml`` can -be validated using ``bcfg2-lint``. - -.. note:: The schema requires that elements be specified in the above order. - Package Checking and Verification ================================= -In order to do disable per-package verification Pkgmgr style, you will -need to use :ref:`BoundEntries <boundentries>`, e.g.: +In order to do disable per-package verification, you will need to use +:ref:`BoundEntries <boundentries>`, e.g.: .. code-block:: xml @@ -533,9 +538,9 @@ Package Groups -------------- Yum package groups are supported by the native Yum libraries. To -include a package group, use the ``group`` attribute of the -``Package`` tag. You can use either the short group ID or the long -group name: +include a package group, use the :xml:attribute:`PackageType:group` +attribute of the :xml:element:`Package` tag. You can use either the +short group ID or the long group name: .. code-block:: xml @@ -544,7 +549,7 @@ group name: By default, only those packages considered the "default" packages in a group will be installed. You can change this behavior using the -"type" attribute: +:xml:attribute:`PackageStructure:type` attribute: .. code-block:: xml @@ -558,6 +563,8 @@ Valid values of "type" are: * ``optional`` or ``all``: Install all packages in the group, including mandatory, default, and optional packages. +See :xml:element:`PackageStructure` for details. + You can view the packages in a group by category with the ``yum groupinfo`` command. More information about the different levels can be found at @@ -580,7 +587,7 @@ Bcfg2 contains explicit support for repositories managed by Pulp Due to the amount of data about a repository that can be retrieved directly from Pulp, the only thing necessary to configure a Pulp repo -is the repo ID: +is the repo ID, in :xml:attribute:`SourceType:pulp_id`: .. code-block:: xml @@ -668,7 +675,6 @@ TODO list * Zypper support * Portage support -* Explicit version pinning (a la Pkgmgr) .. _configuration: @@ -694,7 +700,7 @@ It understands the following directives: | metadata | Enable metadata processing. Disabling ``metadata`` | Boolean | True | | | implies disabling ``resolver`` as well. | | | +-------------+------------------------------------------------------+----------+-----------------------------+ -| yum_config | The path at which to generate Yum configs. | String | /etc/yum.repos.d/bcfg2.repo | +| yum_config | The path at which to generate Yum configs. | String | /etc/yum.repos.d/bcfg2.repo | +-------------+------------------------------------------------------+----------+-----------------------------+ | apt_config | The path at which to generate APT configs. | String | /etc/apt/sources.d/bcfg2 | +-------------+------------------------------------------------------+----------+-----------------------------+ diff --git a/doc/server/plugins/generators/pkgmgr.txt b/doc/server/plugins/generators/pkgmgr.txt index 0d992685c..ace7c16ef 100644 --- a/doc/server/plugins/generators/pkgmgr.txt +++ b/doc/server/plugins/generators/pkgmgr.txt @@ -40,94 +40,9 @@ Group membership may be negated. Tag Attributes in Pkgmgr ======================== -Package Tag -^^^^^^^^^^^ - -The package tag supports the name and pkg_checks attributes and -requires the use of Instance tag entries. - -+------------+---------------------------------------+------------------------+ -| Attribute | Description | Values | -+============+=======================================+========================+ -| name | Package name. | String | -+------------+---------------------------------------+------------------------+ -| pkg_checks | Do the version and rpm verify checks. | true(default) or false | -+------------+---------------------------------------+------------------------+ - -Instance Tag and Attributes -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The instance tag supports the following attributes: - -+---------------------+----------------------------+--------------------------+ -| Attribute | Description | Values | -+=====================+============================+==========================+ -| simplefile | Package file name. | String (see Notes below) | -+---------------------+----------------------------+--------------------------+ -| epoch | Package epoch. | String (numeric only) | -| | | (optional) | -+---------------------+----------------------------+--------------------------+ -| version | Package version. | String | -+---------------------+----------------------------+--------------------------+ -| release | Package release. | String | -+---------------------+----------------------------+--------------------------+ -| arch | Package architecture. | Architecture String e.g. | -| | | (i386|i586|i686|x86_64) | -+---------------------+----------------------------+--------------------------+ -| verify_flags | Comma separated list of | nodeps, nodigest, | -| | rpm --verify options. See | nofiles, noscripts, | -| | the rpm man page for their | nosignature, nolinkto, | -| | details. | nomd5, nosize, nouser, | -| | | nogroup, nomtime, | -| | | nomode, nordev | -+---------------------+----------------------------+--------------------------+ -| pkg_verify | Do the rpm verify | true(default) or false | -+---------------------+----------------------------+--------------------------+ -| install_action | Install package instance | install(default) or none | -| | if it is not installed. | | -+---------------------+----------------------------+--------------------------+ -| version_fail_action | Upgrade package if the | upgrade(default) or none | -| | incorrect version is | | -| | installed. | | -+---------------------+----------------------------+--------------------------+ -| verify_fail_action | Reinstall the package | reinstall(default) or | -| | instance if the rpm verify | none | -| | failed | | -+---------------------+----------------------------+--------------------------+ - -Pkgmgr Group Tag ----------------- - -The Pkgmgr Group Tag may have the following attributes: - -+--------+----------------------------------------------+------------+ -| Name | Description | Values | -+========+==============================================+============+ -| name | Group Name | String | -+--------+----------------------------------------------+------------+ -| negate | Negate group membership (is not a member of) | True|False | -+--------+----------------------------------------------+------------+ - - -Client Tag ----------- - -The Client Tag is used in a PackageList for selecting the package entries -to include in the clients literal configuration. Its function is similar -to the Group tag in this context. It can be thought of as:: - - if client is name then - assign to literal config - -The Client Tag may have the following attributes: - -+--------+----------------------------------------------+------------+ -| Name | Description | Values | -+========+==============================================+============+ -| name | Client Name | String | -+--------+----------------------------------------------+------------+ -| negate | Negate client selection (if not client name) | True|False | -+--------+----------------------------------------------+------------+ +.. xml:schema:: pkglist.xsd + :linktotype: + :noautodep: PackageType Pkgmgr Directory ================ diff --git a/doc/server/plugins/generators/rules.txt b/doc/server/plugins/generators/rules.txt index ba188ae5c..a3f29a803 100644 --- a/doc/server/plugins/generators/rules.txt +++ b/doc/server/plugins/generators/rules.txt @@ -12,6 +12,9 @@ The Rules plugin resolves the following Abstract Configuration Entities: * Package * Path * Action +* All SELinux entries +* POSIXUser +* POSIXGroup to literal configuration entries suitable for the client drivers to consume. @@ -53,121 +56,27 @@ entry specified. Rules Tag --------- -The Rules Tag may have the following attributes: - -+----------+-------------------------------------+--------+ -| Name | Description | Values | -+==========+=====================================+========+ -| priority | Sets the priority for Rules in this | String | -| | Rules list.The higher value wins. | | -+----------+-------------------------------------+--------+ - -Group Tag ---------- - -The Group Tag may have the following attributes: - -+--------+-------------------------+--------------+ -| Name | Description | Values | -+========+=========================+==============+ -| name | Group Name | String | -+--------+-------------------------+--------------+ -| negate | Negate group membership | (true|false) | -| | (is not a member of) | | -+--------+-------------------------+--------------+ - -Client Tag ----------- - -The Client Tag is used in Rules for selecting the package entries to -include in the clients literal configuration. Its function is similar -to the Group tag in this context. It can be thought of as:: - - if client is name then - assign to literal config - -The Client Tag may have the following attributes: - -+--------+-------------------------+--------------+ -| Name | Description | Values | -+========+=========================+==============+ -| name | Client Name | String | -+--------+-------------------------+--------------+ -| negate | Negate client selection | (true|false) | -| | (if not client name) | | -+--------+-------------------------+--------------+ +.. xml:element:: Rules + :linktotype: + :noautodep: + :inlinetypes: PostInstall,RContainerType Package Tag ----------- -The Package Tag may have the following attributes: - -+------------+----------------------------------------------+----------+ -| Name | Description | Values | -+============+==============================================+==========+ -| name | Package name | String | -+------------+----------------------------------------------+----------+ -| version | Package Version or version='noverify' to | String | -| | not do version checking in the Yum driver | | -| | only (temporary work a round). | | -+------------+----------------------------------------------+----------+ -| file | Package file name. Several other attributes | String | -| | (name, version) can be automatically defined | | -| | based on regular expressions defined in the | | -| | Pkgmgr plugin. | | -+------------+----------------------------------------------+----------+ -| simplefile | Package file name. No name parsing is | String | -| | performed, so no extra fields get set | | -+------------+----------------------------------------------+----------+ -| verify | verify='false' - do not do package | String | -| | verification | | -+------------+----------------------------------------------+----------+ -| multiarch | Comma separated list of the architectures of | String | -| | this package that should be installed. | | -+------------+----------------------------------------------+----------+ -| srcs | Filename creation rules for multiarch | String | -| | packages. | | -+------------+----------------------------------------------+----------+ -| type | Package type. (rpm, yum, apt,sysv,blast) | String | -+------------+----------------------------------------------+----------+ +.. xml:type:: PackageType Action Tag ---------- -See :ref:`client-tools-actions` +.. xml:type:: ActionType + +See also :ref:`client-tools-actions`. Service Tag ----------- -+------------+-------------------------------+---------------------------------------------------------+ -| Name | Description | Values | -+============+===============================+=========================================================+ -| restart | Whether to restart the | ( true | false | interactive ) | -| | service when the bundle | | -| | changes (new in 1.3; replaces | | -| | "mode" attribute) | | -+------------+-------------------------------+---------------------------------------------------------+ -| install | Whether to install the | ( true | false ) | -| | service (new in 1.3; replaces | | -| | "mode" attribute) | | -+------------+-------------------------------+---------------------------------------------------------+ -| name | Service name | String | -+------------+-------------------------------+---------------------------------------------------------+ -| status | Should the service be on or | (on | off | ignore) | -| | off (default: off). | | -+------------+-------------------------------+---------------------------------------------------------+ -| target | Service command for restart | String | -| | (default: restart) | | -+------------+-------------------------------+---------------------------------------------------------+ -| type | Driver to use on the client | (chkconfig | deb | rc-update | smf | upstart | | -| | to manage this service. | systemd | freebsd | launchd ) | -+------------+-------------------------------+---------------------------------------------------------+ -| sequence | Order for service startup | integer | -| | (debian services only) | | -+------------+-------------------------------+---------------------------------------------------------+ -| parameters | Pass parameters to service | String | -| | (Upstart services only) | | -+------------+-------------------------------+---------------------------------------------------------+ +.. xml:type:: ServiceType Service mode specification ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -175,7 +84,8 @@ Service mode specification .. versionadded:: 1.3.0 In the 1.3.0 release, the "mode" attribute has been replaced by a pair -of attributes, "restart" and "install," which control how a service is +of attributes, :xml:attribute:`ServiceType:restart` and +:xml:attribute:`ServiceType:install`, which control how a service is handled more granularly than the old "mode" attribute. The old "mode" attribute values are equivalent as follows: @@ -197,21 +107,6 @@ Previously, "supervised" could be used to start a service during the verification phase; this is no longer supported. Services that have been stopped on a client will be started during the install phase. -Service status descriptions -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -* on - - * start the service at boot time - -* off - - * don't start the service at boot time - -* ignore - - * Don't perform service status checks. - Path Tag -------- @@ -227,106 +122,142 @@ the context of the file to the default set by policy. See Attributes common to all Path tags: -+----------+-------------+--------+ -| Name | Description | Values | -+==========+=============+========+ -| name | Full path | String | -+----------+-------------+--------+ +.. xml:type:: PathType + :nochildren: + :noattributegroups: + :nodoc: + :notext: + :onlyattrs: name,type device ^^^^^^ -+-----------+---------------------+-------------------+ -| Name | Description | Values | -+===========+=====================+===================+ -| dev_type | Type of device | (block|char|fifo) | -+-----------+---------------------+-------------------+ -| owner | Device owner | String | -+-----------+---------------------+-------------------+ -| group | Device group | String | -+-----------+---------------------+-------------------+ -| mode | Mode for the device | String | -+-----------+---------------------+-------------------+ -| secontext | SELinux context | String | -+-----------+---------------------+-------------------+ -| major | Major number (block | integer | -| | or char devices) | | -+-----------+---------------------+-------------------+ -| minor | Minor number (block | integer | -| | or char devices) | | -+-----------+---------------------+-------------------+ +Manage devices. + +.. xml:type:: PathType + :nochildren: + :noattributegroups: + :nodoc: + :notext: + :onlyattrs: dev_type,owner,group,mode,secontext,major,minor + :requiredattrs: dev_type,owner,group,mode directory ^^^^^^^^^ -+-----------+------------------------------+------------+ -| Name | Description | Values | -+===========+==============================+============+ -| mode | File mode of the directory | String | -+-----------+------------------------------+------------+ -| owner | Owner of the directory | String | -+-----------+------------------------------+------------+ -| group | Group Owner of the directory | String | -+-----------+------------------------------+------------+ -| secontext | SELinux context | String | -+-----------+------------------------------+------------+ -| prune | prune unspecified entries | true|false | -| | from the Directory | | -+-----------+------------------------------+------------+ +Entry represents a directory. :xml:attribute:`PathType:prune` can be +set to remove all contents from the directory that are not explicitly +specified in Bcfg2. + +.. xml:type:: PathType + :nochildren: + :noattributegroups: + :nodoc: + :notext: + :onlyattrs: owner,group,mode,secontext,prune + :requiredattrs: owner,group,mode + +file +^^^^ + +Distribute an file with content explicitly specified in-line (i.e., as +opposed to using :ref:`server-plugins-generators-cfg` for this file). +If the file has no content, :xml:attribute:`PathType:empty` *must* be +set to ``true``. + +.. xml:type:: PathType + :nochildren: + :noattributegroups: + :nodoc: + :onlyattrs: owner,group,mode,secontext,empty + :requiredattrs: owner,group,mode hardlink ^^^^^^^^ -+-----------+------------------------------+--------+ -| Name | Description | Values | -+===========+==============================+========+ -| to | File to link to | String | -+-----------+------------------------------+--------+ -| owner | Owner of the directory | String | -+-----------+------------------------------+--------+ -| group | Group Owner of the directory | String | -+-----------+------------------------------+--------+ -| secontext | SELinux context | String | -+-----------+------------------------------+--------+ +Manage a hard link. + +.. xml:type:: PathType + :nochildren: + :noattributegroups: + :nodoc: + :notext: + :onlyattrs: owner,group,mode,secontext,to + :requiredattrs: owner,group,mode,to + +.. _path-ignore: + +ignore +^^^^^^ + +``ignore`` lets you flag files that are distributed by system software +packages, but have been modified locally, to be ignored by package +verification routines. This is useful for, e.g., a package that +installs an initial version of a file and then modifies it +automatically. + +.. xml:type:: PathType + :nochildren: + :noattributegroups: + :nodoc: + :notext: + :onlyattrs: name + :requiredattrs: name nonexistent ^^^^^^^^^^^ -+-----------+--------------------+-------------+ -| Name | Description | Values | -+===========+====================+=============+ -| type | Type of file | nonexistent | -+-----------+--------------------+-------------+ -| recursive | Recursively remove | Boolean | -| | directory contents | | -+-----------+--------------------+-------------+ +Remove the specified file or directory. If +:xml:attribute:`PathType:recursive` is set, remove the directory +recursively (i.e., ``rm -rf``). + +.. xml:type:: PathType + :nochildren: + :noattributegroups: + :nodoc: + :notext: + :onlyattrs: recursive permissions ^^^^^^^^^^^ -+-----------+-----------------------------+---------+ -| Name | Description | Values | -+===========+=============================+=========+ -| mode | Mode of the file | String | -+-----------+-----------------------------+---------+ -| owner | Owner of the file | String | -+-----------+-----------------------------+---------+ -| group | Group of the file | String | -+-----------+-----------------------------+---------+ -| secontext | SELinux context | String | -+-----------+-----------------------------+---------+ -| recursive | Recursively set permissions | Boolean | -+-----------+-----------------------------+---------+ +Merely set permissions on the specified path, which is presumed to +already exist. + +.. xml:type:: PathType + :nochildren: + :noattributegroups: + :nodoc: + :notext: + :onlyattrs: owner,group,mode,secontext,recursive + :requiredattrs: owner,group,mode symlink ^^^^^^^ -+------+----------------------+--------+ -| Name | Description | Values | -+======+======================+========+ -| to | File to link to | String | -+------+----------------------+--------+ +Manage symlinks. + +.. xml:type:: PathType + :nochildren: + :noattributegroups: + :nodoc: + :notext: + :onlyattrs: to + :requiredattrs: to + +vcs +^^^ + +Check out the specified VCS repository to the given path. + +.. xml:type:: PathType + :nochildren: + :noattributegroups: + :nodoc: + :notext: + :onlyattrs: vcstype,revision,sourceurl + :requiredattrs: vcstype,revision,sourceurl .. _server-plugins-generators-rules-acls: @@ -346,31 +277,7 @@ child ``<ACL>`` tags. For instance: <ACL type="default" scope="group" group="users" perms="rx"/> </Path> -The ACL tag has the following attributes: - -+-------+---------------------------------------------------+----------------+ -| Name | Description | Values | -+=======+===================================================+================+ -| type | ACL type | default|access | -+-------+---------------------------------------------------+----------------+ -| scope | ACL scope | user|group | -+-------+---------------------------------------------------+----------------+ -| user | User the ACL applies to ``(with scope="user"``) | String | -+-------+---------------------------------------------------+----------------+ -| group | Group the ACL applies to ``(with scope="group"``) | String | -+-------+---------------------------------------------------+----------------+ -| perms | Permissions for the ACL | See below | -+-------+---------------------------------------------------+----------------+ - -The ``perms`` attribute can either be a single octal digit (e.g., -``6`` would indicate read and write, but not execute), or a symbolic -mode including 'r', 'w', and 'x'. You can include '-' for operations -that are not permitted, but it's not required. I.e., all of the -following are identical:: - - perms="5" - perms="rx" - perms="r-x" +.. xml:element:: ACL It is not currently possible to manually set an effective rights mask; the mask will be automatically calculated from the given ACLs when @@ -420,108 +327,49 @@ See :ref:`server-selinux` for more information. SEBoolean Tag ^^^^^^^^^^^^^ -+-------+----------------------+---------+----------+ -| Name | Description | Values | Required | -+=======+======================+=========+==========+ -| name | Name of the boolean | String | Yes | -+-------+----------------------+---------+----------+ -| value | Value of the boolean | on|off | Yes | -+-------+----------------------+---------+----------+ +.. xml:type:: SEBooleanType SEPort Tag ^^^^^^^^^^ -+-------------+------------------------+---------------------------+----------+ -| Name | Description | Values | Required | -+=============+========================+===========================+==========+ -| name | Port number or range | ``<port>/<proto>`` or | Yes | -| | and protocol (tcp|udp) | ``<start>-<end>/<proto>`` | | -+-------------+------------------------+---------------------------+----------+ -| selinuxtype | SELinux type to apply | String | Yes | -| | to this port | | | -+-------------+------------------------+---------------------------+----------+ +.. xml:type:: SEPortType SEFcontext Tag ^^^^^^^^^^^^^^ -+-------------+-------------------------+---------------------+----------+ -| Name | Description | Values | Required | -+=============+=========================+=====================+==========+ -| name | File specification | String | Yes | -+-------------+-------------------------+---------------------+----------+ -| selinuxtype | SELinux type to apply | String | Yes | -| | to files matching this | | | -| | specification | | | -+-------------+-------------------------+---------------------+----------+ -| filetype | File type to match. | (regular|directory| | No | -| | Default: all | symlink|pipe|all| | | -| | | socket|block|char) | | -+-------------+-------------------------+---------------------+----------+ +.. xml:type:: SEFcontextType SENode Tag ^^^^^^^^^^ -+-------------+------------------------------------+------------------+----------+ -| Name | Description | Values | Required | -+=============+====================================+==================+==========+ -| name | IP address and netmask of node. | <addr>/<netmask> | Yes | -| | Netmask can be numeric (/16) or | | | -| | dotted-quad (/255.255.0.0) | | | -+-------------+------------------------------------+------------------+----------+ -| selinuxtype | SELinux type to apply to this node | String | Yes | -+-------------+------------------------------------+------------------+----------+ -| proto | Protocol | (ipv4|ipv6) | Yes | -+-------------+------------------------------------+------------------+----------+ +.. xml:type:: SENodeType SELogin Tag ^^^^^^^^^^^ -+-------------+-------------------------------+-----------+----------+ -| Name | Description | Values | Required | -+=============+===============================+===========+==========+ -| name | Unix username | String | Yes | -+-------------+-------------------------------+-----------+----------+ -| selinuxuser | SELinux username | String | Yes | -+-------------+-------------------------------+-----------+----------+ +.. xml:type:: SELoginType SEUser Tag ^^^^^^^^^^ -+-------------+-------------------------------+-----------+----------+ -| Name | Description | Values | Required | -+=============+===============================+===========+==========+ -| name | SELinux username | String | Yes | -+-------------+-------------------------------+-----------+----------+ -| roles | Space-separated list of roles | String | Yes | -+-------------+-------------------------------+-----------+----------+ -| prefix | Home directory context prefix | String | Yes | -+-------------+-------------------------------+-----------+----------+ +.. xml:type:: SEUserType SEInterface Tag ^^^^^^^^^^^^^^^ -+-------------+-------------------------+-------------+----------+ -| Name | Description | Values | Required | -+=============+=========================+=============+==========+ -| name | Interface name | String | Yes | -+-------------+-------------------------+-------------+----------+ -| selinuxtype | SELinux type to apply | String | Yes | -| | to this interface | | | -+-------------+-------------------------+-------------+----------+ +.. xml:type:: SEInterfaceType SEPermissive Tag ^^^^^^^^^^^^^^^^ -+-------------+------------------------------------+-------------+----------+ -| Name | Description | Values | Required | -+=============+====================================+=============+==========+ -| name | SELinux type to make permissive | String | Yes | -+-------------+------------------------------------+-------------+----------+ +.. xml:type:: SEPermissiveType SEModule Tag ^^^^^^^^^^^^ -See :ref:`server-plugins-generators-semodules` +.. xml:type:: SEModuleType + +See also :ref:`server-plugins-generators-semodules`. POSIXUser Tag ------------- @@ -534,39 +382,7 @@ POSIXUser Tag 1.3.0 since they require a client tool which is unavailable in previous versions. -The POSIXUser tag allows you to create users on client machines. It -takes the following attributes: - -+-------+-----------------------+---------+-------------------------------+ -| Name | Description | Values | Default | -+=======+=======================+=========+===============================+ -| name | Username | String | None | -+-------+-----------------------+---------+-------------------------------+ -| uid | User ID number | Integer | The client sets the uid | -+-------+-----------------------+---------+-------------------------------+ -| group | Name of the user's | String | The username | -| | primary group | | | -+-------+-----------------------+---------+-------------------------------+ -| gecos | Human-readable user | String | The username | -| | name or comment | | | -+-------+-----------------------+---------+-------------------------------+ -| home | User's home directory | String | /root (for "root"); | -| | | | /home/<username> otherwise | -+-------+-----------------------+---------+-------------------------------+ -| shell | User's shell | String | /bin/bash | -+-------+-----------------------+---------+-------------------------------+ - -The group specified will automatically be created if it does not -exist, even if there is no `POSIXGroup Tag`_ for it. If you need to -specify a particular GID for the group, you must specify that in a -``POSIXGroup`` tag. - -If you with to change the default shell, you can do so with :ref:`the -Defaults plugin <server-plugins-structures-defaults>`. - -Additionally, a user may be a member of supplementary groups. These -can be specified with the ``MemberOf`` child tag of the ``POSIXUser`` -tag. +.. xml:type:: POSIXUserType For example: @@ -579,6 +395,14 @@ For example: <MemberOf>bin</MemberOf> </BoundPOSIXUser> +The group specified will automatically be created if it does not +exist, even if there is no :xml:type:`POSIXGroup tag <POSIXGroupType>` +for it. If you need to specify a particular GID for the group, you +must specify that in a ``POSIXGroup`` tag. + +If you with to change the default shell, you can do so with :ref:`the +Defaults plugin <server-plugins-structures-defaults>`. + See :ref:`client-tools-posixusers` for more information on managing users and groups. @@ -593,16 +417,7 @@ POSIXGroup Tag 1.3.0 since they require a client tool which is unavailable in previous versions. -The POSIXGroup tag allows you to create groups on client machines. It -takes the following attributes: - -+-------+-------------------+---------+-------------------------+ -| Name | Description | Values | Default | -+=======+===================+=========+=========================+ -| name | Name of the group | String | None | -+-------+-------------------+---------+-------------------------+ -| gid | Group ID number | Integer | The client sets the gid | -+-------+-------------------+---------+-------------------------+ +.. xml:type:: POSIXGroupType See :ref:`client-tools-posixusers` for more information on managing users and groups. diff --git a/doc/server/plugins/generators/semodules.txt b/doc/server/plugins/generators/semodules.txt index 4466738e6..04d72e139 100644 --- a/doc/server/plugins/generators/semodules.txt +++ b/doc/server/plugins/generators/semodules.txt @@ -37,24 +37,23 @@ For more information on this directory layout, see Entries ======= -SEModules handles ``<SELinux>`` entries with the ``module`` type. For -instance: +SEModules handles ``<SEModule>`` entries. For instance: .. code-block:: xml <Bundle name="foo"> - <SELinux type="module" name="foo.pp"/> + <SEModule name="foo.pp"/> </Bundle> The ``.pp`` extension is optional. .. note:: - If you use a ``BoundSELinux`` tag, you must *not* include the + If you use a ``BoundSEModule`` tag, you must *not* include the ``.pp`` extension. This is not recommend, though. You can also install a disabled module: .. code-block:: xml - <SELinux type="module" name="foo" disabled="true"/> + <SEModule name="foo" disabled="true"/> diff --git a/doc/server/plugins/generators/sslca.txt b/doc/server/plugins/generators/sslca.txt index cabb4d730..cab7eb233 100644 --- a/doc/server/plugins/generators/sslca.txt +++ b/doc/server/plugins/generators/sslca.txt @@ -81,7 +81,7 @@ that CA must contain full (not relative) paths. something like ``/var/lib/bcfg2/SSLCA/etc/pki/tls/private/localhost.key``. -#. Within that directory, create a ``key.xml`` file containing the +#. Within that directory, create a `key.xml`_ file containing the following: .. code-block:: xml @@ -95,7 +95,7 @@ that CA must contain full (not relative) paths. keytype, or a different number of bits. #. Similarly, create the matching directory structure for the - certificate path, and a ``cert.xml`` containinng the following: + certificate path, and a `cert.xml`_ containing the following: .. code-block:: xml @@ -110,6 +110,8 @@ that CA must contain full (not relative) paths. using the CA matching the ca attribute. ie. ca="default" will match [sslca_default] in your ``/etc/bcfg2.conf`` +.. _sslca-configuration: + Configuration ============= @@ -144,67 +146,14 @@ Only ``config`` is required. cert.xml -------- -``cert.xml`` is an XML document describing an SSL certificate -generated from an SSL key that has also been generated by SSLCA. It -honors ``Group`` and ``Client`` tags much like Bundler. It must have -a top-level ``CertInfo`` tag and can contain two types of tags: - -Cert -^^^^ - -The ``Cert`` tag explains how the certificate should be generated. -There should be at least one ``Cert`` tag, and at most one ``Cert`` -tag should apply to any given client. - -+--------------+------------------------------------------+---------+---------+ -| Attribute | Description | Values | Default | -+==============+==========================================+=========+=========+ -| key | The full path to the key to use for this | String | None | -| | certificate. This is the only required | | | -| | attribute. | | | -+--------------+------------------------------------------+---------+---------+ -| format | The format of cert to produce. Currently | 'pem' | 'pem' | -| | only pem certificates are supported. | | | -+--------------+------------------------------------------+---------+---------+ -| ca | The name of the CA (from ``bcfg2.conf``) | String | default | -| | to use to generate this certificate. | | | -+--------------+------------------------------------------+---------+---------+ -| days | Time (in days) the certificate should be | Integer | 365 | -| | valid for | | | -+--------------+------------------------------------------+---------+---------+ -| c | Override the country set in the CA | String | None | -| | config | | | -+--------------+------------------------------------------+---------+---------+ -| l | Override the location set in the CA | String | None | -| | config | | | -+--------------+------------------------------------------+---------+---------+ -| st | Override the state set in the CA config | String | None | -+--------------+------------------------------------------+---------+---------+ -| ou | Override the organizational unit set in | String | None | -| | the CA config | | | -+--------------+------------------------------------------+---------+---------+ -| o | Override the organization set in the CA | String | None | -| | config | | | -+--------------+------------------------------------------+---------+---------+ -| emailaddress | Override the email address set in the CA | String | None | -| | config | | | -+--------------+------------------------------------------+---------+---------+ -| append_chain | Append the CA chain certificate to the | Boolean | False | -| | certificate (e.g., to produce a cert in | | | -| | the format required by Nginx) | | | -+--------------+------------------------------------------+---------+---------+ - -SubjectAltName -^^^^^^^^^^^^^^ - -The ``SubjectAltName`` tag contains text giving a subject alternative -name for the certificate. Any number of ``SubjectAltName`` tags may -be used. +.. xml:schema:: sslca-cert.xsd + :linktotype: + :inlinetypes: CertType Example ^^^^^^^ -.. code-block: xml +.. code-block:: xml <CertInfo> <SubjectAltName>test.example.com</SubjectAltName> @@ -220,29 +169,14 @@ Example key.xml ------- -``key.xml`` is an XML document describing an SSL key. It also honors -``Group`` and ``Client`` tags. It contains a top-level ``KeyInfo`` -tag that contains at least one ``Key`` tag. - -Key -^^^ - -The ``Cert`` tag explains how the certificate should be generated. -There should be at least one ``Cert`` tag, and at most one ``Cert`` -tag should apply to any given client. - -+--------------+------------------------------------------+---------+---------+ -| Attribute | Description | Values | Default | -+==============+==========================================+=========+=========+ -| type | The key type | rsa|dsa | 'rsa' | -+--------------+------------------------------------------+---------+---------+ -| bits | The key length | Integer | 2048 | -+--------------+------------------------------------------+---------+---------+ +.. xml:schema:: sslca-key.xsd + :linktotype: + :inlinetypes: KeyType Example ^^^^^^^ -.. code-block: xml +.. code-block:: xml <KeyInfo> <Group name="fast"> diff --git a/doc/server/plugins/grouping/metadata.txt b/doc/server/plugins/grouping/metadata.txt index ae4ebfe32..a6ed37f8e 100644 --- a/doc/server/plugins/grouping/metadata.txt +++ b/doc/server/plugins/grouping/metadata.txt @@ -10,27 +10,28 @@ The metadata mechanism has two types of information, client metadata and group metadata. The client metadata describes which top level group a client is associated with.The group metadata describes groups in terms of what bundles and other groups they include. Group data and -clients' memberships are reflected in the ``Metadata/groups.xml`` and -``Metadata/clients.xml`` files, respectively. +clients' memberships are reflected in the `groups.xml`_ and +`clients.xml`_ files, respectively. Usage of Groups in Metadata =========================== -Clients are assigned membership of groups in the Metadata descriptions. -Clients can be directly assigned to *'profile'* or *'public'* groups. -Client membership of all other groups is by those groups being -associated with the profile or public groups. This file can be indirectly -modified from clients through use of the ``-p`` flag to ``bcfg2``. +Clients are assigned membership of groups in the Metadata +descriptions. Clients can be directly assigned to *'profile'* or +*'public'* groups. Client membership of all other groups is by those +groups being associated with the profile or public groups. This file +can be indirectly modified from clients through use of the ``-p`` flag +to ``bcfg2``. -Clients are associated with profile groups in ``Metadata/clients.xml`` as -shown below. +Clients are associated with profile groups in `clients.xml`_ +as shown below. .. _server-plugins-grouping-metadata-clients-xml: -Metadata/clients.xml -==================== +clients.xml +=========== -The ``Metadata/clients.xml`` file contains the mappings of Profile Groups +The ``clients.xml`` file contains the mappings of Profile Groups to clients. The file is just a series of *<Client />* tags, each of which describe one host. A sample file is below: @@ -46,63 +47,7 @@ describe one host. A sample file is below: </Client> </Clients> -Clients Tag ------------ - -The Clients tag has the following possible attributes: - -+---------+-----------------------+--------+ -| Name | Description | Values | -+=========+=======================+========+ -| version | Client schema version | String | -+---------+-----------------------+--------+ - -Client Tag ----------- - -Each entry in ``clients.xml`` **must** have the following properties: - -+---------+---------------------------------------+--------+ -| Name | Description | Values | -+=========+=======================================+========+ -| name | Host name of client. This needs to be | String | -| | the name (possibly a FQDN) returned | | -| | by a reverse lookup on the connecting | | -| | IP address. | | -+---------+---------------------------------------+--------+ -| profile | Profile group name to associate this | String | -| | client with. | | -+---------+---------------------------------------+--------+ - -Additionally, the following properties can be specified: - -+----------+----------------------------------------+----------------+ -| Name | Description | Values | -+==========+========================================+================+ -| Alias | Alternative name and address for the | XML Element | -| | client. | | -+----------+----------------------------------------+----------------+ -| address | Establishes an extra IP address that | ip address | -| | resolves to this client. | | -+----------+----------------------------------------+----------------+ -| floating | Allows requests to come from any IP, | true|false | -| | rather than requiring requests to come | | -| | from an IP associated with the client | | -+----------+----------------------------------------+----------------+ -| password | Establishes a per-node password that | String | -| | can be used instead of the global | | -| | password. | | -+----------+----------------------------------------+----------------+ -| secure | Requires the use of the per-client | true|false | -| | password for this client. | | -+----------+----------------------------------------+----------------+ -| uuid | Establishes a per-node name that can | String | -| | be used to bypass dns-based client | | -| | resolution. | | -+----------+----------------------------------------+----------------+ - -Floating can also be configured by setting ``location="floating"``, -but that is deprecated. +.. xml:schema:: clients.xsd For detailed information on client authentication see :ref:`appendix-guides-authentication` @@ -110,47 +55,46 @@ For detailed information on client authentication see .. _server-plugins-grouping-metadata-clients-database: Clients Database -~~~~~~~~~~~~~~~~ +---------------- .. versionadded:: 1.3.0 It is also possible to store client records in a database rather than -writing back to ``clients.xml``. This provides several advantages: +writing back to `clients.xml`_. This provides several advantages: -* ``clients.xml`` will never be written by the server, removing an +* `clients.xml`_ will never be written by the server, removing an area of contention between the user and server. -* ``clients.xml`` can be removed entirely for many sites. +* `clients.xml`_ can be removed entirely for many sites. * The Bcfg2 client list can be queried by other machines without - obtaining and parsing ``clients.xml``. + obtaining and parsing `clients.xml`_. * A single client list can be shared amongst multiple Bcfg2 servers. In general, storing clients in the database works almost the same as -``clients.xml``. ``groups.xml`` is parsed identically. If -``clients.xml`` is present, it is parsed, but ``<Client>`` tags in -``clients.xml`` *do not* assert client existence; they are only used +`clients.xml`_. `groups.xml`_ is parsed identically. If +`clients.xml`_ is present, it is parsed, but ``<Client>`` tags in +`clients.xml`_ *do not* assert client existence; they are only used to set client options *if* the client exists (in the database). That -is, the two purposes of ``clients.xml`` -- to track which clients +is, the two purposes of `clients.xml`_ -- to track which clients exist, and to set client options -- have been separated. -With the improvements in ``groups.xml`` parsing in 1.3, client groups -can now be set directly in ``groups.xml`` with ``<Client>`` tags. (See -:ref:`metadata-client-tag` for more details.) As a result, -``clients.xml`` is only necessary if you need to set -options (e.g., aliases, floating clients, per-client passwords, etc.) -on clients. +With the improvements in `groups.xml`_ parsing in 1.3, client groups +can now be set directly in `groups.xml`_ with ``<Client>`` tags. (See +:xml:type:`clientType` for more details.) As a result, `clients.xml`_ +is only necessary if you need to set options (e.g., aliases, floating +clients, per-client passwords, etc.) on clients. -To use the database backend instead of ``clients.xml``, set +To use the database backend instead of `clients.xml`_, set ``use_database`` in the ``[metadata]`` section of ``bcfg2.conf`` to ``true``. You will also need to configure the :ref:`Global Server Database Settings <server-database>`. -The ``clients.xml``-based model remains the default. +The `clients.xml`_-based model remains the default. -Metadata/groups.xml -=================== +groups.xml +========== -The ``Metadata/groups.xml`` file contains Group and Profile -definitions. Here's a simple ``Metadata/groups.xml`` file: +The ``groups.xml`` file contains Group and Profile definitions. Here's +a simple ``groups.xml`` file: .. code-block:: xml @@ -197,8 +141,8 @@ groups; a RHEL 6 client that is a member of the ``mail-server`` profile group would be a member of the ``apache-server``, ``nfs-client``, ``server``, and ``postfix-server`` groups. -Client tags in ``groups.xml`` allow you to supplement the profile -group declarations in ``clients.xml`` and/or client group assignments +Client tags in `groups.xml`_ allow you to supplement the profile +group declarations in `clients.xml`_ and/or client group assignments with the :ref:`server-plugins-grouping-grouppatterns` plugin. They should be used sparingly. (They are more useful when you are using the database backend for client records.) @@ -235,101 +179,19 @@ groups: Nested Group conditionals, Client tags, and negated Group tags are all new in 1.3.0. -Order of ``groups.xml`` does not matter. - -Groups describe clients in terms for abstract, disjoint aspects. Groups -can be combined to form complex descriptions of clients that use -configuration commonality and inheritance. Groups have several attributes, -described below: - - -Metadata Groups Tag -------------------- - -The Groups tag has the following possible attributes: - -+----------+---------------------------------+--------+ -| Name | Description | Values | -+==========+=================================+========+ -| version | Group schema version | String | -+----------+---------------------------------+--------+ -| origin | URL of master version | String | -| | (for common repository) | | -+----------+---------------------------------+--------+ -| revision | Master version control revision | String | -+----------+---------------------------------+--------+ - -Metadata Group Tag ------------------- - -The Group Tag has the following possible attributes: - -+----------+----------------------------------------------+--------------+ -| Name | Description | Values | -+==========+==============================================+==============+ -| name | Name of the group | String | -+----------+----------------------------------------------+--------------+ -| profile | If a client can be directly associated with | True|False | -| | this group | | -+----------+----------------------------------------------+--------------+ -| public | If a client can freely associate itself with | True|False | -| | this group. For use with the ``bcfg2 -p`` | | -| | option on the client. | | -+----------+----------------------------------------------+--------------+ -| category | A group can only contain one instance of a | String | -| | group in any one category. This provides the | | -| | basis for representing groups which are | | -| | conjugates of one another in a rigorous way. | | -+----------+----------------------------------------------+--------------+ -| default | Set as the profile to use for clients that | True|False | -| | are not associated with a profile in | | -| | ``clients.xml`` | | -+----------+----------------------------------------------+--------------+ -| comment | English text description of group | String | -+----------+----------------------------------------------+--------------+ -| negate | When used as a conditional, only apply the | True|False | -| | children if the named group does not match. | | -| | When used as a declaration, do not apply | | -| | the named group to matching clients. | | -+----------+----------------------------------------------+--------------+ - -The ``profile``, ``public``, ``category``, ``default``, and -``comment`` attributes are only parsed if a Group tag either a) is the -direct child of a Groups tag (i.e., at the top level of an XML file); -or b) has no children. This matches legacy behavior in Bcfg2 1.2 and -earlier. - -Groups can also contain other groups, clients, and bundles. - -.. _metadata-client-tag: - -Metadata Client Tag -------------------- - -The Client Tag has the following possible attributes: - -+----------+-----------------------------------------------+--------------+ -| Name | Description | Values | -+==========+===============================================+==============+ -| name | Name of the client | String | -+----------+-----------------------------------------------+--------------+ -| negate | Only apply the child tags if the named client | True|False | -| | does not match. | | -+----------+-----------------------------------------------+--------------+ - -Clients can also contain groups, other clients (although that's likely -nonsensical), and bundles. - - -Use of XInclude -=============== +.. xml:schema:: metadata.xsd + + +XInclude +======== + +.. versionadded:: 0.9.0 `XInclude <http://www.w3.org/TR/xinclude/>`_ is a W3C specification -for the inclusion of external XML documents into XML source -files. Much like the use of ``#include`` in C, this allows complex -definitions to be split into smaller, more manageable pieces. As of -bcfg2-0.9.0pre1, the `Metadata`_ plugin supports the use of XInclude -specifications to split the ``clients.xml`` and ``groups.xml`` +for the inclusion of external XML documents into XML source files, +allowing complex definitions to be split into smaller, more manageable +pieces. The `Metadata`_ plugin supports the use of XInclude +specifications to split the `clients.xml`_ and `groups.xml`_ files. This mechanism allows the following specification to produce useful results: @@ -358,7 +220,7 @@ Metadata Caching Client metadata can be cached in order to improve performance. This is particularly important if you have lots of templates that use -metadata from other clients (e.g., with the MetadataQuery interface +metadata from other clients (e.g., with the `MetadataQuery`_ interface described below. See :ref:`server-caching` for a full description of the caching features available. @@ -393,7 +255,7 @@ A special client metadata class is available to +------------+------------------------------------------------+---------------+ | connectors | connector plugins known to this client | List | +------------+------------------------------------------------+---------------+ -| query | MetadataQuery object | MetadataQuery | +| query | `MetadataQuery`_ object | MetadataQuery | +------------+------------------------------------------------+---------------+ diff --git a/doc/server/plugins/structures/bundler/index.txt b/doc/server/plugins/structures/bundler/index.txt index 1cc287ebd..a19959e66 100644 --- a/doc/server/plugins/structures/bundler/index.txt +++ b/doc/server/plugins/structures/bundler/index.txt @@ -154,6 +154,8 @@ Several variables are pre-defined inside templates: groups, you *must* use a Genshi conditional, not a ``<Group>`` tag. The same caveats apply to ``<Client>`` tags. +See also the :ref:`xml-genshi-reference`. + Troubleshooting --------------- |