diff options
Diffstat (limited to 'doc/server/plugins/generators/packages.txt')
| -rw-r--r-- | doc/server/plugins/generators/packages.txt | 293 |
1 files changed, 151 insertions, 142 deletions
diff --git a/doc/server/plugins/generators/packages.txt b/doc/server/plugins/generators/packages.txt index 555f7ac97..42efd35a1 100644 --- a/doc/server/plugins/generators/packages.txt +++ b/doc/server/plugins/generators/packages.txt @@ -8,11 +8,12 @@ Packages .. versionadded:: 1.0.0 -Packages is an alternative to :ref:`Pkgmgr <server-plugins-generators-pkgmgr>` - for specifying package entries for clients. Where Pkgmgr explicitly -specifies package entry information, Packages delegates control of package -version information to the underlying package manager, installing the latest -version available through those channels. +This page documents the Packages plugin. Packages is an alternative to +:ref:`Pkgmgr <server-plugins-generators-pkgmgr>` for specifying package +entries for clients. Where Pkgmgr explicitly specifies package entry +information, Packages delegates control of package version information to +the underlying package manager, installing the latest version available +through those channels. .. _server-plugins-generators-packages-magic-groups: @@ -33,29 +34,29 @@ member clients. +--------+----------+--------------+ | Source | OS Group | Architecture | +========+==========+==============+ -| Apt | debian | i386 | +| Apt | debian | i386 | +--------+----------+--------------+ -| Apt | ubuntu | amd64 | +| Apt | ubuntu | amd64 | +--------+----------+--------------+ -| Apt | nexenta | | +| Apt | nexenta | | +--------+----------+--------------+ -| Apt | apt | | +| Apt | apt | | +--------+----------+--------------+ -| Yum | redhat | i386 | +| Yum | redhat | i386 | +--------+----------+--------------+ -| Yum | centos | x86_64 | +| Yum | centos | x86_64 | +--------+----------+--------------+ -| Yum | fedora | | +| Yum | fedora | | +--------+----------+--------------+ -| Yum | yum | | +| Yum | yum | | +--------+----------+--------------+ -.. note:: +.. 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 + ``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. @@ -64,10 +65,10 @@ Limiting sources to groups ========================== ``Packages/sources.xml`` processes ``<Group>`` and ``<Client>`` tags -just like Bundles. In addition to any groups or clients specified +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 +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. @@ -129,12 +130,12 @@ Dependency resolution can be disabled by adding this to ``Packages/packages.conf`` in the ``global`` section:: [global] - resolver=disabled + resolver=0 All metadata processing can be disabled as well:: [global] - metadata=disabled + metadata=0 Blacklisting faulty dependencies -------------------------------- @@ -145,7 +146,7 @@ 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 + <Blacklist>unwanted-packagename</Blacklist> If you use the built-in :ref:`Yum config generator @@ -157,10 +158,12 @@ Handling GPG Keys .. versionadded:: 1.2.0 -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``:: - .. code-block:: xml +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``:: + <Source type="yum" rawurl="http://mirror.example.com/centos6-x86_64/RPMS.os"> <Arch>x86_64</Arch> @@ -182,11 +185,9 @@ REST API. Example usage ============= -APT ---- Create a ``sources.xml`` file in the Packages directory that looks something like this:: - .. code-block:: xml + <Sources> <Group name="ubuntu-intrepid"> <Source type="apt" @@ -204,24 +205,31 @@ 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. 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.: + 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.: .. code-block:: xml <Source type="apt" recommended="true" ...> -YUM ---- + .. warning:: You must regenerate the Packages cache when adding or + removing the recommended attribute. + + .. [#f1] Bcfg2 will by default add **Essential** packages to the + client specification. You can disable this behavior by + setting the ``essential`` attribute to *false*: -Yum sources can be similarly specified:: .. code-block:: xml + + <Source type="apt" essential="false" ...> + +Yum sources can be similarly specified:: + <Sources> <Group name="centos-5.2"> <Source type="yum" @@ -240,13 +248,9 @@ Yum sources can be similarly specified:: For sources with a **URL** attribute, the **Version** attribute is also necessary. -Pulp ----- - :ref:``Pulp sources <pulp-source-support>`` are very simple to specify due to the amount of data that can be queried from Pulp itself:: - .. code-block:: xml <Sources> <Group name="centos-6-x86_64"> <Source type="yum" pulp_id="centos-6-x86_64-os"/> @@ -255,19 +259,18 @@ due to the amount of data that can be queried from Pulp itself:: </Group> </Sources> -Raw URLs --------- -For specifying sources that don't follow the conventional layout, the rawurl -attribute is useful:: +.. note:: There is also a rawurl attribute for specifying sources that + don't follow the conventional layout. - .. code-block:: xml - <Sources> - <Group name="centos5.4"> - <Source type="yum" - rawurl="http://mrepo.ices.utexas.edu/centos5-x86_64/RPMS.os"> - <Arch>x86_64</Arch> - </Source> - <Source type="yum" + .. code-block:: xml + + <Sources> + <Group name="centos5.4"> + <Source type="yum" + rawurl="http://mrepo.ices.utexas.edu/centos5-x86_64/RPMS.os"> + <Arch>x86_64</Arch> + </Source> + <Source type="yum" rawurl="http://mrepo.ices.utexas.edu/centos5-x86_64/RPMS.updates"> <Arch>x86_64</Arch> </Source> @@ -278,19 +281,20 @@ attribute is useful:: </Group> </Sources> - .. code-block:: xml - <Sources> - <Group name="ubuntu-lucid"> - <Source type="apt" - rawurl="http://hudson-ci.org/debian/binary"> - <Arch>amd64</Arch> - </Source> - <Source type="apt" - rawurl=http://hudson-ci.org/debian/binary"> - <Arch>i386</Arch> - </Source> - </Group> - </Sources> + .. code-block:: xml + + <Sources> + <Group name="ubuntu-lucid"> + <Source type="apt" + rawurl="http://hudson-ci.org/debian/binary"> + <Arch>amd64</Arch> + </Source> + <Source type="apt" + rawurl=http://hudson-ci.org/debian/binary"> + <Arch>i386</Arch> + </Source> + </Group> + </Sources> Configuration Updates ===================== @@ -338,7 +342,7 @@ updated. Availability ============ -Support for clients using yum and apt is currently available. Support for +Support for clients using yum and apt is currently available. Support for other package managers (Portage, Zypper, IPS, etc) remain to be added. Validation @@ -354,7 +358,7 @@ Limitations Packages does not do traditional caching as other plugins do. Modifying sources in the Packages ``sources.xml`` file requires a -server restart for the time being. You do not have to restart the +server restart for the time being. You do not have to restart the server after changing ``packages.conf`` or after adding new sources to ``sources.xml``. @@ -364,7 +368,6 @@ Package Checking and Verification In order to do disable per-package verification Pkgmgr style, you will need to use :ref:`BoundEntries <boundentries>`, e.g.:: - .. code-block:: xml <BoundPackage name="mem-agent" priority="1" version="auto" type="yum" verify="false"/> @@ -388,9 +391,9 @@ Then add the corresponding Path entry to your Yum bundle. .. versionadded:: 1.1.0 APT repository information can be generated automatically from -software sources using :doc:`./tgenshi/index` or :doc:`./tcheetah`. A +software sources using :doc:`./tgenshi/index` or :doc:`./tcheetah`. A list of source urls are exposed in the client's metadata as -``metadata.Packages.sources``. E.g.:: +``metadata.Packages.sources``. E.g.:: # bcfg2 maintained apt @@ -408,7 +411,7 @@ Using Native Yum Libraries By default, Bcfg2 uses an internal implementation of Yum's dependency resolution and other routines so that the Bcfg2 server can be run on a -host that does not support Yum itself. If you run the Bcfg2 server on +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``. @@ -422,7 +425,7 @@ Benefits to this include: Drawbacks include: -* More disk I/O. In some cases, you may have to raise the open file +* 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, @@ -437,8 +440,8 @@ Configuring the Yum Helper Due to poor memory management by the Yum API, the long-lived bcfg2-server process uses an external short-lived helper, ``bcfg2-yum-helper``, to do the actual Yum API calls for native yum -library support. By default, Bcfg2 looks for this helper at -``/usr/sbin/bcfg2-yum-helper``. If you have installed the helper +library support. By default, Bcfg2 looks for this helper at +``/usr/sbin/bcfg2-yum-helper``. If you have installed the helper elsewhere, you will need to configure that location with the ``helper`` option in the ``[yum]`` section, e.g.:: @@ -452,11 +455,11 @@ Setting Yum Options In ``Packages/packages.conf``, any options you set in the ``[yum]`` section other than ``use_yum_libraries`` and ``helper`` 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 +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. + 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. @@ -466,18 +469,18 @@ not generally be overridden: Package Groups -------------- -Yum package groups are supported by the native Yum libraries. To +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 +``Package`` tag. You can use either the short group ID or the long group name:: - .. code-block:: xml + <Package group="SNMP Support"/> <Package group="system-management-snmp"/> By default, only those packages considered the "default" packages in a -group will be installed. You can change this behavior using the +group will be installed. You can change this behavior using the "type" attribute:: - .. code-block:: xml + <Package group="development" type="optional"/> <Package group="Administration Tools" type="mandatory"/> @@ -489,7 +492,7 @@ Valid values of "type" are: including mandatory, default, and optional packages. You can view the packages in a group by category with the ``yum -groupinfo`` command. More information about the different levels can +groupinfo`` command. More information about the different levels can be found at http://fedoraproject.org/wiki/How_to_use_and_edit_comps.xml_for_package_groups#Installation @@ -501,10 +504,10 @@ 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 +(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:: - .. code-block:: xml + <Sources> <Group name="centos-6-x86_64"> <Source type="yum" pulp_id="centos-6-x86_64-os"/> @@ -513,7 +516,7 @@ necessary to configure a Pulp repo is the repo ID:: </Group> </Sources> -Pulp sources require some additional configuration. First, the Bcfg2 +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. @@ -523,7 +526,7 @@ 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 + repositories. Membership in the default ``consumer-users`` role is sufficient. Bcfg2 clients using Pulp sources will be registered to the Pulp server @@ -532,50 +535,50 @@ as consumers, and will be bound to the appropriate repositories. Debugging unexpected behavior ============================= +.. versionadded:: 1.2.1 + Using bcfg2-info ---------------- The dependency resolver used in Packages can be run in debug mode:: - - $ bcfg2-info + $ bcfg2-info packageresolve foo.example.com bcfg2-server zlib ... - Handled 20 events in 0.004s - > debug - dropping to python interpreter; press ^D to resume - ... - (debug_shell) - >>> m = self.build_metadata('ubik3') - >>> self.plugins['Packages'].complete(m, ['ssh'], debug=True) - Package ssh: adding new deps ['openssh-client', 'openssh-server'] - Package openssh-server: adding new deps ['libc6', 'libcomerr2', 'libkrb53', 'libpam0g', 'libselinux1', 'libssl0.9.8 - ', 'libwrap0', 'zlib1g', 'debconf', 'libpam-runtime', 'libpam-modules', 'adduser', 'dpkg', 'lsb-base'] - Package debconf: adding new deps ['debconf-i18n'] - Package libpam-modules: adding new deps ['libdb4.7'] - Package openssh-client: adding new deps ['libedit2', 'libncurses5', 'passwd'] - Package lsb-base: adding new deps ['sed', 'ncurses-bin'] - Package adduser: adding new deps ['perl-base'] - Package debconf-i18n: adding new deps ['liblocale-gettext-perl', 'libtext-iconv-perl', 'libtext-wrapi18n-perl', 'libtext-charwidth-perl'] - Package passwd: adding new deps ['debianutils'] - Package libtext-charwidth-perl: adding new deps ['perlapi-5.10.0'] - VPackage perlapi-5.10.0: got provides ['perl-base'] - Package libkrb53: adding new deps ['libkeyutils1'] - Package libtext-iconv-perl: adding new deps ['perlapi-5.10.0'] - Package libc6: adding new deps ['libgcc1', 'findutils'] - Package libgcc1: adding new deps ['gcc-4.3-base'] - (set(['debconf', 'libgcc1', 'lsb-base', 'libtext-wrapi18n-perl', 'libtext-iconv-perl', 'sed', 'passwd', 'findutils', 'libpam0g', 'openssh-client', 'debconf-i18n', 'libselinux1', 'zlib1g', 'adduser', 'libwrap0', 'ncurses-bin', 'libssl0.9.8', 'liblocale-gettext-perl', 'libkeyutils1', 'libpam-runtime', 'libpam-modules', 'openssh-server', 'libkrb53', 'ssh', 'libncurses5', 'libc6', 'libedit2', 'libcomerr2', 'dpkg', 'perl-base', 'libdb4.7', 'libtext-charwidth-perl', 'gcc-4.3-base', 'debianutils']), set([]), 'deb') + 2 initial packages + bcfg2-server + zlib + 54 new packages added + sqlite + less + libxml2 + expat + ... + 1 unknown packages + libglib-2.0.so.0()(64bit) This will show why the resolver is acting as it is. Replace -``"ubik3"`` and ``['ssh']`` with a client name and list of packages, -respectively. Also, a more polished interface to this functionality is -coming as well. +``foo.example.com`` and ``bcfg2-server`` with a client name and list +of packages, respectively. + +Note that resolving a partial package list (as above) may result in +more unknown entries than you'd have otherwise; some of the package +drivers (Yum in particular) consider the full package list when +resolving multiple providers, and will not be able to properly resolve +some dependencies without a full package list. -Each line starting with Package: <name> describes a set of new -prerequisites pulled in by a package. Lines starting with VPackage <vname> -describe provides entries and their mappings to required names. The last -line describes the overall results of the resolver, with three fields: -a list of packages that should be installed, a list of unresolved -requirements, and a type for these packages. +You can also view the sources applicable to a client:: + + $ bcfg2-info packagesources foo.example.com + ... + Name: centos-6-x86_64-updates + Type: yum + URL: http://mirror.example.com/centos-6-x86_64-updates + GPG Key(s): http://mirror.example.com/centos-6-x86_64-updates/RPM-GPG-KEY-CentOS-6 + + Name: centos-6-x86_64-os + Type: yum + URL: http://mirror.example.com/centos-6-x86_64-os + GPG Key(s): http://mirror.example.com/centos-6-x86_64-os/RPM-GPG-KEY-CentOS-6 Using bcfg2-server ------------------ @@ -584,6 +587,13 @@ Once the server is started, enable debugging via bcfg2-admin:: $ bcfg2-admin xcmd Packages.toggle_debug +TODO list +========= + +* Zypper support +* Portage support +* Explicit version pinning (a la Pkgmgr) + Developing for Packages ======================= @@ -637,37 +647,36 @@ packages.conf ============= ``packages.conf`` contains miscellaneous configuration options for the -Packages plugin. It understands the following directives: +Packages plugin. Any booleans in the config file accept the values +"1", "yes", "true", and "on" for True, and "0", "no", "false", and +"off" for False + +It understands the following directives: [global] section ---------------- -* ``resolver``: Disable dependency resolution. Default is "enabled". -* ``metadata``: Disable metadata processing. Default is "enabled". -* ``yum_config``: The path at which to generate Yum configs. No +* ``resolver``: Enable dependency resolution. Default is ``1`` + (true). For historical reasons, this also accepts "enabled" and + "disabled". +* ``metadata``: Enable metadata processing. Default is ``1`` + (true). For historical reasons, this also accepts "enabled" and + "disabled". +* ``yum_config``: The path at which to generate Yum configs. No default. -* ``apt_config``: The path at which to generate APT configs. No +* ``apt_config``: The path at which to generate APT configs. No default. * ``gpg_keypath``: The path on the client RPM GPG keys will be copied - to before they are imported on the client. Default is + to before they are imported on the client. Default is "/etc/pki/rpm-gpg". -* ``import_gpg_keys``: The RPM release of an RPM GPG key cannot be - reliably and automatically determined without importing the key into - the server's key chain. If ``import_gpg_keys`` is "false" (the - default), the release of automatically-generated RPM GPG key entries - in the specification will be set to "any", which disables - verification of the release. (Version will still be verified.) In - practice, this is unlikely to be an issue, as the RPM version of a - GPG key is the key's fingerprint, and collisions are rare. If you - do encounter a GPG key version collision, you will need to set this - to "true", whereupon Packages will import the keys into the server's - key chain. Python RPM libraries must be installed for this to work. +* ``version``: Set the version attribute used when binding + Packages. Default is ``auto``. [yum] section ------------- * ``use_yum_libraries``: Whether or not to use the :ref:`native yum - library support <native-yum-libraries>`. Default is ``0`` (false). + 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 @@ -678,5 +687,5 @@ library support. * ``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 + repositories. Membership in the default ``consumer-users`` role is sufficient. |