diff options
Diffstat (limited to 'doc')
29 files changed, 492 insertions, 243 deletions
diff --git a/doc/appendix/guides/bootstrap.txt b/doc/appendix/guides/bootstrap.txt new file mode 100644 index 000000000..b9b5f318e --- /dev/null +++ b/doc/appendix/guides/bootstrap.txt @@ -0,0 +1,39 @@ +.. -*- mode: rst -*- + +.. _appendix-guides-bootstrap: + +========= +Bootstrap +========= + +Once you have your bcfg2 server setup and working, a common next step to +take is automating the addition of new clients. + +The method for bootstrapping your clients will vary depending on your +needs. The simplest way to go about this is to create a public default +group in ``Metadata/groups.xml``. Example: + +.. code-block:: xml + + <Group profile='true' name='basic' public='true' default='true'> + +This allows clients to freely associate themselves with this group so that +you will not be required to manually add them to ``Metadata/clients.xml`` +prior to running the client. + +.. note:: + + Reverse DNS will need to work in order to automate the process of + bootstrapping clients without first adding them to + ``Metadata/clients.xml``. + +There are command line options available on the client which allow +you to specify the options that are normally found in the client's +``/etc/bcfg2.conf``:: + + 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. diff --git a/doc/appendix/guides/centos.txt b/doc/appendix/guides/centos.txt index d89d532ba..d788891de 100644 --- a/doc/appendix/guides/centos.txt +++ b/doc/appendix/guides/centos.txt @@ -211,13 +211,17 @@ line of ``bcfg2.conf``. Then create Packages layout (as per </YUMSource> </Sources> -Due to the `Magic Groups`_, we need to modify our Metadata. Let's -add a **centos5.4** group which inherits a **centos** group -(this should replace the existing **redhat** group) present in -``/var/lib/bcfg2/Metadata/groups.xml``. The resulting file should look -something like this +Due to the :ref:`server-plugins-generators-packages-magic-groups`, +we need to modify our Metadata. Let's add a **centos5.4** group which +inherits a **centos** group (this should replace the existing **redhat** +group) present in ``/var/lib/bcfg2/Metadata/groups.xml``. The resulting +file should look something like this -.. _Magic Groups: http://trac.mcs.anl.gov/projects/bcfg2/wiki/Plugins/Packages#MagicGroups +.. note:: + + The reason we are creating a release-specific group in this case is + that the YUMSource above is specific to the 5.4 release of centos. + That is, it should not apply to other releases (5.1, 5.3, etc). .. code-block:: xml @@ -240,7 +244,7 @@ something like this .. note:: When editing your xml files by hand, it is useful to occasionally run - `bcfg2-repo-validate` to ensure that your xml validates properly. + `bcfg2-lint` to ensure that your xml validates properly. The final thing we need is for the client to have the proper arch group membership. For this, we will make use of the @@ -431,7 +435,7 @@ packages. Currently, the way to manage them is using :ref:`BoundEntries .. code-block:: xml <Bundle name='base-packages'> - <BoundPackage name="gpg-pubkey" type="rpm"> + <BoundPackage name="gpg-pubkey" type="rpm" version="foo"> <Instance simplefile="/etc/pki/rpm-gpg/RPM-GPG-KEY-CentOS-5" version="e8562897" release="459f07a4"/> <Instance simplefile="/etc/pki/rpm-gpg/RPM-GPG-KEY-EPEL" version="217521f6" release="45e8a532"/> </BoundPackage> @@ -452,6 +456,10 @@ packages. Currently, the way to manage them is using :ref:`BoundEntries <Package name='yum'/> </Bundle> +.. note:: + + version="foo" is just a dummy attribute for the gpg-pubkey Package + To actually push the gpg keys out via Bcfg2, you will need to manage the files as well. This can be done by adding Path entries for each of the gpg keys you want to manage @@ -461,7 +469,7 @@ gpg keys you want to manage <Bundle name='base-packages'> <Path name='/etc/pki/rpm-gpg/RPM-GPG-KEY-CentOS-5'/> <Path name='/etc/pki/rpm-gpg/RPM-GPG-KEY-EPEL'/> - <BoundPackage name="gpg-pubkey" type="rpm"> + <BoundPackage name="gpg-pubkey" type="rpm" version="foo"> <Instance simplefile="/etc/pki/rpm-gpg/RPM-GPG-KEY-CentOS-5" version="e8562897" release="459f07a4"/> <Instance simplefile="/etc/pki/rpm-gpg/RPM-GPG-KEY-EPEL" version="217521f6" release="45e8a532"/> </BoundPackage> @@ -578,3 +586,8 @@ Dynamic (web) reports ===================== See installation instructions at :ref:`reports-dynamic` + +Next Steps +========== + +:ref:`getting_started-index-next-steps` diff --git a/doc/appendix/guides/converging_rhel5.txt b/doc/appendix/guides/converging_rhel5.txt index 7581d307f..d6a9d2d1c 100644 --- a/doc/appendix/guides/converging_rhel5.txt +++ b/doc/appendix/guides/converging_rhel5.txt @@ -81,7 +81,7 @@ For a "Package" <Bundle name='keys'> <!-- GPG keys --> - <BoundPackage name="gpg-pubkey" type="yum"> + <BoundPackage name="gpg-pubkey" type="rpm" version="foo"> <Instance simplefile="/etc/pki/rpm-gpg/RPM-GPG-KEY-EPEL" version="217521f6" release="45e8a532"/> <Instance simplefile="/etc/pki/rpm-gpg/RPM-GPG-KEY-redhat-release" version="37017186" release="45761324"/> </BoundPackage> diff --git a/doc/appendix/guides/fedora.txt b/doc/appendix/guides/fedora.txt index 4e3244eaa..db23e94bf 100644 --- a/doc/appendix/guides/fedora.txt +++ b/doc/appendix/guides/fedora.txt @@ -216,13 +216,18 @@ mirror near your location according the `Mirror list`_ . </YUMSource> </Sources> -.. _Magic Groups: http://trac.mcs.anl.gov/projects/bcfg2/wiki/Plugins/Packages#MagicGroups -Due to the `Magic Groups`_, we need to modify our Metadata. Let's -add a **fedora13** group which inherits a **fedora** group -(this should replace the existing **redhat** group) present in -``/var/lib/bcfg2/Metadata/groups.xml``. The resulting file should look -something like this +Due to the :ref:`server-plugins-generators-packages-magic-groups`, +we need to modify our Metadata. Let's add a **fedora13** group which +inherits a **fedora** group (this should replace the existing **redhat** +group) present in ``/var/lib/bcfg2/Metadata/groups.xml``. The resulting +file should look something like this + +.. note:: + + The reason we are creating a release-specific group in this case is + that the YUMSource above is specific to the 13th release of fedora. + That is, it should not apply to other releases (14, 15, etc). .. code-block:: xml @@ -244,8 +249,7 @@ something like this .. note:: When editing your xml files by hand, it is useful to occasionally - run ``bcfg2-repo-validate`` to ensure that your xml validates - properly. + run ``bcfg2-lint`` to ensure that your xml validates properly. Add a probe +++++++++++ @@ -339,7 +343,7 @@ Bundle now looks like this .. code-block:: xml <Bundle name='base-packages'> - <BoundPackage name="gpg-pubkey" type="rpm"> + <BoundPackage name="gpg-pubkey" type="rpm" version="foo"> <Instance simplefile="/etc/pki/rpm-gpg/RPM-GPG-KEY-CentOS-5" version="e8562897" release="459f07a4"/> <Instance simplefile="/etc/pki/rpm-gpg/RPM-GPG-KEY-EPEL" version="217521f6" release="45e8a532"/> </BoundPackage> @@ -360,6 +364,10 @@ Bundle now looks like this <Package name='yum'/> </Bundle> +.. note:: + + version="foo" is just a dummy attribute for the gpg-pubkey Package + To actually push the gpg keys out via Bcfg2, you will need to manage the files as well. This can be done by adding Path entries for each of the gpg keys you want to manage @@ -369,7 +377,7 @@ of the gpg keys you want to manage <Bundle name='base-packages'> <Path name='/etc/pki/rpm-gpg/RPM-GPG-KEY-CentOS-5'/> <Path name='/etc/pki/rpm-gpg/RPM-GPG-KEY-EPEL'/> - <BoundPackage name="gpg-pubkey" type="rpm"> + <BoundPackage name="gpg-pubkey" type="rpm" version="foo"> <Instance simplefile="/etc/pki/rpm-gpg/RPM-GPG-KEY-CentOS-5" version="e8562897" release="459f07a4"/> <Instance simplefile="/etc/pki/rpm-gpg/RPM-GPG-KEY-EPEL" version="217521f6" release="45e8a532"/> </BoundPackage> diff --git a/doc/appendix/guides/import-existing-ssh-keys.txt b/doc/appendix/guides/import-existing-ssh-keys.txt index e606ba908..64a1b62cd 100644 --- a/doc/appendix/guides/import-existing-ssh-keys.txt +++ b/doc/appendix/guides/import-existing-ssh-keys.txt @@ -46,7 +46,7 @@ Validate your repository Validation can be performed using the following command:: - bcfg2-repo-validate -v + bcfg2-lint Run the bcfg2 client ==================== diff --git a/doc/appendix/guides/ubuntu.txt b/doc/appendix/guides/ubuntu.txt index 24338c6d2..a597a5492 100644 --- a/doc/appendix/guides/ubuntu.txt +++ b/doc/appendix/guides/ubuntu.txt @@ -167,14 +167,39 @@ Create Packages layout (as per :ref:`packages-exampleusage`) in <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> </Sources> -Due to the `Magic Groups`_, we need to modify our Metadata. Let's add -an **ubuntu-lucid** group which inherits the **ubuntu** group already -present in ``/var/lib/bcfg2/Metadata/groups.xml``. The resulting file -should look something like this +Due to the :ref:`server-plugins-generators-packages-magic-groups`, +we need to modify our Metadata. Let's add an **ubuntu-lucid** +group which inherits the **ubuntu** group already present in +``/var/lib/bcfg2/Metadata/groups.xml``. The resulting file should look +something like this + +.. note:: -.. _Magic Groups: http://trac.mcs.anl.gov/projects/bcfg2/wiki/Plugins/Packages#MagicGroups + The reason we are creating a release-specific group in this case is + that the APTSource above is specific to the lucid release of ubuntu. + That is, it should not apply to other releases (hardy, maverick, etc). .. code-block:: xml @@ -197,7 +222,7 @@ should look something like this .. note:: When editing your xml files by hand, it is useful to occasionally run - `bcfg2-repo-validate` to ensure that your xml validates properly. + `bcfg2-lint` to ensure that your xml validates properly. The last thing we need is for the client to have the proper arch group membership. For this, we will make use of the @@ -481,13 +506,8 @@ Now we run the client and see there are no more unmanaged entries! :: managed. Please see :ref:`unsorted-writing_specification` for more details. -Dynamic (web) reports -===================== - -See installation instructions at :ref:`appendix-guides-web-reports-install` - Upstart -======= +^^^^^^^ Upstart services are defined like this: @@ -501,3 +521,13 @@ Some Upstart services require additional parameters, like network-interface and <Service name="network-interface" status="on" type="upstart" parameters="INTERFACE=eth0"/> <Service name="bridge-network-interface" status="on" type="upstart" parameters="INTERFACE=br0"/> + +Dynamic (web) reports +===================== + +See installation instructions at :ref:`appendix-guides-web-reports-install` + +Next Steps +========== + +:ref:`getting_started-index-next-steps` diff --git a/doc/client/metadata.txt b/doc/client/metadata.txt index 2a19f3a1a..27870ba9a 100644 --- a/doc/client/metadata.txt +++ b/doc/client/metadata.txt @@ -22,22 +22,23 @@ interaction: * Statistics Upload This construction process spans several server plugins. The -:ref:`server-plugins-grouping-metadata` is responsible for initial -instance creation, including the client hostname, profile, and basic -group memberships. After this initial creation, Connector plugins (such as -:ref:`server-plugins-probes-index` or :ref:`server-plugins-properties`) -can add additional group memberships for clients. These memberships -are merged into the instance; that is, the new group memberships are -treated as if they were included in groups.xml. If any of these groups -are defined in groups.xml, then groups included there are included in -the ClientMetadata instance group list. At the end of this process, the -ClientMetadata instance has its complete set of group memberships. At this -point, each connector plugin has the opportunity to return an additional -object which will be placed in an attribute corresponding to the Connector -name. For example, the Probes plugin returns a dictionary of probe name -to probe result mappings for the client. This dictionary is available as -the "Probes" attribute. With this, ClientMetadata resolution is complete, -and the ClientMetadata instance can be used by the rest of the system. +:ref:`server-plugins-grouping-metadata` is responsible for +initial instance creation, including the client hostname, +profile, and basic group memberships. After this initial creation, +Connector plugins (such as :ref:`server-plugins-probes-index` or +:ref:`server-plugins-connectors-properties`) can add additional group +memberships for clients. These memberships are merged into the instance; +that is, the new group memberships are treated as if they were included +in groups.xml. If any of these groups are defined in groups.xml, +then groups included there are included in the ClientMetadata instance +group list. At the end of this process, the ClientMetadata instance has +its complete set of group memberships. At this point, each connector +plugin has the opportunity to return an additional object which will be +placed in an attribute corresponding to the Connector name. For example, +the Probes plugin returns a dictionary of probe name to probe result +mappings for the client. This dictionary is available as the "Probes" +attribute. With this, ClientMetadata resolution is complete, and the +ClientMetadata instance can be used by the rest of the system. Contents ======== diff --git a/doc/client/tools.txt b/doc/client/tools.txt index d9a9b76f4..bedcb9ab9 100644 --- a/doc/client/tools.txt +++ b/doc/client/tools.txt @@ -57,11 +57,15 @@ Chkconfig Tool to manage services (primarily on Redhat based distros). -.. note:: Start and stop are standard arguments, but the one for reload - isn't consistent across services. You can specify which argument - to use with the `restart` property in Service tags. Example: - ``<Service name="ftp" restart="condrestart" status="on" - type="chkconfig">`` +.. note:: + + Start and stop are standard arguments, but the one for reload + isn't consistent across services. You can specify which argument + to use with the ``target`` attribute in Service tags. Example: + + .. code-block:: xml + + <Service name="ftp" target="condrestart" status="on" type="chkconfig"/> DebInit ------- @@ -89,9 +93,13 @@ launchd Mac OS X Services. To use this tool, you must maintain a standard launch daemon .plist file in ``/Library/LaunchDaemons/`` (example ssh.plist) -and setup a ``<Service name="com.openssh.sshd" type="launchd" status="on" -/>`` entry in your config to load or unload the service. Note the name -is the ''Label'' specified inside of the .plist file +and setup an entry in your config to load or unload the service. + +.. code-block:: xml + + <Service name="com.openssh.sshd" type="launchd" status="on"/> + +Note the name is the *Label* specified inside of the .plist file Portage ------- @@ -133,7 +141,18 @@ Example legacy run service (lrc): .. code-block:: xml - <BoundService name='/etc/rc2_d/S47pppd' FMRI='lrc:/etc/rc2_d/S47pppd' status='off' type='smf'/> + <Service name='/etc/rc2_d/S47pppd' FMRI='lrc:/etc/rc2_d/S47pppd' status='off' type='smf'/> + +Systemd +------- + +Systemd service support. + +Example: + +.. code-block:: xml + + <Service name='udev' status='on' type='systemd'/> SYSV ---- diff --git a/doc/client/tools/vcs.txt b/doc/client/tools/vcs.txt new file mode 100644 index 000000000..fb9c33684 --- /dev/null +++ b/doc/client/tools/vcs.txt @@ -0,0 +1,15 @@ +.. -*- mode: rst -*- + +.. _client-tools-vcs: + +=============== +VCS Client Tool +=============== + +.. warning: This tool is currently under development. + +.. note: Currently, the only supported VCS is git. + +The VCS tool allows you to checkout particular revisions from a VCS +repository on the client to a specified path. The tool requires the +appropriate python libraries for the VCS used to be installed. diff --git a/doc/client/tools/yumng.txt b/doc/client/tools/yumng.txt index dd712ddec..c2e9161a1 100644 --- a/doc/client/tools/yumng.txt +++ b/doc/client/tools/yumng.txt @@ -18,9 +18,15 @@ and SUSE based distributions. Examples of this are: -* SLES10 and openSUSE 10.2 both install six GPG keys. From an RPM perspective this means that there are six packages with the name gpg-pubkey. -* YUM always installs, as opposed to upgrades, kernel packages. This is hard coded in YUM (actually it can be overridden in yum.conf), so systems using YUM will eventually have multiple kernel packages installed. -* Red Hat family x86_64 based systems frequently have both an x86_64 and an i386 version of the same package installed. +* SLES10 and openSUSE 10.2 both install six GPG keys. From an RPM + perspective this means that there are six packages with the name + gpg-pubkey. +* YUM always installs, as opposed to upgrades, kernel packages. This is + hard coded in YUM (actually it can be overridden in yum.conf), + so systems using YUM will eventually have multiple kernel packages + installed. +* Red Hat family x86_64 based systems frequently have both an x86_64 + and an i386 version of the same package installed. The new Pkgmgr format files with Instances are therefore the only way to accurately describe an RPM based system. It is recommended that all RPM @@ -50,7 +56,9 @@ Features * Support for per instance ignoring of individual files for the RPM verification with the Ignore tag. * Multiple package Instances with full version information listed in interactive mode. * Support for installation and removal of gpg-pubkey packages. -* Support for controlling what action is taken on package verification failure with the install_action, version_fail_action and verify_fail_action attributes. +* Support for controlling what action is taken on package + verification failure with the install_action, version_fail_action and + verify_fail_action attributes. RPMng Driver Overview diff --git a/doc/development/client-driver.txt b/doc/development/client-driver.txt index cc065dd32..32bb0aff4 100644 --- a/doc/development/client-driver.txt +++ b/doc/development/client-driver.txt @@ -10,7 +10,6 @@ driver for a configuration element type. The included example describes an existing driver, and the process that was used to create it. #. Pick a name for the driver. In this case, we picked the name RPM. -#. Add "RPM" to the ``__all__`` list in ``src/lib/Client/Tools/__init__.py`` #. Create a file in ``src/lib/Client/Tools`` with the same name (RPM.py) #. Create a class in this file with the same name (class RPM) diff --git a/doc/development/docstyleguide.txt b/doc/development/docstyleguide.txt index fda1037f3..59db58362 100644 --- a/doc/development/docstyleguide.txt +++ b/doc/development/docstyleguide.txt @@ -25,3 +25,9 @@ Basics When used alone this refers to a Bcfg2 :term:`repository`. When there is a chance for confusion, for instance in documents also talking about :term:`VCS`, be sure to use the longer Bcfg2 :term:`repository`. + +Sections +-------- + +Unless necessary, all the documentation follows the sections header +rules available at http://docs.python.org/documenting/rest.html#sections. diff --git a/doc/development/plugins.txt b/doc/development/plugins.txt index 709b9fcec..4c723f7e9 100644 --- a/doc/development/plugins.txt +++ b/doc/development/plugins.txt @@ -139,7 +139,7 @@ Example Plugin __version__ = '1' __author__ = 'me@me.com' __rmi__ = ['myfunction'] - # myfunction is not available remotely as MyPlugin.myfunction + # myfunction is now available remotely as MyPlugin.myfunction def __init__(self, core, datastore): Bcfg2.Server.Plugin.Plugin.__init__(self, core, datastore) @@ -206,8 +206,8 @@ do so. We will call our new plugin `MyMetadata`. __version__ = '$Id$' __author__ = 'bcfg-dev@mcs.anl.gov' - def __init__(self, core, datastore, watch_clients=True): - Bcfg2.Server.Plugins.Metadata.Metadata.__init__(self, core, datastore, watch_clients) + def __init__(self, core, datastore, watch_clients=True): + Bcfg2.Server.Plugins.Metadata.Metadata.__init__(self, core, datastore, watch_clients) #. Add MyMetadata to ``src/lib/Server/Plugins/__init__.py`` #. Replace Metadata with MyMetadata in the plugins line of bcfg2.conf diff --git a/doc/getting_started/index.txt b/doc/getting_started/index.txt index b256edd2d..65ac296f7 100644 --- a/doc/getting_started/index.txt +++ b/doc/getting_started/index.txt @@ -223,11 +223,13 @@ you will find that we now have a correct entry:: Done! Now we just have 242 (or more) entries to take care of! -:ref:`server-plugins-structures-bundler-index` is a relatively easy -directory to populate. You can find many samples of Bundles in the -`Bundle Repository`_, many of which can be used without editing. +:ref:`server-plugins-structures-bundler-index` is a +relatively easy directory to populate. You can find many +samples of Bundles in the :ref:`Bundler Example Repository +<server-plugins-structures-bundler-index-examples>`, many of which can +be used without editing. -.. _Bundle Repository: http://docs.bcfg2.org/server/plugins/structures/bundler/index.html#other-examples +.. _getting_started-index-next-steps: Next Steps ========== @@ -247,6 +249,9 @@ Run ``bcfg2-info``, and type help and the prompt when it comes up. ``bcfg2-admin`` can perform a variety of repository maintenance tasks. Run ``bcfg2-admin`` help for details. +Once you have the server setup, you may be interested in +:ref:`bootstrapping <appendix-guides-bootstrap>` additional clients. + Platform-specific Quickstart Notes ================================== diff --git a/doc/help/faq/general.txt b/doc/help/faq/general.txt index f8ecc9854..ba5d1fda3 100644 --- a/doc/help/faq/general.txt +++ b/doc/help/faq/general.txt @@ -29,7 +29,7 @@ exact list of platforms on which Bcfg2 works. **What pre-requisites are needed to run Bcfg2?** -Please visit the :ref:`prerequisites` section in the manual. +Please visit the :ref:`installation-prerequisites` section in the manual. **Why won't bcfg2-server start?** @@ -51,6 +51,6 @@ The bcfg2-server process logs to syslog facility LOG_DAEMON. The server produces **Is there a way to check if all repository XML files conform to schemas?** Bcfg2 comes with XML schemas describing all of the XML formats used in -the server repository. A validation command ``bcfg2-repo-validate`` is -included with the source distribution and all packages. Run it with -the ``-v`` flag to see each file and the results if its validation. +the server repository. A validation command ``bcfg2-lint`` is +included with the source distribution and all packages. ``bcfg2-lint`` +can also performs lots of other checks for common mistakes. diff --git a/doc/help/troubleshooting.txt b/doc/help/troubleshooting.txt index 0892587aa..88a0febc5 100644 --- a/doc/help/troubleshooting.txt +++ b/doc/help/troubleshooting.txt @@ -38,9 +38,8 @@ Check if all repository XML files conform to schemas ==================================================== Bcfg2 comes with XML schemas describing all of the XML formats used in -the server repository. A validation command ``bcfg2-repo-validate`` is -included with the source distribution and all packages. Run it with the --v flag to see each file and the results if its validation. +the server repository. A validation command ``bcfg2-lint`` is +included with the source distribution and all packages. If the bcfg2 server is not reflecting recent changes, try restarting the bcfg2-server process ============================================================================================= @@ -139,11 +138,27 @@ be taken to remedy them. | | | associated with a | | | | | non-profile group. | | +------------------------------+----------+---------------------+--------------+ +| Failed to decode <filename> | Server | The encoding being | [10]_ | +| Please verify you are using | | used is unable to | | +| the proper encoding | | decode the | | +| | | character present | | +| | | in this file. | | ++------------------------------+----------+---------------------+--------------+ +| Got unknown entries | Server | The Packages plugin | [11]_ | +| [list of unknown entries] | | has no knowledge of | | +| | | the listed entries | | ++------------------------------+----------+---------------------+--------------+ +| Failed to import lxml | Server | The server cannot | [12]_ | +| dependency. Shutting | | import lxml | | +| down server. | | | | ++------------------------------+----------+---------------------+--------------+ .. [1] This entry is not being bound. Ensure that a version of this entry applies to this client. -.. [2] Add a type to the generator definition for this entry +.. [2] It is possible that the type attribute for this generator entry + is undefined. You may need to add the appropriate type attribute + in the literal entry specification. .. [3] Copy the Bcfg2 server's CA certificate to the client and specify it using the **ca** option in the [communication] section of ``bcfg2.conf`` @@ -158,6 +173,18 @@ be taken to remedy them. .. [8] Ensure that the file is properly formed XML. .. [9] Fix hostname resolution for the client or ensure that the profile group is properly setup. +.. [10] Ensure the correct encoding is specified in the [components] + section of ``bcfg2.conf``. +.. [11] 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 + 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 + these packages (however, note that this package is most often + specified as a BoundPackage entry). +.. [12] Ensure that you have installed all the necessary + :ref:`installation-prerequisites`. FAQs ==== @@ -172,10 +199,12 @@ why. Why am I getting a traceback? ----------------------------- -If you get a traceback, please let us know by :ref:`reporting it -<report-a-bug>` on Trac, via the mailing list, or on IRC. Your best bet +If you get a traceback, please let us know by reporting it +on `Trac ticket tracker`_, via the mailing list, or on IRC. Your best bet to get a quick response will be to jump on IRC during the daytime (CST). +.. _Trac ticket tracker: http://bcfg2.org + What is the most common cause of "The following entries are not handled by any tool"? ------------------------------------------------------------------------------------- diff --git a/doc/installation/prerequisites.txt b/doc/installation/prerequisites.txt index c86e86774..0cb721bb9 100644 --- a/doc/installation/prerequisites.txt +++ b/doc/installation/prerequisites.txt @@ -1,6 +1,6 @@ .. -*- mode: rst -*- -.. _prerequisites: +.. _installation-prerequisites: Prerequisites ============= @@ -21,7 +21,7 @@ Bcfg2 Client +----------------------------+------------------------+--------------------------------+ | libxslt (if lxml is used) | Any | libxml2 | +----------------------------+------------------------+--------------------------------+ -| python | 2.3-2.4, 2.5-2.7 [#f1] | | +| python | 2.4 and greater [#f1] | | +----------------------------+------------------------+--------------------------------+ | lxml or elementtree [#f2]_ | Any | lxml: libxml2, libxslt, python | +----------------------------+------------------------+--------------------------------+ @@ -39,20 +39,23 @@ Bcfg2 Client Bcfg2 Server ------------ -+----------------------------+----------+--------------------------------+ -| Software | Version | Requires | -+============================+==========+================================+ -| libxml2 | 2.6.24+ | | -+----------------------------+----------+--------------------------------+ -| libxslt | Any | libxml2 | -+----------------------------+----------+--------------------------------+ -| python | 2.2-2.7 | | -+----------------------------+----------+--------------------------------+ -| lxml | 0.9+ | lxml: libxml2, libxslt, python | -+----------------------------+----------+--------------------------------+ -| gamin or fam | Any | | -+----------------------------+----------+--------------------------------+ -| python-gamin or python-fam | Any | gamin or fam, python | -+----------------------------+----------+--------------------------------+ -| M2crypto | Any | python, openssl | -+----------------------------+----------+--------------------------------+ ++-------------------------------+----------+--------------------------------+ +| Software | Version | Requires | ++===============================+==========+================================+ +| libxml2 | 2.6.24+ | | ++-------------------------------+----------+--------------------------------+ +| libxslt | Any | libxml2 | ++-------------------------------+----------+--------------------------------+ +| python | 2.2-2.7 | | ++-------------------------------+----------+--------------------------------+ +| lxml | 0.9+ | lxml: libxml2, libxslt, python | ++-------------------------------+----------+--------------------------------+ +| gamin or fam | Any | | ++-------------------------------+----------+--------------------------------+ +| python-gamin or python-fam | Any | gamin or fam, python | ++-------------------------------+----------+--------------------------------+ +| M2crypto or python-ssl (note | Any | python, openssl | +| that the ssl module is | | | +| included in python versions | | | +| 2.6 and later | | | ++-------------------------------+----------+--------------------------------+ diff --git a/doc/server/configurationentries.txt b/doc/server/configurationentries.txt index 6e6ab79f7..5602da189 100644 --- a/doc/server/configurationentries.txt +++ b/doc/server/configurationentries.txt @@ -31,7 +31,7 @@ Non-POSIX entries +-------------+---------------------+-----------------------------+ | PostInstall | PostInstall command | name | +-------------+---------------------+-----------------------------+ -| Service | System Services | name, type, status, reload | +| Service | System Services | name, type, status, target | +-------------+---------------------+-----------------------------+ POSIX entries @@ -50,9 +50,9 @@ plugin that handles the entry in the case of `Cfg`_, `TGenshi`_, or a device, directory, hardlink, symlink, etc), then you will specify both the *type* and any other necessary attributes in `Rules`_. -Running ``bcfg2-repo-validate`` will check your configuration -specification for the presence of any mandatory attributes that are -necessary for the Path type specified. +Running ``bcfg2-lint`` will check your configuration specification for +the presence of any mandatory attributes that are necessary for the +Path type specified. .. note:: A tool for converting old POSIX entries is available in the Bcfg2 source directory at tools/posixunified.py @@ -95,6 +95,10 @@ necessary for the Path type specified. | | entries | POSIX entities | group, perms | | | | | | +-------------+----------------------+-----------------+--------------------------+ +| vcs | New | Create version | vcstype (git), | +| | | control | sourceurl, revision | +| | | checkout | | ++-------------+----------------------+-----------------+--------------------------+ Keep in mind that permissions for files served up by Cfg/TGenshi/TCheetah are still handled via the traditional :ref:`server-info` mechanisms. diff --git a/doc/server/plugins/connectors/properties.txt b/doc/server/plugins/connectors/properties.txt index ae8bf0caa..1cbc4cf65 100644 --- a/doc/server/plugins/connectors/properties.txt +++ b/doc/server/plugins/connectors/properties.txt @@ -1,6 +1,6 @@ .. -*- mode: rst -*- -.. _server-plugins-properties: +.. _server-plugins-connectors-properties: ========== Properties @@ -24,17 +24,37 @@ Properties adds a new dictionary to client metadata instances that maps property file names to PropertyFile instances. PropertyFile instances contain parsed XML data as the "data" attribute. +The XML data in a property file is arbitrary, but a matching ``.xsd`` +file can be created to assign a schema to a property file, which will +be checked when running ``bcfg2-lint``. For instance, given:: + + Properties/dns-config.xml + Properties/dns-config.xsd + +``dns-config.xml`` will be validated against ``dns-config.xsd``. + Usage ===== Specific property files can be referred to in -templates as metadata.Properties[<filename>]. The +templates as ``metadata.Properties[<filename>]``. The data attribute is an LXML element object. (Documented `here <http://codespeak.net/lxml/tutorial.html#the-element-class>`_) -Currently, no access methods are defined for this data, but as we -formulate common use cases, we will add them to the !PropertyFile class -as methods. This will simplify templates. +Currently, only one access method is defined for this data, ``Match``. +``Match`` parses the Group and Client tags in the file and returns a +list of elements that apply to the client described by a set of +metadata. (See :ref:`server-plugins-structures-bundler-index` for +more details on how Group and Client tags are parsed.) For instance:: + + {% python + ntp_servers = [el.text + for el in metadata.Properties['ntp.xml'].Match(metadata): + if el.tag == "Server"] + %} + +As we formulate more common use cases, we will add them to the +!PropertyFile class as methods. This will simplify templates. Accessing Properties contents from TGenshi ========================================== diff --git a/doc/server/plugins/generators/cfg.txt b/doc/server/plugins/generators/cfg.txt index 8b40eec67..612b14bec 100644 --- a/doc/server/plugins/generators/cfg.txt +++ b/doc/server/plugins/generators/cfg.txt @@ -24,12 +24,13 @@ the files on your clients, starting at the root level. For example:: bin/ boot/ etc/ opt/ root/ usr/ var/ Specific config files go in like-named directories in this -heirarchy. For example the password file, ``/etc/passwd``, goes in -``Cfg/etc/passwd/passwd``, while the ssh pam module config file, -``/etc/pam.d/sshd``, goes in ``Cfg/etc/pam.d/sshd/sshd``. The reason -for the like-name directory is to allow multiple versions of each file -to exist, as described below. Note that these files are exact copies of -what will appear on the client machine - no templates, XML wrappers, etc. +heirarchy. For example the password file, ``/etc/passwd``, goes +in ``Cfg/etc/passwd/passwd``, while the ssh pam module config file, +``/etc/pam.d/sshd``, goes in ``Cfg/etc/pam.d/sshd/sshd``. The reason for +the like-name directory is to allow multiple versions of each file to +exist, as described below. Note that these files are exact copies of what +will appear on the client machine (except when using genshi templating -- +see below). Group-Specific Files ==================== @@ -157,6 +158,17 @@ will be processed using the new template style (like .newtxt in the TGenshi plugin). Templates can be host and group specific as well. Deltas will not be processed for any genshi base file. +.. note:: + + If you are using genshi templating in combination with host-specific + or group-specific files, you will need to ensure that the ``.genshi`` + extensions is at the **end** of the filename. Using the examples + from above for *host.example.com* and group *server* you would have + the following:: + + Cfg/etc/fstab/fstab.H_host.example.com.genshi + Cfg/etc/fstab/fstab.G50_server.genshi + File permissions ================ diff --git a/doc/server/plugins/generators/nagiosgen.txt b/doc/server/plugins/generators/nagiosgen.txt index 196f1e76b..b839c10ca 100644 --- a/doc/server/plugins/generators/nagiosgen.txt +++ b/doc/server/plugins/generators/nagiosgen.txt @@ -169,3 +169,37 @@ Note that some of these files are built on demand, each time a client in group "nagios-server" checks in with the Bcfg2 server. Local nagios instances can be configured to use the NagiosGen directory in the Bcfg2 repository directly. + +Fine-Grained Configuration +========================== + +NagiosGen can be configured in excruciating detail by editing +``NagiosGen/config.xml``, which will let you set individual Nagios +options for hosts or groups. E.g.: + +.. code-block:: xml + + <NagiosGen> + <Group name="datacenter-2"> + <Option name="parents">dc-2-switch</Option> + <Group> + <Group name="non-production"> + <Option name="notification_period">workhours</Option> + <Option name="notification_options">d</Option> + </Group> + <Client name="foo.example.com"> + <Option name="max_check_attempts">10</Option> + </Client> + </NagiosGen> + +Obviously the sort of fine-grained control you get from this overlaps +to some degree with Nagios' own templating, so use it wisely and in +moderation. + +``NagiosGen/config.xml`` replaces the files +``Properties/NagiosGen.xml`` and ``NagiosGen/parents.xml`` in older +versions of Bcfg2; your old configs can be migrated using the +``nagiosgen-convert.py`` tool. The plugin does contain a +backwards-compatibility layer for those older config files, but +``NagiosGen/config.xml`` must exist (even if empty) for the plugin to +function. diff --git a/doc/server/plugins/generators/packages.txt b/doc/server/plugins/generators/packages.txt index d1a68b16e..90cd19de4 100644 --- a/doc/server/plugins/generators/packages.txt +++ b/doc/server/plugins/generators/packages.txt @@ -15,6 +15,8 @@ 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: + "Magic Groups" ============== @@ -152,14 +154,15 @@ like this: </Sources> .. note:: + 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 following line immediately following the URL: + 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 following line immediately + following the **URL**: .. versionadded:: 1.1.0 @@ -184,6 +187,8 @@ Yum sources can be similarly specified: </YUMSource> </Sources> +For sources with a **URL** tag, the **Version** tag is also necessary. + .. note:: There is also a RawURL syntax for specifying APT or YUM sources that don't follow the conventional layout: @@ -268,7 +273,7 @@ Validation ========== A schema for Packages/config.xml is included; config.xml can be validated -using ``bcfg2-repo-validate``. +using ``bcfg2-lint``. .. note:: The schema requires that elements be specified in the above order. diff --git a/doc/server/plugins/generators/rules.txt b/doc/server/plugins/generators/rules.txt index cff78a8ee..a2953ad08 100644 --- a/doc/server/plugins/generators/rules.txt +++ b/doc/server/plugins/generators/rules.txt @@ -116,34 +116,28 @@ See :ref:`client-tools-actions` Service Tag ----------- -+------------+--------------------------+---------------------------------------+ -| Name | Description | Values | -+============+==========================+=======================================+ -| mode | Per Service Mode (New in | (manual|default|supervised) | -| | 1.0) | | -+------------+--------------------------+---------------------------------------+ -| name | Service Name | String | -+------------+--------------------------+---------------------------------------+ -| status | Should the service be | (on|off) | -| | on or off (default: | | -| | off). | | -+------------+--------------------------+---------------------------------------+ -| target | Service command for | String | -| | restart (default: | | -| | restart) | | -+------------+--------------------------+---------------------------------------+ -| type | Driver to use on the | (chkconfig|deb|rc-update|smf|upstart) | -| | client to manage this | | -| | service. | | -+------------+--------------------------+---------------------------------------+ -| sequence | Order for service | integer | -| | startup (debian services | | -| | only) | | -+------------+--------------------------+---------------------------------------+ -| parameters | Pass parameters to | String | -| | service (Upstart | | -| | services only) | | -+------------+--------------------------+---------------------------------------+ ++------------+-------------------------------+-----------------------------------------------+ +| Name | Description | Values | ++============+===============================+===============================================+ +| mode | Per Service Mode (New in 1.0) | (manual | default | supervised) | ++------------+-------------------------------+-----------------------------------------------+ +| 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. | | ++------------+-------------------------------+-----------------------------------------------+ +| sequence | Order for service startup | integer | +| | (debian services only) | | ++------------+-------------------------------+-----------------------------------------------+ +| parameters | Pass parameters to service | String | +| | (Upstart services only) | | ++------------+-------------------------------+-----------------------------------------------+ Service mode descriptions ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -153,6 +147,12 @@ Service mode descriptions * manual * do not start/stop/restart this service + * service installation is not performed + +* interactive_only + + * only attempt to start/stop/restart this service if the client is run interactively + * service installation is performed * default @@ -163,6 +163,21 @@ Service mode descriptions * default and ensure service is running (or stopped) when verification is performed * deprecates supervised='true' +Service status descriptions +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* on + + * start the service at boot time + +* off + + * don't start the service at boot time + +* ignore + + * don't check the status, leave it as-is (valid for deb and upstart services only) + Client Tag ---------- diff --git a/doc/server/plugins/generators/sslca.txt b/doc/server/plugins/generators/sslca.txt index ebc625e11..c91905d78 100644 --- a/doc/server/plugins/generators/sslca.txt +++ b/doc/server/plugins/generators/sslca.txt @@ -34,39 +34,39 @@ must contain full (not relative) paths. server -- This enabled the SSLCA plugin on the Bcfg2 server. #. Add a section to your ``/etc/bcfg2.conf`` called sslca_foo, replacing foo -with the name you wish to give your CA so you can reference it in certificate -definitions. + with the name you wish to give your CA so you can reference it in certificate + definitions. #. Under that section, add an entry for ``config`` that gives the location of -the openssl configuration file for your CA. + the openssl configuration file for your CA. #. If necessary, add an entry for ``passphrase`` containing the passphrase for -the CA's private key. We store this in ``/etc/bcfg2.conf`` as the permissions -on that file should have it only readable by the bcfg2 user. If no passphrase -is entry exists, it is assumed that the private key is stored unencrypted. + the CA's private key. We store this in ``/etc/bcfg2.conf`` as the permissions + on that file should have it only readable by the bcfg2 user. If no passphrase + is entry exists, it is assumed that the private key is stored unencrypted. #. Add an entry ``chaincert`` that points to the location of your ssl chaining -certificate. This is used when preexisting certifcate hostfiles are found, so -that they can be validated and only regenerated if they no longer meet the -specification. + certificate. This is used when preexisting certifcate hostfiles are found, so + that they can be validated and only regenerated if they no longer meet the + specification. #. Once all this is done, you should have a section in your ``/etc/bcfg2.conf`` -that looks similar to the following: + that looks similar to the following:: - [sslca_default] - config = /etc/pki/CA/openssl.cnf - passphrase = youReallyThinkIdShareThis? - chaincert = /etc/pki/CA/chaincert.crt + [sslca_default] + config = /etc/pki/CA/openssl.cnf + passphrase = youReallyThinkIdShareThis? + chaincert = /etc/pki/CA/chaincert.crt #. You are now ready to create key and certificate definitions. For this -example we'll assume you've added Path entries for the key, -``/etc/pki/tls/private/localhost.key``, and the certificate, -``/etc/pki/tls/certs/localhost.crt`` to a bundle or base. + example we'll assume you've added Path entries for the key, + ``/etc/pki/tls/private/localhost.key``, and the certificate, + ``/etc/pki/tls/certs/localhost.crt`` to a bundle or base. #. Defining a key or certificate is similar to defining a TGenshi template. -Under your Bcfg2's SSLCA directory, create the directory structure to match the -path to your key. In this case this would be something like -``/var/lib/bcfg2/SSLCA/etc/pki/tls/private/localhost.key``. + Under your Bcfg2's SSLCA directory, create the directory structure to match the + path to your key. In this case this would be something like + ``/var/lib/bcfg2/SSLCA/etc/pki/tls/private/localhost.key``. #. Within that directory, create a ``key.xml`` file containing the following: @@ -77,11 +77,11 @@ path to your key. In this case this would be something like </KeyInfo> #. This will cause the generation of an 2048 bit RSA key when a client requests -that Path. Alternatively you can specify ``dsa`` as the keytype, or a different -number of bits. + that Path. Alternatively you can specify ``dsa`` as the keytype, or a different + number of bits. #. Similarly, create the matching directory structure for the certificate path, -and a ``cert.xml`` containinng the following: + and a ``cert.xml`` containinng the following: .. code-block:: xml @@ -90,9 +90,9 @@ and a ``cert.xml`` containinng the following: </CertInfo> #. When a client requests the cert path, a certificate will be generated using -the key hostfile at the specified key location, using the CA matching the ca -attribute. ie. ca="default" will match [sslca_default] in your -``/etc/bcfg2.conf`` + the key hostfile at the specified key location, using the CA matching the ca + attribute. ie. ca="default" will match [sslca_default] in your + ``/etc/bcfg2.conf`` TODO ==== diff --git a/doc/server/plugins/generators/tcheetah.txt b/doc/server/plugins/generators/tcheetah.txt index f2ca6c87c..ef8bb5513 100644 --- a/doc/server/plugins/generators/tcheetah.txt +++ b/doc/server/plugins/generators/tcheetah.txt @@ -50,6 +50,12 @@ self.metadata is an instance of the class ClientMetadata and documented self.metadata.Properties.data ============================= +.. note:: + + If you want to use Properties, you will need to enable the + :ref:`server-plugins-connectors-properties` plugin in + ``/etc/bcfg2.conf``. + Properties.data 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. @@ -78,6 +84,12 @@ on the host 'www.example.com':: ${self.metadata.Properties['example.xml'].data.xpath($path)[0].text} ${self.metadata.Properties['example.xml'].data.xpath(path)[0].text} +Other Variables +=============== + +* **Template.searchList(self)[1]['path']** is the Path name specified in a Bundle +* **Template.searchList(self)[1]['source_path']** is the path to the TCheetah template on the Bcfg2 server + Simple Example ============== @@ -92,6 +104,8 @@ directory. Below is a simple example a file ``/foo``. > buildfile /foo <clientname> Hostname is $self.metadata.hostname + Filename is $Template.searchList(self)[1]['path'] + Template is $Template.searchList(self)[1]['source_path'] Groups: #for $group in $self.metadata.groups: * $group @@ -124,6 +138,8 @@ current client probe state. <Path type="file" name="/foo" owner="root" perms="0624" group="root"> Hostname is topaz.mcs.anl.gov + Filename is /foo + Template is /var/lib/bcfg2/TCheetah/foo/template Groups: * desktop * mcs-base diff --git a/doc/server/plugins/generators/tgenshi/index.txt b/doc/server/plugins/generators/tgenshi/index.txt index c1970ee0d..0fc541b52 100644 --- a/doc/server/plugins/generators/tgenshi/index.txt +++ b/doc/server/plugins/generators/tgenshi/index.txt @@ -48,8 +48,11 @@ supported. Inside of templates =================== -* **metadata** is the client's :ref:`metadata <server-plugins-grouping-metadata-clientmetadata>` -* **properties.properties** is an xml document of unstructured data +* **metadata** is the client's :ref:`metadata + <server-plugins-grouping-metadata-clientmetadata>` +* **metadata.Properties** is an xml document of unstructured data (only + available when used in conjunction with the + :ref:`server-plugins-connectors-properties` plugin) * **name** is the path name specified in bcfg * **path** is the path to the TGenshi template diff --git a/doc/server/plugins/grouping/metadata.txt b/doc/server/plugins/grouping/metadata.txt index 1c915e2cf..43cc6a2d7 100644 --- a/doc/server/plugins/grouping/metadata.txt +++ b/doc/server/plugins/grouping/metadata.txt @@ -217,9 +217,9 @@ useful results: </Groups> Each of the included groups files has the same format. These files are -properly validated by ``bcfg2-repo-validate``. This mechanism is -useful for composing group definitions from multiple sources, or -setting different permissions in an svn repository. +properly validated by ``bcfg2-lint``. This mechanism is useful for +composing group definitions from multiple sources, or setting +different permissions in an svn repository. Probes ====== diff --git a/doc/server/plugins/structures/bundler/index.txt b/doc/server/plugins/structures/bundler/index.txt index 0d0054a2c..9fd897385 100644 --- a/doc/server/plugins/structures/bundler/index.txt +++ b/doc/server/plugins/structures/bundler/index.txt @@ -16,14 +16,15 @@ entries. For example, a bundle could say that the configuration file describe the particular version of ``/etc/passwd`` that a given client will receive. -Groups can be used inside of bundles to differentiate which entries -particular clients will recieve; this is useful for the case where -entries are named differently across systems; for example, one linux -distro may have a package called openssh while another uses the name -ssh. Configuration entries nested inside of Group elements only apply -to clients who are a member of those groups; multiple nested groups must -all apply. Also, groups may be negated; entries included in such groups -will only apply to clients who are not a member of said group. +Group and Client tags can be used inside of bundles to differentiate +which entries particular clients will recieve; this is useful for the +case where entries are named differently across systems; for example, +one linux distro may have a package called openssh while another uses +the name ssh. Configuration entries nested inside of Group elements +only apply to clients who are a member of those groups; multiple +nested groups must all apply. Also, groups may be negated; entries +included in such groups will only apply to clients who are not a +member of said group. The same applies to Client elements. The following is an annotated copy of a bundle: @@ -54,20 +55,25 @@ The following is an annotated copy of a bundle: <Package name='ssh'/> <Service name='ssh'/> </Group> + <Client name='trust.example.com'> + <Path name='/etc/ssh/shosts.equiv'/> + </Client> </Bundle> -In this bundle, most of the entries are common to all systems. Clients in -group **deb** get one extra package and service, while clients in group -**rpm** get two extra packages and an extra service. In addition, clients -in group **fedora** *and* group **rpm** get one extra package entries, -unless they are not in the **fc14** group, in which case, they get an -extra package. Notice that this file doesn't describe which versions -of these entries that clients should get, only that they should get -them. (Admittedly, this example is slightly contrived, but demonstrates -how group entries can be used in bundles) +In this bundle, most of the entries are common to all systems. Clients +in group **deb** get one extra package and service, while clients in +group **rpm** get two extra packages and an extra service. In +addition, clients in group **fedora** *and* group **rpm** get one +extra package entries, unless they are not in the **fc14** group, in +which case, they get an extra package. The client +**trust.example.com** gets one extra file that is not distributed to +any other clients. Notice that this file doesn't describe which +versions of these entries that clients should get, only that they +should get them. (Admittedly, this example is slightly contrived, but +demonstrates how group entries can be used in bundles) +----------------------------+-------------------------------+ -| Group | Entry | +| Group/Hostname | Entry | +============================+===============================+ | all | /etc/ssh/ssh_host_dsa_key | +----------------------------+-------------------------------+ @@ -101,6 +107,8 @@ how group entries can be used in bundles) +----------------------------+-------------------------------+ | deb | Service ssh | +----------------------------+-------------------------------+ +| trust.example.com | /etc/ssh/shosts.equiv | ++----------------------------+-------------------------------+ Genshi templates ================ @@ -220,6 +228,8 @@ 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. +.. _server-plugins-structures-bundler-index-examples: + Other examples ============== diff --git a/doc/unsorted/help.txt b/doc/unsorted/help.txt deleted file mode 100644 index 155dbf77c..000000000 --- a/doc/unsorted/help.txt +++ /dev/null @@ -1,45 +0,0 @@ -.. -*- mode: rst -*- - -.. _unsorted-help: - -================ -Ways to get help -================ - -Interactive Help -================ - -* [wiki:IRCChannel IRC Channel, with indexed archives] -* [wiki:MailingList Mailing list, with indexed archives] - -Note that the IRC channel tends to be much busier than the mailing list; use whichever seems most appropriate for your query, but don't let the lack of mailing list activity make you think the project isn't active. - -Frequently Asked Questions -========================== - -* [wiki:FAQ The FAQ] - -Examples -======== - -* There are examples sprinkled throughout this wiki; we should link to them from here. -* The [http://www.fsf.org Free Software Foundation] is (very slowly) working towards having configurations for the majority of the machines it administers available via [http://config.fsf.org config.fsf.org]. This is a tie-in with the [http://autonomo.us/2008/07/franklin-street-statement/ Franklin Street Statement on Freedom and Network Services] (FSF offices are on Franklin Street). Documentation on how to have a public access Bcfg2 configuration repository will be at PublicRepository. - -Manuals -======= - -* The current canonical source of documentation are pages on this wiki ([wiki:UsingBcfg2]). Please mail the MailingList for editor access to this wiki. -* There is a printed manual in the SAGE short topics series, "!#19: Configuration Management with Bcfg2", that you can [https://db.usenix.org/cgi-bin/sage/booklets/order.cgi order] for $20 (or get for free if you are a [http://www.sage.org/index.html SAGE] member and haven't gotten a booklet yet during your current membership year). The book includes documentation up to and including most features in Bcfg2 0.9.6. Note that all proceeds from the sale of this book go to SAGE. - -FLOSS Manual Project -==================== - -A project is getting started to make a user-contributed manual using the [http://en.flossmanuals.net/ FLOSS Manuals] web site and tools. The intention is for this manual to be based on but not a verbatim copy of the information on the wiki, formatted in a way that is easier for new users to read, and written mostly by users of Bcfg2, rather than the authors of Bcfg2. This manual will also be free (as in freedom and price). - -One important point is that new contributors can get edit access to the manual in about a minute, and the manual is edited via WYSIWYG tools, so there should be pretty much no barrier for new manual authors to get started. - -There will be an announcement to the mailing list about this soon. - -If you are seriously interested in dedicating time to this manual, it would make sense to read the [http://en.flossmanuals.net/FLOSSManuals FLOSS Manuals Manual] (free online) and the [https://db.usenix.org/cgi-bin/sage/booklets/order.cgi Configuration Management with Bcfg2] manual ($20). If you are willing to commit time to manual writing, would like physical copies of these manuals, and purchasing them would be a financial hardship for you, email [http://pobox.com/~dclark Danny Clark] at dclark@pobox.com (ping djbclark on [wiki:IRCChannel #bcfg2 irc] if you don't get a reply) with your postal address (don't be shy, I already bought a bunch of these, and they aren't doing much good sitting on my shelf :-). - -You can get to the Bcfg2 FLOSS Manual at http://docs.bcfg2.org (which just redirects to http://en.flossmanuals.net/bin/view/BCFG2). |