diff options
Diffstat (limited to 'doc')
33 files changed, 753 insertions, 311 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..0b5b83211 100644 --- a/doc/appendix/guides/centos.txt +++ b/doc/appendix/guides/centos.txt @@ -195,37 +195,41 @@ line of ``bcfg2.conf``. Then create Packages layout (as per <Sources> <!-- CentOS (5.4) sources --> <YUMSource> - <Group>centos5.4</Group> + <Group>centos-5.4</Group> <RawURL>http://mrepo/centos5-x86_64/RPMS.os</RawURL> <Arch>x86_64</Arch> </YUMSource> <YUMSource> - <Group>centos5.4</Group> + <Group>centos-5.4</Group> <RawURL>http://mrepo/centos5-x86_64/RPMS.updates</RawURL> <Arch>x86_64</Arch> </YUMSource> <YUMSource> - <Group>centos5.4</Group> + <Group>centos-5.4</Group> <RawURL>http://mrepo/centos5-x86_64/RPMS.extras</RawURL> <Arch>x86_64</Arch> </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 <Groups version='3.0'> <Group profile='true' public='true' default='true' name='basic'> - <Group name='centos5.4'/> + <Group name='centos-5.4'/> </Group> - <Group name='centos5.4'> + <Group name='centos-5.4'> <Group name='centos'/> </Group> <Group name='ubuntu'/> @@ -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 17bc391bd..5fe1500f4 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 ============================================================================================= @@ -82,90 +81,150 @@ Type `help` in bcfg2-info for more information. Error Messages ============== -This page describes error messages produced by Bcfg2 and steps that can +The tables below describe error messages produced by Bcfg2 and steps that can be taken to remedy them. +Client Errors +------------- + +------------------------------+----------+---------------------+--------------+ | Error | Location | Meaning | Repair | +==============================+==========+=====================+==============+ -| Incomplete information for | Client | The described entry | [1]_ | +| Incomplete information for | Client | The described entry | [c1]_ | | entry <EntryTag>:<EntryName> | | is not fully | | | cannot verify | | specified by the | | | | | server, so no | | | | | verification can be | | | | | performed. | | +------------------------------+----------+---------------------+--------------+ -| Incomplete information for | Client | The described entry | [1]_ | +| Incomplete information for | Client | The described entry | [c1]_ | | entry <EntryTag>:<EntryName> | | is not fully | | | cannot install | | specified by the | | | | | server, so no | | | | | verification can be | | | | | performed. | | +------------------------------+----------+---------------------+--------------+ -| The following entries are | Client | The client cannot | [2]_ | +| The following entries are | Client | The client cannot | [c2]_ | | not handled by any tool: | | figure out how to | | | <EntryTag>:<EntryName> | | handle this entry. | | +------------------------------+----------+---------------------+--------------+ -| No ca is specified. Cannot | Client | The client is | [3]_ | +| No ca is specified. Cannot | Client | The client is | [c3]_ | | authenticate the server with | | unable to verify | | | SSL. | | the server | | +------------------------------+----------+---------------------+--------------+ -| Failed to bind entry: | Server | The server was | [4]_ | +| GID normalization failed for | Client | The client is | [c4]_ | +| FILENAME. Does group GROUP | | unable to convert | | +| exist? | | the group GROUP to | | +| | | a usable GID | | ++------------------------------+----------+---------------------+--------------+ +| UID normalization failed for | Client | The client is | [c5]_ | +| FILENAME. Does owner OWNER | | unable to convert | | +| exist? | | the owner OWNER to | | +| | | a usable UID | | ++------------------------------+----------+---------------------+--------------+ + + +.. [c1] This entry is not being bound. Ensure that a version of this + entry applies to this client. +.. [c2] 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. +.. [c3] Copy the Bcfg2 server's CA certificate to the client and specify it + using the **ca** option in the [communication] section of + ``bcfg2.conf`` +.. [c4] If the group doesn't exist, you need to specify the correct one + in an :ref:`info.xml <server-info>` file or set the default group + appropriately. +.. [c5] If the owner doesn't exist, you need to specify the correct one + in an :ref:`info.xml <server-info>` file or set the default owner + appropriately. + +Server Errors +------------- + ++------------------------------+----------+---------------------+--------------+ +| Error | Location | Meaning | Repair | ++==============================+==========+=====================+==============+ +| Failed to bind entry: | Server | The server was | [s1]_ | | <EntryTag> <EntryName> | | unable to find a | | | | | suitable version of | | | | | entry for client. | | +------------------------------+----------+---------------------+--------------+ -| Failed to bind to socket | Server | The server was | [5]_ | +| Failed to bind to socket | Server | The server was | [s2]_ | | | | unable to bind to | | | | | the tcp server | | | | | socket. | | +------------------------------+----------+---------------------+--------------+ -| Failed to load | Server | The server was | [6]_ | +| Failed to load | Server | The server was | [s3]_ | | ssl key <path> | | unable to read and | | | | | process the ssl key.| | +------------------------------+----------+---------------------+--------------+ -| Failed to read file <path> | Server | The server failed | [7]_ | +| Failed to read file <path> | Server | The server failed | [s4]_ | | | | to read the | | | | | specified file | | +------------------------------+----------+---------------------+--------------+ -| Failed to parse file <path> | Server | The server failed | [8]_ | +| Failed to parse file <path> | Server | The server failed | [s5]_ | | | | to parse the | | | | | specified XML file | | +------------------------------+----------+---------------------+--------------+ -| Client metadata resolution | Server | The server cannot | [9]_ | +| Client metadata resolution | Server | The server cannot | [s6]_ | | error for <IP> | | resolve the client | | | | | hostname or the | | | | | client is | | | | | associated with a | | | | | non-profile group. | | +------------------------------+----------+---------------------+--------------+ -| Failed to decode <filename> | Server | The encoding being | [10]_ | +| Failed to decode <filename> | Server | The encoding being | [s7]_ | | 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 | [s8]_ | +| [list of unknown entries] | | has no knowledge of | | +| | | the listed entries | | ++------------------------------+----------+---------------------+--------------+ +| Failed to import lxml | Server | The server cannot | [s9]_ | +| dependency. Shutting | | import lxml | | +| down server. | | | | ++------------------------------+----------+---------------------+--------------+ +| You need to specify base64 | Server | The server cannot | [s10]_ | +| encoding for <path> | | send the file as | | +| | | ascii text | | ++------------------------------+----------+---------------------+--------------+ +| ERROR: Error reading file | Server | The server cannot | [s11]_ | +| '/path/to/schema': failed to | | find the schema | | +| load external entity | | file | | +| "/path/to/schema" | | | | ++------------------------------+----------+---------------------+--------------+ -.. [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 -.. [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`` -.. [4] This entry is not being bound. Ensure that a version of this - entry applies to this client. -.. [5] Ensure that another instance of the daemon (or any other process) - is not listening on the same port. -.. [6] Ensure that the key is readable by the user running the daemon - and that it is well-formed. -.. [7] Ensure that this file still exists; a frequent cause is the - deletion of a temp file. -.. [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] +.. [s1] This entry is not being bound. Ensure that a version of this + entry applies to this client. +.. [s2] Ensure that another instance of the daemon (or any other process) + is not listening on the same port. +.. [s3] Ensure that the key is readable by the user running the daemon + and that it is well-formed. +.. [s4] Ensure that this file still exists; a frequent cause is the + deletion of a temp file. +.. [s5] Ensure that the file is properly formed XML. +.. [s6] Fix hostname resolution for the client or ensure that the profile + group is properly setup. +.. [s7] Ensure the correct encoding is specified in the [components] section of ``bcfg2.conf``. +.. [s8] For packages listed other than **gpg-pubkey**, this error means + that the Packages plugin is unable to find the package in any of + the sources listed in ``Packages/config.xml``. The issue often + 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). +.. [s9] Ensure that you have installed all the necessary + :ref:`installation-prerequisites`. +.. [s10] You likely need to specify a base64 encoding using an + :ref:`server-info` file for this entry. +.. [s11] Verify that you have the proper prefix set in bcfg2.conf. FAQs ==== 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/reports/dynamic.txt b/doc/reports/dynamic.txt index 6e0ea8050..4c75cce32 100644 --- a/doc/reports/dynamic.txt +++ b/doc/reports/dynamic.txt @@ -188,29 +188,38 @@ displays:: Usage: python bcfg2-reports [option] ... Options and arguments (and corresponding environment variables): - -a : shows all hosts, including expired hosts - -b NAME : single-host mode - shows bad entries from the - current interaction of NAME - -c : shows only clean hosts - -d : shows only dirty hosts - -e NAME : single-host mode - shows extra entries from the - current interaction of NAME - -h : shows help and usage info about bcfg2-reports - -s NAME : single-host mode - shows bad and extra entries from - the current interaction of NAME - -x NAME : toggles expired/unexpired state of NAME - --badentry=KIND,NAME : shows only hosts whose current interaction has bad - entries in of KIND kind and NAME name; if a single - argument ARG1 is given, then KIND,NAME pairs will be - read from a file of name ARG1 - --extraentry=KIND,NAME : shows only hosts whose current interaction has extra - entries in of KIND kind and NAME name; if a single - argument ARG1 is given, then KIND,NAME pairs will be - read from a file of name ARG1 - --fields=ARG1,ARG2,... : only displays the fields ARG1,ARG2,... - (name,time,state) - --sort=ARG1,ARG2,... : sorts output on ARG1,ARG2,... (name,time,state) - --stale : shows hosts which haven't run in the last 24 hours + -a : shows all hosts, including expired hosts + -b NAME : single-host mode - shows bad entries from the + current interaction of NAME + -c : shows only clean hosts + -d : shows only dirty hosts + -e NAME : single-host mode - shows extra entries from the + current interaction of NAME + -h : shows help and usage info about bcfg2-reports + -m NAME : single-host mode - shows modified entries from the + current interaction of NAME + -s NAME : single-host mode - shows bad, modified, and extra + entries from the current interaction of NAME + -t NAME : single-host mode - shows total number of managed and + good entries from the current interaction of NAME + -x NAME : toggles expired/unexpired state of NAME + --badentry=KIND,NAME : shows only hosts whose current interaction has bad + entries in of KIND kind and NAME name; if a single + argument ARG1 is given, then KIND,NAME pairs will be + read from a file of name ARG1 + --modifiedentry=KIND,NAME : shows only hosts whose current interaction has + modified entries in of KIND kind and NAME name; if a + single argument ARG1 is given, then KIND,NAME pairs + will be read from a file of name ARG1 + --extraentry=KIND,NAME : shows only hosts whose current interaction has extra + entries in of KIND kind and NAME name; if a single + argument ARG1 is given, then KIND,NAME pairs will be + read from a file of name ARG1 + --fields=ARG1,ARG2,... : only displays the fields ARG1,ARG2,... + (name,time,state,total,good,bad) + --sort=ARG1,ARG2,... : sorts output on ARG1,ARG2,... + (name,time,state,total,good,bad) + --stale : shows hosts which haven't run in the last 24 hours Screenshots =========== diff --git a/doc/server/configurationentries.txt b/doc/server/configurationentries.txt index 6e6ab79f7..10eccf6be 100644 --- a/doc/server/configurationentries.txt +++ b/doc/server/configurationentries.txt @@ -31,9 +31,25 @@ Non-POSIX entries +-------------+---------------------+-----------------------------+ | PostInstall | PostInstall command | name | +-------------+---------------------+-----------------------------+ -| Service | System Services | name, type, status, reload | +| Service | System Services | name, type, status, target | +-------------+---------------------+-----------------------------+ +.. note:: + + PostInstall entries are deprecated in favor of Action entries. In + fact, a PostInstall entry is simply a specific type of Action. + Basically, the following are equivalent: + + .. code-block:: xml + + <PostInstall name='foo'/> + + and + + .. code-block:: xml + + <Action timing='post' when='modified' name='n' command='foo' status='ignore'/> + POSIX entries ============= @@ -48,11 +64,11 @@ will only contain a *name* attribute. The type will be added by the plugin that handles the entry in the case of `Cfg`_, `TGenshi`_, or `TCheetah`_. If the entry is handled by the `Rules`_ plugin (i.e. it is a device, directory, hardlink, symlink, etc), then you will specify both -the *type* and any other necessary attributes in `Rules`_. +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 +111,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 612b14bec..1039ff556 100644 --- a/doc/server/plugins/generators/cfg.txt +++ b/doc/server/plugins/generators/cfg.txt @@ -132,16 +132,16 @@ server and we have the following configuration files:: motd.G01_web-server motd.G01_mail-server.cat motd.G02_file-server.cat - motd.H_foo.example.cat + motd.H_foo.example.com.cat -If our machine isn't *foo.example.com* then here's what would happen: +If our machine **isn't** *foo.example.com* then here's what would happen: Bcfg2 would choose ``motd.G01_web-server`` as the base file. It is the most specific base file for this host. Bcfg2 would apply the ``motd.G01_mail-server.cat`` delta to the ``motd.G01_web-server`` base file. It is the least specific delta. Bcfg2 would then apply the ``motd.G02_file-server.cat`` delta to the result of the delta before -it. If our machine is foo.example.com then here's what would happen: +it. If our machine **is** *foo.example.com* then here's what would happen: Bcfg2 would choose ``motd.G01_web-server`` as the base file. It is the most specific base file for this host. Bcfg2 would apply the diff --git a/doc/server/plugins/generators/decisions.txt b/doc/server/plugins/generators/decisions.txt index ba01f7fc2..d75a9fede 100644 --- a/doc/server/plugins/generators/decisions.txt +++ b/doc/server/plugins/generators/decisions.txt @@ -22,6 +22,12 @@ should be corrected during the current run of the installation tool. The Decisions plugin is the only stock plugin that generates entries for client's whitelists or blacklists. +.. note:: + + If the client is not explicitly configured to run in whitelist or + blacklist mode, the list of entries is not downloaded and decisions + is not used. See `Decision Mode`_ below. + The Decisions plugin uses a directory in the Bcfg2 repository called Decisions. Files in the Decisions subdirectory are named similarly to files managed by Cfg, probes, TCheetah, and TGenshi (so you can use host- @@ -37,12 +43,6 @@ the following is an example. <Decision type='Path' name='/etc/apt/apt.conf'/> </Decisions> -.. note:: To add syntax highlighting in vim, you can add a modeline such as this: - - <!-- - vim: ft=xml - --> - This example, included as a whitelist due to its name, enables all services, and the path entry named ``/etc/apt/apt.conf``. All these entries must already be present in your repository, the Decisions plugin just references @@ -55,11 +55,27 @@ When a client asks for its whitelist or blacklist, all of the files pertaining to that client of the correct type are aggregated into a single list. This list is sent to the client. -.. note:: This list is only generated when a client is explicitly run with - the appropriate option (``-l (whitelist|blacklist)``); client - behavior is not controlled unless this option is used. If you do - not use Decisions, all your entries will be installed normally. -.. note:: Also, using this plugin does not present additional prompts or +.. note:: Using this plugin does not present additional prompts or safety nets to the administrator running the client, you have to control these via their respective options (``-I`` or ``-n``, for example). + +To add syntax highlighting to Decisions files in vim and emacs, you +can add comments such as this:: + + <Decisions><!--*- mode: xml; -*--> + <!-- vim: set ft=xml : --> + + +============= +Decision Mode +============= + +The whitelist or blacklist is only generated when a client is run in +whitelist or blacklist mode. This can either be set at the command +line with the appropriate option (``-l (whitelist|blacklist)``), or in +``bcfg2.conf`` by setting ``decision`` in the ``client`` section to +``whitelist`` or ``blacklist``). + +Client behavior is not controlled unless the decision mode is set. If +you do not use Decisions, all your entries will be installed normally. 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..d7e0b3bf2 100644 --- a/doc/server/plugins/generators/tgenshi/index.txt +++ b/doc/server/plugins/generators/tgenshi/index.txt @@ -48,10 +48,16 @@ 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 +* **path** is the path to the TGenshi template. It starts with a + leading slash, and is relative to the Bcfg2 specification root. + E.g., ``/Cfg/etc/foo.conf/foo.conf.genshi`` or + ``/TGenshi/etc/foo.conf/template.newtxt.H_foo.example.com`` See the genshi `documentation <http://genshi.edgewall.org/wiki/Documentation>`_ for examples of @@ -88,6 +94,56 @@ Produces: This flexibility provides the ability to build much more compact and succinct definitions of configuration contents than Cfg can. +Troubleshooting +=============== + +When developing a template, you can see what the template would +generate on a client with :ref:`bcfg2-info <server-bcfg2-info>`:: + + bcfg2-info buildfile <path> <hostname> + +E.g.:: + + bcfg2-info buildfile /etc/foo.conf foo.example.com + +Sometimes, it's useful to be able to do more in-depth troubleshooting +by running the template manually. (This is also necessary if you want +to generate a template that depends on an :ref:`altsrc +<server-plugins-structures-altsrc>` tag.) To do this, run ``bcfg2-info +debug``, and, once in the Python interpreter, run:: + + metadata = self.build_metadata("<hostname>") + path = "<relative path to template (see note below)>" + bcfg2root = "<path to bcfg2 specification root>" + +``path`` should be set to the path to the template file with a leading +slash, relative to the Bcfg2 specification root. See `Inside of +Templates`_ for examples. + +``bcfg2root`` should be set to the absolute path to the Bcfg2 +specification. (This is ``/var/lib/bcfg2`` by default.) + +Then, run:: + + import os + name = os.path.dirname(path[path.find('/', 1):]) + from genshi.template import TemplateLoader, NewTextTemplate + template = TemplateLoader().load(bcfg2root + path, cls=NewTextTemplate) + print template.generate(metadata=metadata, path=path, name=name).render() + +This gives you more fine-grained control over how your template is +rendered. + +You can also use this approach to render templates that depend on +:ref:`altsrc <server-plugins-structures-altsrc>` tags by setting +``path`` to the path to the template, and setting ``name`` to the path +to the file to be generated, e.g.:: + + metadata = self.build_metadata("foo.example.com") + path = "/Cfg/etc/sysconfig/network-scripts/ifcfg-template/ifcfg-template.genshi" + bcfg2root = "/var/lib/bcfg2" + name = "/etc/sysconfig/network-scripts/ifcfg-bond0" + File permissions ================ @@ -98,10 +154,10 @@ Permissions entry and a Path entry to handle the same file. Error handling ================ -Situations may arrise where a templated file cannot be generated due to +Situations may arise where a templated file cannot be generated due to missing or incomplete information. A TemplateError can be raised to -force a bind failure and prevent sending an incomplete file to the client. -For example, this template:: +force a bind failure and prevent sending an incomplete file to the +client. For example, this template:: {% python from genshi.template import TemplateError 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/probes/index.txt b/doc/server/plugins/probes/index.txt index 33ec6f444..b9f698a0f 100644 --- a/doc/server/plugins/probes/index.txt +++ b/doc/server/plugins/probes/index.txt @@ -143,3 +143,60 @@ Other examples :hidden: ohai + +.. _server-plugins-probes-fileprobes: + +FileProbes +========== + +The FileProbes plugin allows you to probe a client for a file, +which is then added to the :ref:`server-plugins-generators-cfg` +specification. If the file changes on the client, FileProbes can +either update it in the specification or allow Cfg to replace it. + +FileProbes will not probe a file if there's already a file in Cfg that +will apply to the client. So if, for instance, you have a generic +file in ``Cfg/etc/foo.conf/foo.conf`` that applies to all hosts, +FileProbes will not retrieve ``/etc/foo.conf`` from the client (unless +``update`` is enabled; see Configuration_ below). + +When a new config file is first probed, an ``info.xml`` file is also +written to enforce the permissions from that client. Subsequent +probes from other clients will not modify or overwrite the data in +``info.xml``. (This ensures that any manual changes you make to +``info.xml`` for that file are not circumvented.) + +Configuration +------------- + +FileProbes is configured in ``FileProbes/config.xml``, which might +look something like: + +.. code-block:: xml + + <FileProbes> + <FileProbe name="/etc/foo.conf"/> + <Group name="blah-servers"> + <FileProbe name="/etc/blah.conf" update="true" + </Group> + <Client name="bar.example.com"> + <FileProbe name="/var/lib/bar.gz" base64="true"/> + </Client> + </FileProbes> + +This will result in ``/etc/foo.conf`` being retrieved from all +clients; if it changes on a client, it will be overwritten by the +version that was retrieved initially. + +Clients in the ``blah-servers`` group will be probed for +``/etc/blah.conf``; if it changes on a client, those changes will be +written into the Bcfg2 specification. If the file is deleted from a +client, it will be rewritten from Bcfg2. + +``bar.example.com`` will be probed for ``/var/lib/bar.gz``, which +contains non-ASCII characters and so needs to use base64 encoding when +transferring the file. + +The paths probed by FileProbes must also be included as Path entries +in your bundles in order to be handled properly by Cfg. Permissions +are handled as usual, with ``info.xml`` files in Cfg. diff --git a/doc/server/plugins/structures/base.txt b/doc/server/plugins/structures/base.txt index 66d8062e1..03eae0573 100644 --- a/doc/server/plugins/structures/base.txt +++ b/doc/server/plugins/structures/base.txt @@ -6,6 +6,13 @@ Base ==== +.. deprecated:: 1.2.0 + +.. warning:: + + The Base plugin no longer receives new features/functionality. + Please use :ref:`server-plugins-structures-bundler-index` instead. + The Base plugin is a structure plugin that provides the ability to add lists of unrelated entries into client configuration entry inventories. diff --git a/doc/server/plugins/structures/bundler/index.txt b/doc/server/plugins/structures/bundler/index.txt index 0d0054a2c..6b5c246aa 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 ================ @@ -148,6 +156,23 @@ format is XML. A Genshi template looks much like a Bundler file, except the Bundle tag has an additional `xmlns:py` attribute. See the examples. +Troubleshooting +--------------- + +There is no :ref:`bcfg2-info <server-bcfg2-info>` command like +``buildfile`` for Bundler templates, so if you want to generate a +Bundler template for a given client, you have to do so manually by +first invoking ``bcfg2-info debug``, then run:: + + metadata = self.build_metadata("<hostname>") + path = "<full path to template file>" + from genshi.template import TemplateLoader, MarkupTemplate + template = TemplateLoader().load(path, cls=MarkupTemplate) + print template.generate(metadata=metadata).render('xml') + +``path`` needs to be the full path to the template file on the +filesystem, not just within the Bcfg2 repo. + Altsrc ====== @@ -220,6 +245,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). |