diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/appendix/guides/bootstrap.txt | 6 | ||||
| -rw-r--r-- | doc/appendix/guides/converging_rhel5.txt | 4 | ||||
| -rw-r--r-- | doc/appendix/guides/fedora.txt | 28 | ||||
| -rw-r--r-- | doc/appendix/guides/ubuntu.txt | 58 | ||||
| -rw-r--r-- | doc/client/agent.txt | 2 | ||||
| -rw-r--r-- | doc/client/tools/actions.txt | 6 | ||||
| -rw-r--r-- | doc/development/plugins.txt | 2 | ||||
| -rw-r--r-- | doc/help/troubleshooting.txt | 4 | ||||
| -rw-r--r-- | doc/server/configurationentries.txt | 22 | ||||
| -rw-r--r-- | doc/server/info.txt | 8 | ||||
| -rw-r--r-- | doc/server/plugins/generators/decisions.txt | 1 | ||||
| -rw-r--r-- | doc/server/plugins/generators/packages.txt | 239 | ||||
| -rw-r--r-- | doc/server/plugins/generators/rules.txt | 67 | ||||
| -rw-r--r-- | doc/server/plugins/generators/tcheetah.txt | 18 | ||||
| -rw-r--r-- | doc/server/plugins/generators/tgenshi/clientsxml.txt | 6 | ||||
| -rw-r--r-- | doc/server/plugins/generators/tgenshi/test.txt | 34 | ||||
| -rw-r--r-- | doc/server/plugins/grouping/metadata.txt | 4 | ||||
| -rw-r--r-- | doc/server/plugins/structures/bundler/index.txt | 69 | ||||
| -rw-r--r-- | doc/server/plugins/structures/defaults.txt | 31 |
19 files changed, 403 insertions, 206 deletions
diff --git a/doc/appendix/guides/bootstrap.txt b/doc/appendix/guides/bootstrap.txt index b9b5f318e..a5133c4c1 100644 --- a/doc/appendix/guides/bootstrap.txt +++ b/doc/appendix/guides/bootstrap.txt @@ -34,6 +34,6 @@ you to specify the options that are normally found in the client's bcfg2 -x password -p basic -S https://bcfg2-server:6789 The above command will add the client to ``Metadata/clients.xml`` with the -profile *basic*. Generally, the configuration given to the client by the -bcfg2 server in this initial run will include the ``/etc/bcfg2.conf`` file -so that the client won't need to specify these options on future runs. +profile *basic*. Generally, you should include ``/etc/bcfg2.conf`` in the +configuration given to the client by the bcfg2 server in this initial run +to avoid specifying these options on future runs. diff --git a/doc/appendix/guides/converging_rhel5.txt b/doc/appendix/guides/converging_rhel5.txt index d6a9d2d1c..1b52e198d 100644 --- a/doc/appendix/guides/converging_rhel5.txt +++ b/doc/appendix/guides/converging_rhel5.txt @@ -19,7 +19,7 @@ Unmanaged entries * Package (top-level) #. Enable the "Packages" plugin in ``/etc/bcfg2.conf``, and configure - the Yum repositories in ``/var/lib/bcfg2/Packages/config.xml``. + the Yum repositories in ``/var/lib/bcfg2/Packages/sources.xml``. #. If a package is unwanted, remove it:: sudo yum remove PACKAGE @@ -29,7 +29,7 @@ Unmanaged entries * Package (dependency) #. Ensure the Yum repository sources configured in - ``/var/lib/bcfg2/Packages/config.xml`` are correct. + ``/var/lib/bcfg2/Packages/sources.xml`` are correct. #. Ensure the Yum repositories themselves are up-to-date with the main package and dependencies. #. Rebuild the Packages plugin cache:: diff --git a/doc/appendix/guides/fedora.txt b/doc/appendix/guides/fedora.txt index 7aaa02815..9d11414ef 100644 --- a/doc/appendix/guides/fedora.txt +++ b/doc/appendix/guides/fedora.txt @@ -190,28 +190,32 @@ Setup the :ref:`server-plugins-generators-packages` plugin ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ First, replace **Pkgmgr** with **Packages** in the plugins -line of ``bcfg2.conf``. Then create `Packages/` directory in +line of ``bcfg2.conf``. Then create a `Packages/` directory in ``/var/lib/bcfg2`` :: $ su -c 'mkdir /var/lib/bcfg2/Packages' -Create a ``config.xml`` file for the packages in -``/var/lib/bcfg2/Packages`` with the following content. Choose a -mirror near your location according the `Mirror list`_ . +Create a ``packages.conf`` in the ``/var/lib/bcfg2/Packages`` directory +with the following contents:: + + [global] + +Create a ``sources.xml`` file for the packages in +``/var/lib/bcfg2/Packages`` with the following content. Choose a mirror +near your location according the `Mirror list`_ . .. _Mirror list: http://mirrors.fedoraproject.org/publiclist/ .. code-block:: xml <Sources> - <YUMSource> - <Group>fedora-13</Group> - <URL>ftp://fedora.tu-chemnitz.de/pub/linux/fedora/linux/releases/</URL> - <Version>13</Version> - <Component>Fedora</Component> - <Arch>i386</Arch> - <Arch>x86_64</Arch> - </YUMSource> + <Group name="fedora-13"> + <Source type="yum" url="ftp://fedora.tu-chemnitz.de/pub/linux/fedora/linux/releases/" version="13"> + <Component>Fedora</Component> + <Arch>i386</Arch> + <Arch>x86_64</Arch> + <Source> + </Group> </Sources> diff --git a/doc/appendix/guides/ubuntu.txt b/doc/appendix/guides/ubuntu.txt index 6655a3b04..fe5564d19 100644 --- a/doc/appendix/guides/ubuntu.txt +++ b/doc/appendix/guides/ubuntu.txt @@ -152,39 +152,33 @@ Create Packages layout (as per :ref:`packages-exampleusage`) in .. code-block:: xml root@lucid:~# mkdir /var/lib/bcfg2/Packages - root@lucid:~# cat /var/lib/bcfg2/Packages/config.xml + root@lucid:~# cat /var/lib/bcfg2/Packages/packages.conf + [global] + root@lucid:~# cat /var/lib/bcfg2/Packages/sources.xml <Sources> - <APTSource> - <Group>ubuntu-lucid</Group> - <URL>http://us.archive.ubuntu.com/ubuntu</URL> - <Version>lucid</Version> - <Component>main</Component> - <Component>multiverse</Component> - <Component>restricted</Component> - <Component>universe</Component> - <Arch>amd64</Arch> - <Arch>i386</Arch> - </APTSource> - <APTSource> - <Group>lucid</Group> - <URL>http://archive.ubuntu.com/ubuntu</URL> - <Version>lucid-updates</Version> - <Component>main</Component> - <Component>multiverse</Component> - <Component>restricted</Component> - <Component>universe</Component> - <Arch>amd64</Arch> - </APTSource> - <APTSource> - <Group>lucid</Group> - <URL>http://security.ubuntu.com/ubuntu</URL> - <Version>lucid-security</Version> - <Component>main</Component> - <Component>multiverse</Component> - <Component>restricted</Component> - <Component>universe</Component> - <Arch>amd64</Arch> - </APTSource> + <Group name="lucid"> + <Source type="apt" url="http://archive.ubuntu.com/ubuntu" version="lucid"> + <Component>main</Component> + <Component>multiverse</Component> + <Component>restricted</Component> + <Component>universe</Component> + <Arch>amd64</Arch> + </Source> + <Source type="apt" url="http://archive.ubuntu.com/ubuntu" version="lucid-updates"> + <Component>main</Component> + <Component>multiverse</Component> + <Component>restricted</Component> + <Component>universe</Component> + <Arch>amd64</Arch> + </Source> + <Source type="apt" url="http://security.ubuntu.com/ubuntu" version="lucid-security"> + <Component>main</Component> + <Component>multiverse</Component> + <Component>restricted</Component> + <Component>universe</Component> + <Arch>amd64</Arch> + </Source> + </Group> </Sources> Due to the :ref:`server-plugins-generators-packages-magic-groups`, diff --git a/doc/client/agent.txt b/doc/client/agent.txt index ef152133e..770c2a41c 100644 --- a/doc/client/agent.txt +++ b/doc/client/agent.txt @@ -24,7 +24,7 @@ is pretty easy: The key fingerprint is: aa:25:9b:a7:10:60:f3:eb:2b:ae:4b:1a:42:1b:63:5d desai@ubik -#. Add this this public key to root's authorized_keys file, with several +#. Add this public key to root's authorized_keys file, with several commands prepended to it:: command="/usr/sbin/bcfg2 -q <other options>",no-port-forwarding,no-X11-forwarding,no-pty,no-agent-forwarding,from="<bcfg2-server ipaddr>" <pub key> diff --git a/doc/client/tools/actions.txt b/doc/client/tools/actions.txt index 11922b00d..49488dfbe 100644 --- a/doc/client/tools/actions.txt +++ b/doc/client/tools/actions.txt @@ -20,7 +20,8 @@ so they can be centrally observed. Actions look like: name='name' command='cmd text' when='always|modified' - status='ignore|check'/> + status='ignore|check' + build='true|false'/> +-----------+------------------+-------------------------------------------+ | Attribute | Values | Meaning | @@ -37,6 +38,9 @@ so they can be centrally observed. Actions look like: | status | ignore, check | If the return code of the action | | | | should be reported or not | +-----------+------------------+-------------------------------------------+ +| build | true, false | Also execute the action in build mode | +| | | (default: true) | ++-----------+------------------+-------------------------------------------+ Note that the status attribute tells the bcfg2 client to ignore return status, causing failures to still not be centrally reported. If diff --git a/doc/development/plugins.txt b/doc/development/plugins.txt index e6a5a73a0..15b512365 100644 --- a/doc/development/plugins.txt +++ b/doc/development/plugins.txt @@ -175,7 +175,7 @@ Example Connector def get_additional_data(self, metadata): mydata = {} - for data in self.store.entries['foo.xml'].data.get("foo", []): + for data in self.store.entries['foo.xml'].xdata.get("foo", []): mydata[data] = "bar" diff --git a/doc/help/troubleshooting.txt b/doc/help/troubleshooting.txt index 7aeb0f247..b964154e0 100644 --- a/doc/help/troubleshooting.txt +++ b/doc/help/troubleshooting.txt @@ -202,7 +202,7 @@ Server Errors | Packages: No matching | Server | None of the sources | [s12]_ | | sources for client | | defined in the | | | <clientname>; improper group | | Package plugin's | | -| memberships? | | ``config.xml`` | | +| memberships? | | ``sources.xml`` | | | | | apply to the client | | +------------------------------+----------+---------------------+--------------+ @@ -222,7 +222,7 @@ Server Errors section of ``bcfg2.conf``. .. [s8] For packages listed other than **gpg-pubkey**, this error means that the Packages plugin is unable to find the package in any of - the sources listed in ``Packages/config.xml``. The issue often + the sources listed in ``Packages/sources.xml``. The issue often arises when the client is not in one of the groups necessary for the Source listed. In the case of gpg-pubkey, you can safely ignore the message as the Packages plugin has no knowledge of diff --git a/doc/server/configurationentries.txt b/doc/server/configurationentries.txt index fbce092b9..be9ea987c 100644 --- a/doc/server/configurationentries.txt +++ b/doc/server/configurationentries.txt @@ -22,17 +22,17 @@ entries used by Bcfg2. Non-POSIX entries ================= -+-------------+---------------------+-----------------------------+ -| TagName | Description | Attributes | -+=============+=====================+=============================+ -| Action | Command | name, command, when, timing | -+-------------+---------------------+-----------------------------+ -| Package | Software Packages | name, type, version, url | -+-------------+---------------------+-----------------------------+ -| PostInstall | PostInstall command | name | -+-------------+---------------------+-----------------------------+ -| Service | System Services | name, type, status, target | -+-------------+---------------------+-----------------------------+ ++-------------+---------------------+--------------------------------------------+ +| TagName | Description | Attributes | ++=============+=====================+============================================+ +| Action | Command | name, command, when, timing, status, build | ++-------------+---------------------+--------------------------------------------+ +| Package | Software Packages | name, type, version, url | ++-------------+---------------------+--------------------------------------------+ +| PostInstall | PostInstall command | name | ++-------------+---------------------+--------------------------------------------+ +| Service | System Services | name, type, status, target | ++-------------+---------------------+--------------------------------------------+ .. note:: diff --git a/doc/server/info.txt b/doc/server/info.txt index c58bbd7a3..97bb92a0d 100644 --- a/doc/server/info.txt +++ b/doc/server/info.txt @@ -94,7 +94,9 @@ files are XML, and work similarly to those used by :ref:`Rules The following specifies a different global set of permissions (root/sys/0651) than on clients in group webserver or named -"foo.example.com" (root/root/0652):: +"foo.example.com" (root/root/0652). + +.. code-block:: xml <FileInfo> <Client name='foo.example.com'> @@ -107,7 +109,9 @@ The following specifies a different global set of permissions </FileInfo> The following specifies a different set of permissions depending on -the path of the file:: +the path of the file. + +.. code-block:: xml <FileInfo> <Path name="/etc/bcfg2-web.conf"> diff --git a/doc/server/plugins/generators/decisions.txt b/doc/server/plugins/generators/decisions.txt index d75a9fede..acb1de6ee 100644 --- a/doc/server/plugins/generators/decisions.txt +++ b/doc/server/plugins/generators/decisions.txt @@ -67,7 +67,6 @@ can add comments such as this:: <!-- vim: set ft=xml : --> -============= Decision Mode ============= diff --git a/doc/server/plugins/generators/packages.txt b/doc/server/plugins/generators/packages.txt index fb145876c..2299da3ee 100644 --- a/doc/server/plugins/generators/packages.txt +++ b/doc/server/plugins/generators/packages.txt @@ -23,32 +23,43 @@ through those channels. Packages is the only plugin that uses "magic groups". Most plugins operate based on client group memberships, without any concern for the particular names chosen for groups by the user. The Packages plugin is -the sole exception to this rule. Packages needs to "know" two different -sorts of facts about clients. The first is the basic OS/distro of the -client, enabling classes of sources. The second is the architecture of -the client, enabling sources for a given architecture. In addition to -these magic groups, each source may also specify a non-magic group to -limit the source's applicability to group member clients. - -+-----------+----------+--------------+ -| Source | OS Group | Architecture | -+===========+==========+==============+ -| APTSource | debian | i386 | -+-----------+----------+--------------+ -| APTSource | ubuntu | amd64 | -+-----------+----------+--------------+ -| APTSource | nexenta | | -+-----------+----------+--------------+ -| APTSource | apt | | -+-----------+----------+--------------+ -| YUMSource | redhat | i386 | -+-----------+----------+--------------+ -| YUMSource | centos | x86_64 | -+-----------+----------+--------------+ -| YUMSource | fedora | | -+-----------+----------+--------------+ -| YUMSource | yum | | -+-----------+----------+--------------+ +the sole exception to this rule. Packages needs to "know" two +different sorts of facts about clients. The first is the basic +OS/distro of the client, enabling classes of sources. The second is +the architecture of the client, enabling sources for a given +architecture. In addition to these magic groups, each source may also +specify non-magic groups to limit the source's applicability to group +member clients. + ++--------+----------+--------------+ +| Source | OS Group | Architecture | ++========+==========+==============+ +| Apt | debian | i386 | ++--------+----------+--------------+ +| Apt | ubuntu | amd64 | ++--------+----------+--------------+ +| Apt | nexenta | | ++--------+----------+--------------+ +| Apt | apt | | ++--------+----------+--------------+ +| Yum | redhat | i386 | ++--------+----------+--------------+ +| Yum | centos | x86_64 | ++--------+----------+--------------+ +| Yum | fedora | | ++--------+----------+--------------+ +| Yum | yum | | ++--------+----------+--------------+ + +.. note:: + + .. versionadded:: 1.2.0 + + Magic OS groups can be disabled in Bcfg2 1.2 and greater by setting + ``magic_groups`` to ``0`` in ``Packages/packages.conf``. This may + give you greater flexibility in determining which source types to + use for which OSes. Magic architecture groups cannot be disabled. + Limiting sources to groups ========================== @@ -113,9 +124,9 @@ plugin. Disabling dependency resolution ------------------------------- -.. versionadded:: 1.2.0 +.. versionadded:: 1.1.0 -Dependency resolution can now be disabled by adding this to +Dependency resolution can be disabled by adding this to ``Packages/packages.conf`` in the ``global`` section:: [global] @@ -126,8 +137,6 @@ All metadata processing can be disabled as well:: [global] metadata=disabled -.. _packages-exampleusage: - Blacklisting faulty dependencies -------------------------------- @@ -136,18 +145,20 @@ 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: - -.. code-block:: xml +and should look like the following:: <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. + Handling GPG Keys ----------------- .. versionadded:: 1.2.0 -Packages can automatically handle GPG signing keys for Yum +Packages can automatically handle GPG signing keys for Yum and Pulp repositories. Simply specify the URL to the GPG key(s) for a repository in ``sources.xml``:: @@ -163,11 +174,17 @@ With the keys specified thusly, Packages will include the keys in the generated yum config file, and will ensure that the keys are imported on the client. +There is no need to specify ``<GPGKey>`` tags for :ref:``Pulp sources +<pulp-source-support>``; that data is pulled directly from the Pulp +REST API. + +.. _packages-exampleusage: + Example usage ============= -Create a config.xml file in the Packages directory that looks something -like this:: +Create a ``sources.xml`` file in the Packages directory that looks +something like this:: <Sources> <Group name="ubuntu-intrepid"> @@ -193,7 +210,9 @@ like this:: 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.:: + e.g.: + + .. code-block:: xml <Source type="apt" recommended="true" ...> @@ -209,6 +228,7 @@ Yum sources can be similarly specified:: <Component>extras</Component> <Arch>i386</Arch> <Arch>x86_64</Arch> + <GPGKey>http://mirror.centos.org/centos/RPM-GPG-KEY-CentOS-5</GPGKey> </Source> </Group> </Sources> @@ -216,8 +236,21 @@ Yum sources can be similarly specified:: For sources with a **URL** attribute, the **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:: + + <Sources> + <Group name="centos-6-x86_64"> + <Source type="yum" pulp_id="centos-6-x86_64-os"/> + <Source type="yum" pulp_id="centos-6-x86_64-updates"/> + <Source type="yum" pulp_id="centos-6-x86_64-extras"/> + </Group> + </Sources> + .. note:: There is also a rawurl attribute for specifying sources that - don't follow the conventional layout:: + don't follow the conventional layout. + + .. code-block:: xml <Sources> <Group name="centos5.4"> @@ -255,7 +288,7 @@ Configuration Updates ===================== Packages will reload its configuration upon an explicit command via -bcfg2-admin.:: +bcfg2-admin:: [0:3711] bcfg2-admin xcmd Packages.Refresh True @@ -272,9 +305,13 @@ will report information like:: Packages: Updating http://mirror.centos.org/centos/5/extras/x86_64/repodata/filelists.xml.gz Packages: Updating http://mirror.centos.org/centos/5/extras/x86_64/repodata/primary.xml.gz -Once line per file download needed. ``Packages/sources.xml`` will be reloaded -at this time, so any source specification changes (new or modified -sources in this file) will be reflected by the server at this point. +Once line per file download needed. ``Packages/sources.xml`` will +be reloaded at this time, so any source specification changes (new +or modified sources in this file) will be reflected by the server at +this point. + +This process is much, much faster if you use the :ref:`native yum +library support <native-yum-libraries>`. Soft reload ----------- @@ -287,6 +324,9 @@ download only missing sources.:: [0:3711] bcfg2-admin xcmd Packages.Reload True +This is done automatically any time ``Packages/sources.xml`` is +updated. + Availability ============ @@ -317,6 +357,7 @@ need to use :ref:`BoundEntries <boundentries>`, e.g.:: type="yum" verify="false"/> +.. _generating-client-configs: Generating Client APT/Yum Configurations ======================================== @@ -332,7 +373,7 @@ to the yum config file you want to generate:: Then add the corresponding Path entry to your Yum bundle. -.. versionadded:: 1.2.0 +.. versionadded:: 1.1.0 APT repository information can be generated automatically from software sources using :doc:`./tgenshi/index` or :doc:`./tcheetah`. A @@ -346,6 +387,99 @@ list of source urls are exposed in the client's metadata as {% end %}\ +.. _native-yum-libraries: + +Using Native Yum Libraries +========================== + +.. versionadded:: 1.2.0 + +By default, Bcfg2 uses an internal implementation of Yum's dependency +resolution and other routines so that the Bcfg2 server can be run on a +host that does not support Yum itself. If you run the Bcfg2 server on +a machine that does have Yum libraries, however, you can enable use of +those native libraries in Bcfg2 by setting ``use_yum_libraries`` to +``1`` in the ``[yum]`` section of ``Packages/packages.conf``. + +Benefits to this include: + +* Much lower memory usage by the ``bcfg2-server`` process. +* Much faster ``Packages.Refresh`` behavior. +* More accurate dependency resolution. +* Support for package groups. + +Drawbacks include: + +* More disk I/O. In some cases, you may have to raise the open file + limit for the user who runs your Bcfg2 server process, particularly + if you have a lot of repositories. +* Resolution of package dependencies is slower in some cases, + particularly after running ``Packages.Refresh``. + +Setting Yum Options +------------------- + +In ``Packages/packages.conf``, any options you set in the ``[yum]`` +section other than ``use_yum_libraries`` will be passed along verbatim +to the configuration of the Yum objects used in the Bcfg2 server. The +following options are set by default, and should not generally be +overridden: + +* ``cachedir`` is set to a hashed value unique to each distinct Yum + configuration. Don't set this unless you know what you're doing. +* ``keepcache`` is set to ``0``; there is no benefit to changing this. +* ``sslverify`` is set to ``0``; change this if you know what you're + doing. +* ``reposdir`` is set to ``/dev/null`` to prevent the server's Yum + configuration from being read; do not change this. + +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:: + + <Package group="SNMP Support"/> + <Package group="system-management-snmp"/> + +.. _pulp-source-support: + +Pulp Support +============ + +.. versionadded:: 1.2.0 + +Bcfg2 contains explicit support for repositories managed by Pulp +(http://pulpproject.org/). 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:: + + <Sources> + <Group name="centos-6-x86_64"> + <Source type="yum" pulp_id="centos-6-x86_64-os"/> + <Source type="yum" pulp_id="centos-6-x86_64-updates"/> + <Source type="yum" pulp_id="centos-6-x86_64-extras"/> + </Group> + </Sources> + +Pulp sources require some additional configuration. First, the Bcfg2 +server must have a valid ``/etc/pulp/consumer/consumer.conf`` that is +readable by the user your Bcfg2 server runs as; the Pulp server , +URLs, and so on, are determined from this. + +Secondly, in ``Packages/packages.conf`` you must set the following +options in the ``[pulp]`` section: + +* ``username`` and ``password``: The username and password of a Pulp + user that will be used to register new clients and bind them to + repositories. Membership in the default ``consumer-users`` role is + sufficient. + +Bcfg2 clients using Pulp sources will be registered to the Pulp server +as consumers, and will be bound to the appropriate repositories. + Debugging unexpected behavior ============================= @@ -463,7 +597,7 @@ packages.conf ``packages.conf`` contains miscellaneous configuration options for the Packages plugin. It understands the following directives: -"global" section +[global] section ---------------- * ``resolver``: Disable dependency resolution. Default is "enabled". @@ -487,3 +621,20 @@ Packages plugin. It understands the following directives: to "true", whereupon Packages will import the keys into the server's key chain. Python RPM libraries must be installed for this to work. +[yum] section +------------- + +* ``use_yum_libraries``: Whether or not to use the :ref:`native yum + library support <native-yum-libraries>`. Default is ``0`` (false). + +All other options in the ``[yum]`` section will be passed along +verbatim to the Yum configuration if you are using the native Yum +library support. + +[pulp] section +-------------- + +* ``username`` and ``password``: The username and password of a Pulp + user that will be used to register new clients and bind them to + repositories. Membership in the default ``consumer-users`` role is + sufficient. diff --git a/doc/server/plugins/generators/rules.txt b/doc/server/plugins/generators/rules.txt index 6bc407371..925ee6419 100644 --- a/doc/server/plugins/generators/rules.txt +++ b/doc/server/plugins/generators/rules.txt @@ -115,29 +115,29 @@ See :ref:`client-tools-actions` Service Tag ----------- -+------------+-------------------------------+-----------------------------------------------------+ -| Name | Description | Values | -+============+===============================+=====================================================+ -| mode | Per Service Mode (New in 1.0) | (manual | default | supervised | interactive_only ) | -+------------+-------------------------------+-----------------------------------------------------+ -| name | Service name or regular | String or regex | -| | expression | | -+------------+-------------------------------+-----------------------------------------------------+ -| 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. | | -+------------+-------------------------------+-----------------------------------------------------+ -| sequence | Order for service startup | integer | -| | (debian services only) | | -+------------+-------------------------------+-----------------------------------------------------+ -| parameters | Pass parameters to service | String | -| | (Upstart services only) | | -+------------+-------------------------------+-----------------------------------------------------+ ++------------+-------------------------------+---------------------------------------------------------+ +| Name | Description | Values | ++============+===============================+=========================================================+ +| mode | Per Service Mode (New in 1.0) | (manual | default | supervised | interactive_only ) | ++------------+-------------------------------+---------------------------------------------------------+ +| name | Service name or regular | String or regex | +| | expression | | ++------------+-------------------------------+---------------------------------------------------------+ +| 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) | | ++------------+-------------------------------+---------------------------------------------------------+ Service mode descriptions ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -355,28 +355,11 @@ Using Regular Expressions in Rules ================================== The ``name`` attribute in Rules supports the use of regular -expressions to match multiple abstract configuration entries. For -instance, to make all Service entries use the ``systemd`` -tool on Fedora 15 and the ``chkconfig`` tool on Fedora 14, you could -do:: - - <Rules priority="0"> - <Group name="fedora-15"> - <Service name=".*" type="systemd"/> - </Group> - <Group name="fedora-14"> - <Service name=".*" type="chkconfig"/> - </Group> - </Rules> +expressions to match multiple abstract configuration entries. Regular expressions are anchored at both ends, so ``<Service name="bcfg2".../>`` will *not* match a Service named ``bcfg2-server``; you'd have to explicitly specify ``<Service name="bcfg2.*".../>``. Note that only one Rule can apply to any abstract entry, so you cannot -specify multiple regexs to match the same rule. In the use case -above, you would have to specify the services fully (except for type) -in the bundles. - -Attributes specified in a bundle have precedence over attributes -specified in Rules, so you can use Rules to set defaults. +specify multiple regexs to match the same rule. diff --git a/doc/server/plugins/generators/tcheetah.txt b/doc/server/plugins/generators/tcheetah.txt index ef8bb5513..29fd7affe 100644 --- a/doc/server/plugins/generators/tcheetah.txt +++ b/doc/server/plugins/generators/tcheetah.txt @@ -28,7 +28,7 @@ files, ``template`` and ``info``. The template is a standard Cheetah template with two additions: * `self.metadata` is the client's :ref:`metadata <server-plugins-grouping-metadata-clientmetadata>` -* `self.metadata.Properties.data` is an xml document of unstructured data +* `self.metadata.Properties.xdata` is an xml document of unstructured data The ``info`` file is formatted like ``:info`` files from Cfg. @@ -47,7 +47,7 @@ self.metadata variables self.metadata is an instance of the class ClientMetadata and documented :ref:`here <server-plugins-grouping-metadata-clientmetadata>`. -self.metadata.Properties.data +self.metadata.Properties.xdata ============================= .. note:: @@ -56,7 +56,7 @@ self.metadata.Properties.data :ref:`server-plugins-connectors-properties` plugin in ``/etc/bcfg2.conf``. -Properties.data is a python `ElementTree <http://codespeak.net/lxml/>`_ +Properties.xdata is a python `ElementTree <http://codespeak.net/lxml/>`_ object, loaded from the data in ``/var/lib/bcfg2/Properties/<properties file>.xml``. That file should have a ``Properties`` node at its root. @@ -76,13 +76,13 @@ You may use any of the ElementTree methods to access data in your template. Several examples follow, each producing an identical result on the host 'www.example.com':: - $self.metadata.Properties['example.xml'].data.find('host').find('www.example.com').find('rootdev').text - $self.metadata.Properties['example.xml'].data.find('host').find($self.metadata.hostname).find('rootdev').text - ${self.metadata.Properties['example.xml'].data.xpath('host/www.example.com/rootdev')[0].text} - ${self.metadata.Properties['example.xml'].data.xpath('host/' + self.metadata.hostname + '/rootdev')[0].text} + $self.metadata.Properties['example.xml'].xdata.find('host').find('www.example.com').find('rootdev').text + $self.metadata.Properties['example.xml'].xdata.find('host').find($self.metadata.hostname).find('rootdev').text + ${self.metadata.Properties['example.xml'].xdata.xpath('host/www.example.com/rootdev')[0].text} + ${self.metadata.Properties['example.xml'].xdata.xpath('host/' + self.metadata.hostname + '/rootdev')[0].text} #set $path = 'host/' + $self.metadata.hostname + '/rootdev' - ${self.metadata.Properties['example.xml'].data.xpath($path)[0].text} - ${self.metadata.Properties['example.xml'].data.xpath(path)[0].text} + ${self.metadata.Properties['example.xml'].xdata.xpath($path)[0].text} + ${self.metadata.Properties['example.xml'].xdata.xpath(path)[0].text} Other Variables =============== diff --git a/doc/server/plugins/generators/tgenshi/clientsxml.txt b/doc/server/plugins/generators/tgenshi/clientsxml.txt index 7305ba70d..7a8d1fcc4 100644 --- a/doc/server/plugins/generators/tgenshi/clientsxml.txt +++ b/doc/server/plugins/generators/tgenshi/clientsxml.txt @@ -22,7 +22,7 @@ There are two main advantages: thing to note is how the `name` variable is handled - when just referring to it the standard `${name}` syntax is used, but when it is used as a variable in the expression to get the password, - `password="${metadata.Properties['passwords.xml'].data.find('password').find('bcfg2-client').find(name).text}"`, + `password="${metadata.Properties['passwords.xml'].xdata.find('password').find('bcfg2-client').find(name).text}"`, it is just referred to as `name`. There is the disadvantage that sometimes 2 passes will be needed to get @@ -53,7 +53,7 @@ Possible improvements: profile="${profile}" name="${name}" uuid="${name}" - password="${metadata.Properties['passwords.xml'].data.find('password').find('bcfg2-client').find(name).text}" + password="${metadata.Properties['passwords.xml'].xdata.find('password').find('bcfg2-client').find(name).text}" address="${address}" location="fixed" secure="true" @@ -64,7 +64,7 @@ Possible improvements: profile="${profile}" name="${name}" uuid="${name}" - password="${metadata.Properties['passwords.xml'].data.find('password').find('bcfg2-client').find(name).text}" + password="${metadata.Properties['passwords.xml'].xdata.find('password').find('bcfg2-client').find(name).text}" location="floating" secure="true" />\ diff --git a/doc/server/plugins/generators/tgenshi/test.txt b/doc/server/plugins/generators/tgenshi/test.txt index dca578434..c047b88d0 100644 --- a/doc/server/plugins/generators/tgenshi/test.txt +++ b/doc/server/plugins/generators/tgenshi/test.txt @@ -45,8 +45,8 @@ This file just shows you what's available. It assumes a {% end %}\ Two main ways to get the same property value: - ${metadata.Properties['test.xml'].data.find('password').find('bcfg2').text} - ${metadata.Properties['test.xml'].data.xpath('password/bcfg2')[0].text} + ${metadata.Properties['test.xml'].xdata.find('password').find('bcfg2').text} + ${metadata.Properties['test.xml'].xdata.xpath('password/bcfg2')[0].text} One way to get information about metadata and properties: @@ -55,28 +55,28 @@ This file just shows you what's available. It assumes a ${var} \ {% end %} - dir(metadata.Properties.data): - {% for var in dir(metadata.Properties.data) %}\ + dir(metadata.Properties.xdata): + {% for var in dir(metadata.Properties.xdata) %}\ ${var} \ {% end %} - dir(metadata.Properties.data.entries): - {% for var in dir(metadata.Properties.data.entries) %}\ + dir(metadata.Properties.xdata.entries): + {% for var in dir(metadata.Properties.xdata.entries) %}\ ${var} \ {% end %} - dir(metadata.Properties.data.label): - {% for var in dir(metadata.Properties.data.label) %}\ + dir(metadata.Properties.xdata.label): + {% for var in dir(metadata.Properties.xdata.label) %}\ ${var} \ {% end %} - dir(metadata.Properties.data.name): - {% for var in dir(metadata.Properties.data.name) %}\ + dir(metadata.Properties.xdata.name): + {% for var in dir(metadata.Properties.xdata.name) %}\ ${var} \ {% end %} - dir(metadata.Properties.data.properties): - {% for var in dir(metadata.Properties.data.properties) %}\ + dir(metadata.Properties.xdata.properties): + {% for var in dir(metadata.Properties.xdata.properties) %}\ ${var} \ {% end %} @@ -113,13 +113,13 @@ this (below reformatted a little bit to fit in 80 columns):: __weakref__ all bundles categories get_clients_by_group get_clients_by_profile groups hostname inGrouppassword probes uuid - dir(metadata.Properties.data): + dir(metadata.Properties.xdata): HandleEvent Index __class__ __delattr__ __dict__ __doc__ __getattribute__ __hash__ __identifier__ __init__ __iter__ __module__ __new__ __reduce__ __reduce_ex__ __repr__ __setattr__ __str__ __weakref__ entries label name properties - dir(metadata.Properties.data.entries): + dir(metadata.Properties.xdata.entries): __add__ __class__ __contains__ __delattr__ __delitem__ __delslice__ __doc__ __eq__ __ge__ __getattribute__ __getitem__ __getslice__ __gt__ __hash__ __iadd__ __imul__ __init__ __iter__ __le__ __len__ __lt__ __mul__ __ne__ @@ -127,7 +127,7 @@ this (below reformatted a little bit to fit in 80 columns):: __setitem__ __setslice__ __str__ append count extend index insert pop remove reverse sort - dir(metadata.Properties.data.label): + dir(metadata.Properties.xdata.label): __add__ __class__ __contains__ __delattr__ __doc__ __eq__ __ge__ __getattribute__ __getitem__ __getnewargs__ __getslice__ __gt__ __hash__ __init__ __le__ __len__ __lt__ __mod__ __mul__ __ne__ __new__ __reduce__ @@ -137,7 +137,7 @@ this (below reformatted a little bit to fit in 80 columns):: rfind rindex rjust rpartition rsplit rstrip split splitlinesstartswith strip swapcase title translate upper zfill - dir(metadata.Properties.data.name): + dir(metadata.Properties.xdata.name): __add__ __class__ __contains__ __delattr__ __doc__ __eq__ __ge__ __getattribute__ __getitem__ __getnewargs__ __getslice__ __gt__ __hash__ __init__ __le__ __len__ __lt__ __mod__ __mul__ __ne__ __new__ __reduce__ @@ -147,7 +147,7 @@ this (below reformatted a little bit to fit in 80 columns):: rfind rindex rjust rpartition rsplit rstrip split splitlinesstartswith strip swapcase title translate upper zfill - dir(metadata.Properties.data.properties): + dir(metadata.Properties.xdata.properties): __class__ __contains__ __copy__ __deepcopy__ __delattr__ __delitem__ __delslice__ __doc__ __getattribute__ __getitem__ __getslice__ __hash__ __init__ __iter__ __len__ __new__ __nonzero__ __reduce__ __reduce_ex__ diff --git a/doc/server/plugins/grouping/metadata.txt b/doc/server/plugins/grouping/metadata.txt index 43cc6a2d7..fc8605115 100644 --- a/doc/server/plugins/grouping/metadata.txt +++ b/doc/server/plugins/grouping/metadata.txt @@ -281,9 +281,9 @@ This class provides query routines for the servers Metadata. +==============================+================================================+===================+ | by_name(client) | Get ClientMetadata object for 'client' | ClientMetadata | +------------------------------+------------------------------------------------+-------------------+ -| names_by_groups(group) | | | +| names_by_groups(groups) | All client names in the list of 'groups' | List | +------------------------------+------------------------------------------------+-------------------+ -| names_by_profiles(profile) | All clients names in 'profile' | List | +| names_by_profiles(profiles) | All client names in the list of 'profiles' | List | +------------------------------+------------------------------------------------+-------------------+ | all_clients() | All known client hostnames | List | +------------------------------+------------------------------------------------+-------------------+ diff --git a/doc/server/plugins/structures/bundler/index.txt b/doc/server/plugins/structures/bundler/index.txt index 0cc2a0e55..3184fe6eb 100644 --- a/doc/server/plugins/structures/bundler/index.txt +++ b/doc/server/plugins/structures/bundler/index.txt @@ -148,18 +148,25 @@ Use .. warning:: - Group tags are not used inside of Genshi templates. You can get the - same logic (and more) using Genshi conditionals. + ``<Group>`` and ``<Client>`` tags are allowed inside of Genshi + templates as of Bcfg2 1.2. However, they do not behave the same + as using a Genshi conditional, e.g.:: - .. code-block:: xml - - <py:if test="groupname in metadata.groups"> + <py:if test="'groupname' in metadata.groups"> </py:if> - -Bcfg uses the Genshi API for templates, and performs a XML format + + The conditional is evaluated when the template is rendered, so + code inside the conditional is not executed if the conditional + fails. A ``<Group>`` tag is evaluated *after* the template is + rendered, so code inside the tag is always executed. This is an + important distinction: if you have code that will fail on some + groups, you *must* use a Genshi conditional, not a ``<Group>`` + tag. The same caveats apply to ``<Client>`` tags. + +Bcfg2 uses the Genshi API for templates, and performs a XML format stream rendering of the template into an lxml entry, which is included in the client configuration. :ref:`Client metadata <client-metadata>` -is avilable inside of the template using the 'metadata' name. Note that +is available inside of the template using the 'metadata' name. Note that only the markup Genshi template format can be used, as the target output format is XML. @@ -210,19 +217,35 @@ and returns them in a newline delimited string. .. code-block:: xml - <Bundle name='networkinterfaces' xmlns:py="http://genshi.edgewall.org/"> + <Bundle name="networkinterfaces" xmlns:py="http://genshi.edgewall.org/"> <?python - files = $metadata.Probes["getmacs"].split("\n") + files = metadata.Probes["getmacs"].split("\n") ?> - <Path py:for="file in files" name="/etc/sysconfig/network/ifcfg-eth-${file}" altsrc='/etc/ifcfg-template'/> + <Path py:for="file in files" + name="/etc/sysconfig/network/ifcfg-eth-${file}" + altsrc="/etc/ifcfg-template"/> </Bundle> .. note:: - * The use of the altsrc directive causes all ifcfg files to be handled by the same plugin and entry. - * The <?python ?> blocks have only been available in genshi since 0.4 (http://genshi.edgewall.org/ticket/84) + * The use of the altsrc directive causes all ifcfg files to be + handled by the same plugin and entry. + * The <?python ?> blocks have only been available in genshi since + 0.4 (http://genshi.edgewall.org/ticket/84) If you want a file to be only on a per-client basis, you can use an -if declaration: +if declaration. + +.. code-block:: xml + + <Bundle name='bacula' xmlns:py="http://genshi.edgewall.org/"> + <Path name="/etc/bacula/bconsole.conf"/> + <Path name="/etc/bacula/bacula-fd.conf"/> + <Path name="/etc/bacula/bacula-sd.conf"/> + <Path py:if="metadata.hostname == 'foo.bar.com'" + name="/etc/bacula/bacula-dir.conf"/> + </Bundle> + +or alternately .. code-block:: xml @@ -230,10 +253,12 @@ if declaration: <Path name="/etc/bacula/bconsole.conf"/> <Path name="/etc/bacula/bacula-fd.conf"/> <Path name="/etc/bacula/bacula-sd.conf"/> - <Path py:if="metadata.hostname == 'foo.bar.com'" name="/etc/bacula/bacula-dir.conf"/> + <py:if="metadata.hostname == 'foo.bar.com'"> + <Path name="/etc/bacula/bacula-dir.conf"/> + </py:if> </Bundle> -or alternately: +or yet another way .. code-block:: xml @@ -241,14 +266,16 @@ or alternately: <Path name="/etc/bacula/bconsole.conf"/> <Path name="/etc/bacula/bacula-fd.conf"/> <Path name="/etc/bacula/bacula-sd.conf"/> - <py:if test="metadata.hostname == 'foo.bar.com'"> + <Client name="foo.bar.com"> <Path name="/etc/bacula/bacula-dir.conf"/> - </py:if> + </Client> </Bundle> -The latter form is preferred if the if block contains multiple -files. While this example is simple, the test in the if block can in -fact be any python statement. +The final form is preferred if there is no code inside the block that +would fail on other clients. + +While these examples are simple, the test in the if block can in fact +be any python statement. .. _server-plugins-structures-bundler-index-examples: diff --git a/doc/server/plugins/structures/defaults.txt b/doc/server/plugins/structures/defaults.txt new file mode 100644 index 000000000..58b9feddb --- /dev/null +++ b/doc/server/plugins/structures/defaults.txt @@ -0,0 +1,31 @@ +.. -*- mode: rst -*- + +.. _server-plugins-structures-defaults: + +========== + Defaults +========== + +The Defaults plugin can be used to populate default attributes for +entries. Defaults is *not* a Generator plugin, so it does not +actually bind an entry; Defaults are applied after an entry has been +bound, and only populate attributes that are not yet set. + +Like :ref:`server-plugins-generators-rules`, Defaults supports regular +expressions in the name attribute. + +For instance, to make all Service entries use the ``systemd`` tool +on Fedora 15 and the ``chkconfig`` tool on Fedora 14, you could do:: + + <Defaults priority="0"> + <Group name="fedora-15"> + <Service name=".*" type="systemd"/> + </Group> + <Group name="fedora-14"> + <Service name=".*" type="chkconfig"/> + </Group> + </Defaults> + +If you were to specify a ``type`` attribute for a Service entry in +Rules (or a ``type`` attribute for a BoundService entry in Bundler), +that would take precendence over the default. |