diff options
Diffstat (limited to 'doc/server/plugins/generators/packages.txt')
| -rw-r--r-- | doc/server/plugins/generators/packages.txt | 224 |
1 files changed, 147 insertions, 77 deletions
diff --git a/doc/server/plugins/generators/packages.txt b/doc/server/plugins/generators/packages.txt index 62574be76..43db251b0 100644 --- a/doc/server/plugins/generators/packages.txt +++ b/doc/server/plugins/generators/packages.txt @@ -126,17 +126,19 @@ Disabling dependency resolution .. versionadded:: 1.1.0 -Dependency resolution can be disabled by adding this to -``Packages/packages.conf`` in the ``global`` section:: +Dependency resolution can be disabled by adding the following setting +to ``bcfg2.conf`` in the ``packages`` section:: - [global] + [packages] resolver=0 All metadata processing can be disabled as well:: - [global] + [packages] metadata=0 +This setting implies disabling the resolver. + Blacklisting faulty dependencies -------------------------------- @@ -145,7 +147,9 @@ 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:: +and should look like the following: + +.. code-block:: xml <Blacklist>unwanted-packagename</Blacklist> @@ -162,7 +166,9 @@ 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 in ``sources.xml``: + +.. code-block:: xml <Source type="yum" rawurl="http://mirror.example.com/centos6-x86_64/RPMS.os"> @@ -176,17 +182,53 @@ 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 +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. +Arbitrary Repo Options +---------------------- + +.. versionadded:: 1.2.3 + +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: + +.. code-block:: xml + + <Source type="yum" rawurl="http://mirror.example.com/centos-6-os"> + <Arch>x86_64</Arch> + <Options proxy="http://proxy.example.com"/> + </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: + +.. code-block:: xml + + <Source type="yum" rawurl="http://mirror.example.com/centos-6-os"> + <Arch>x86_64</Arch> + <Options serveronly="true" proxy="http://proxy.example.com"/> + <Options clientonly="true" metadata_expire="0"/> + </Source> + .. _packages-exampleusage: Example usage ============= Create a ``sources.xml`` file in the Packages directory that looks -something like this:: +something like this: + +.. code-block:: xml <Sources> <Group name="ubuntu-intrepid"> @@ -228,7 +270,9 @@ something like this:: <Source type="apt" essential="false" ...> -Yum sources can be similarly specified:: +Yum sources can be similarly specified: + +.. code-block:: xml <Sources> <Group name="centos-5.2"> @@ -248,8 +292,10 @@ 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:: +: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"> @@ -353,20 +399,13 @@ be validated using ``bcfg2-lint``. .. note:: The schema requires that elements be specified in the above order. -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 after changing ``packages.conf`` or after adding new sources to -``sources.xml``. - Package Checking and Verification ================================= In order to do disable per-package verification Pkgmgr style, you will -need to use :ref:`BoundEntries <boundentries>`, e.g.:: +need to use :ref:`BoundEntries <boundentries>`, e.g.: + +.. code-block:: xml <BoundPackage name="mem-agent" priority="1" version="auto" type="yum" verify="false"/> @@ -380,10 +419,10 @@ Generating Client APT/Yum Configurations .. versionadded:: 1.2.0 The Packages plugin has native support for generating Yum configs. -You must set ``yum_config`` in ``Packages/packages.conf`` to the path -to the yum config file you want to generate:: +You must set ``yum_config`` in ``bcfg2.conf`` to the path to the yum +config file you want to generate:: - [global] + [packages] yum_config=/etc/yum.repos.d/all.repo Then add the corresponding Path entry to your Yum bundle. @@ -414,7 +453,7 @@ 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``. +``1`` in the ``[packages:yum]`` section of ``bcfg2.conf``. Benefits to this include: @@ -440,23 +479,24 @@ 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 -elsewhere, you will need to configure that location with the -``helper`` option in the ``[yum]`` section, e.g.:: +library support. By default, Bcfg2 looks for this helper in +``$PATH``, or, failing that, 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 ``[packages:yum]`` +section, e.g.:: - [yum] + [packages:yum] use_yum_libraries = 1 helper = /usr/local/sbin/bcfg2-yum-helper Setting Yum Options ------------------- -In ``Packages/packages.conf``, any options you set in the ``[yum]`` +In ``bcfg2.conf``, any options you set in the ``[packages: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 -not generally be overridden: +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. @@ -472,14 +512,18 @@ 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:: +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 -"type" attribute:: +"type" attribute: + +.. code-block:: xml <Package group="development" type="optional"/> <Package group="Administration Tools" type="mandatory"/> @@ -506,7 +550,9 @@ Pulp Support 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:: +necessary to configure a Pulp repo is the repo ID: + +.. code-block:: xml <Sources> <Group name="centos-6-x86_64"> @@ -521,8 +567,8 @@ 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: +Secondly, in ``bcfg2.conf`` you must set the following +options in the ``[packages: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 @@ -643,49 +689,73 @@ multiple data sources need to be multiplexed. The APT source in ``src/lib/Server/Plugins/Packages.py`` provides a relatively simple implementation of a source. -packages.conf +Configuration ============= -``packages.conf`` contains miscellaneous configuration options for the +``bcfg2.conf`` contains miscellaneous configuration options for the 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 +"off" for False. For historical reasons, ``resolver`` and +``metadata`` also accept "enabled" and "disabled". It understands the following directives: -[global] section ----------------- - -* ``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 - default. -* ``gpg_keypath``: The path on the client RPM GPG keys will be copied - to before they are imported on the client. Default is - "/etc/pki/rpm-gpg". -* ``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). - -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 --------------- +[packages] 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. ++-------------+------------------------------------------------------+----------+-----------------------------+ +| Name | Description | Values | Default | ++=============+======================================================+==========+=============================+ +| resolver | Enable dependency resolution | Boolean | True | ++-------------+------------------------------------------------------+----------+-----------------------------+ +| 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 | ++-------------+------------------------------------------------------+----------+-----------------------------+ +| apt_config | The path at which to generate APT configs. | String | /etc/apt/sources.d/bcfg2 | ++-------------+------------------------------------------------------+----------+-----------------------------+ +| gpg_keypath | The path on the client RPM GPG keys will be copied | String | /etc/pki/rpm-gpg | +| | to before they are imported on the client. | | | ++-------------+------------------------------------------------------+----------+-----------------------------+ +| version | Set the version attribute used when binding Packages | any|auto | auto | ++-------------+------------------------------------------------------+----------+-----------------------------+ +| cache | Path where Packages will store its cache | String | <repo>/Packages/cache | ++-------------+------------------------------------------------------+----------+-----------------------------+ +| keycache | Path where Packages will cache downloaded GPG keys | String | <repo>/Packages/keys | ++-------------+------------------------------------------------------+----------+-----------------------------+ + + +[packages:yum] section +---------------------- + ++-------------------+----------------------------------------------------------+---------+-----------+ +| Name | Description | Values | Default | ++===================+==========================================================+=========+===========+ +| use_yum_libraries | Whether or not to use the | Boolean | False | +| | :ref:`native yum library support <native-yum-libraries>` | | | ++-------------------+----------------------------------------------------------+---------+-----------+ +| helper | Path to ``bcfg2-yum-helper`` | String | See below | ++-------------------+----------------------------------------------------------+---------+-----------+ + +To find ``bcfg2-yum-helper`` if none is specified, Bcfg2 looks first +in ``$PATH`` and then in ``/usr/sbin/bcfg2-yum-helper`` for the +helper. + +All other options in the ``[packages:yum]`` section will be passed +along verbatim to the Yum configuration if you are using the native +Yum library support. + +[packages:pulp] section +----------------------- + ++----------+-----------------------------------------------------+--------+---------+ +| Name | Description | Values | Default | ++==========+=====================================================+========+=========+ +| username | The username of a Pulp user that will be used to | String | None | +| | register new clients and bind them to repositories. | | | ++----------+-----------------------------------------------------+--------+---------+ +| password | The password of the Pulp user | String | None | ++----------+-----------------------------------------------------+--------+---------+ + +The user should be a member of the default ``consumer-users`` role. |