diff options
Diffstat (limited to 'doc/server/plugins')
37 files changed, 769 insertions, 1688 deletions
diff --git a/doc/server/plugins/connectors/properties.txt b/doc/server/plugins/connectors/properties.txt index 47e82fdbf..a6f6af741 100644 --- a/doc/server/plugins/connectors/properties.txt +++ b/doc/server/plugins/connectors/properties.txt @@ -120,6 +120,8 @@ in ``bcfg2.conf``:: [properties] writes_enabled = false +.. _server-plugins-connectors-properties-xml: + XML Property Files ------------------ @@ -266,47 +268,13 @@ Encrypted Properties data .. versionadded:: 1.3.0 You can encrypt selected data in XML Properties files to protect that -data from other people who need access to the repository. See -:ref:`server-encryption-configuration` for details on configuring -encryption passphrases. The data is decrypted transparently -on-the-fly by the server; you never need to decrypt the data in your -templates. Encryption is only supported on XML properties files. - -.. note:: - - This feature is *not* intended to secure the files against a - malicious attacker who has gained access to your Bcfg2 server, as - the encryption passphrases are held in plaintext in - ``bcfg2.conf``. This is only intended to make it easier to use a - single Bcfg2 repository with multiple admins who should not - necessarily have access to each other's sensitive data. - -Properties files are encrypted on a per-element basis; that is, rather -than encrypting the whole file, only the character content of -individual elements is encrypted. This makes it easier to track -changes to the file in a VCS, and also lets unprivileged users work -with the other data in the file. Only character content of an element -can be encrypted; attribute content and XML elements themselves cannot -be encrypted. - -By default, decryption is *strict*; that is, if any element cannot be -decrypted, parsing of the file is aborted. If you wish for parsing to -continue, with unencryptable elements simply skipped, then you can set -decryption to *lax* in one of two ways: - -* Set ``decrypt=lax`` in the ``[encryption]`` section of - ``bcfg2.conf`` to set lax decryption on all files by default; or -* Set the ``decrypt="lax"`` attribute on the top-level ``Properties`` - tag of a Properties file to set lax decryption for a single file. - -Note that you could, for instance, set lax decryption by default, and -then set strict decryption on individual files. - -To encrypt or decrypt a file, use :ref:`bcfg2-crypt`. - -See :ref:`server-encryption` for more details on encryption in Bcfg2 -in general. +data from other people who need access to the repository. The +data is decrypted transparently on-the-fly by the server; you never +need to decrypt the data in your templates. Encryption is only +supported on XML properties files. +See :ref:`server-encryption` for details on encryption in general, and +:ref:`xml-encryption` for details on encryption in XML files. Accessing Properties contents from Genshi Templates =================================================== diff --git a/doc/server/plugins/connectors/templatehelper.txt b/doc/server/plugins/connectors/templatehelper.txt index 374aeb171..c719f93cb 100644 --- a/doc/server/plugins/connectors/templatehelper.txt +++ b/doc/server/plugins/connectors/templatehelper.txt @@ -31,7 +31,7 @@ helpers will be available to all clients. Writing Helpers =============== -A helper module is just a Python module with three special conditions: +A helper module is just a Python module with several special conditions: * The filename must end with ``.py`` * The module must have an attribute, ``__export__``, that lists all of @@ -43,6 +43,12 @@ A helper module is just a Python module with three special conditions: an underscore or double underscore is bad form, and may also produce errors. +Additionally, the module *may* have an attribute, ``__default__``, +that lists all of the symbols that you wish to include by default in +the template namespace. ``name``, ``metadata``, ``source_path``, +``repo``, and ``path`` are reserved names, and should not be included +in ``__default__``. + See ``examples/TemplateHelper`` for examples of helper modules. Usage @@ -54,17 +60,23 @@ a HelperModule object will has, as attributes, all symbols listed in ``__export__``. For example, consider this helper module:: __export__ = ["hello"] - + __default__ = ["pining"] + def hello(metadata): return "Hello, %s!" % metadata.hostname + def pining(text): + return "It's pinin' for the %s!" % text + To use this in a Genshi template, we could do:: ${metadata.TemplateHelper['hello'].hello(metadata)} + ${pining("fjords")} The template would produce:: Hello, foo.example.com! + It's pinin' for the fjords! Note that the client metadata object is not passed to a helper module in any magical way; if you want to access the client metadata object diff --git a/doc/server/plugins/generators/account.txt b/doc/server/plugins/generators/account.txt deleted file mode 100644 index 99c35c814..000000000 --- a/doc/server/plugins/generators/account.txt +++ /dev/null @@ -1,115 +0,0 @@ -.. -*- mode: rst -*- - -.. _server-plugins-generators-account: - -======= -Account -======= - -The account plugin manages authentication data, including - -* ``/etc/passwd`` -* ``/etc/group`` -* ``/etc/security/limits.conf`` -* ``/etc/sudoers`` -* ``/root/.ssh/authorized_keys`` - -User access data is stored in three files in the Account directory: - -* superusers (a list of users who always have root privs) -* rootlist (a list of user:host pairs for scoped root privs) -* useraccess (a list of user:host pairs for login access) - -SSH keys are stored in files named $username.key; these are installed -into root's authorized keys for users in the superusers list as well as -for the pertitent users in the rootlike file (for the current system). - -Authentication data is read in from (static|dyn).(passwd|group) The static -ones are for system local ones, while the dyn. versions are for external -synchronization (from ldap/nis/etc). There is also a static.limits.conf -that provides the limits.conf header and any static entries. - -Files in the Account directory: - -``<username>.key`` - - **Format**: The SSH public key for user <username>. - - If the user is in the "rootlike" or "superusers" group, these - keys will be appended to ``/root/.ssh/auth`` - -``useraccess`` - - **Format**: "user:hostname" on each line. - - Describes who may login where (via PAMs - ``/etc/security/limits.conf``). Everybody else will be denied - access.(?) - - **Example**: - - If Alice should be able to access host "foo", Bob should access - "foo" and "bar":: - - alice:foo.example.com - bob:foo.example.com - bob:bar.example.com - -``rootlike`` - - **Format**: "user:hostname" on each line. - - Describes who will be allowed root access where. The user may - login via public key and use sudo. - - **Example**: - - If Chris should be root only on host "foo":: - - chris:foo.example.com - -``superusers`` - - **Format**: usernames, separated by spaces or newlines. (Any whitespace that makes pythons split() happy.) - - Describes who will be allowed root access on all hosts. The user - may login via public key and use sudo. - - **Example**: - - Daniel, Eve and Faith are global admins:: - - daniel eve - faith - -``static.passwd``, ``static.group`` - - **Format**: Lines from ``/etc/passwd`` or ``/etc/group`` - - These entries are appended to the passwd and group files - (in addition to the auto-generated entries from "useraccess", - "rootlike" and "superusers" above) without doing anything else. - -``dyn.passwd``, ``dyn.group`` - - **Format**: Lines from ``/etc/passwd`` or ``/etc/group`` - - Similar to "static.*" above, but for entries that are managed "on - the network" (yp, LDAP, ...), so it is most likely periodically - (re)filled. - -``static.limits.conf`` - - **Format**: Lines from ``/etc/security/limit.conf`` - - These limits will be appended to limits.conf (in addition to - the auto-generated entries from "useraccess", "rootlike" and - "superusers" above). - -``static.sudoers`` - - **Format**: Lines from ``/etc/sudoers`` - - These lines will be appended to to sudoers file (in addition - to the auto-generated entries from "useraccess", "rootlike" and - "superusers" above). diff --git a/doc/server/plugins/generators/cfg.txt b/doc/server/plugins/generators/cfg.txt index 0f0601105..7a404c824 100644 --- a/doc/server/plugins/generators/cfg.txt +++ b/doc/server/plugins/generators/cfg.txt @@ -102,9 +102,8 @@ Genshi Templates ---------------- Genshi templates allow you to use the `Genshi -<http://genshi.edgewall.org>`_ templating system. This is similar to -the deprecated :ref:`server-plugins-generators-tgenshi-index` plugin. -Genshi templates should be named with a ``.genshi`` extension, e.g.:: +<http://genshi.edgewall.org>`_ templating system. Genshi templates +should be named with a ``.genshi`` extension, e.g.:: % ls Cfg/etc/motd info.xml motd.genshi @@ -214,9 +213,8 @@ Cheetah Templates ----------------- Cheetah templates allow you to use the `cheetah templating system -<http://www.cheetahtemplate.org/>`_. This is similar to -the deprecated :ref:`server-plugins-generators-tcheetah` plugin. -Cheetah templates should be named with a ``.cheetah`` extension, e.g.:: +<http://www.cheetahtemplate.org/>`_. Cheetah templates should be +named with a ``.cheetah`` extension, e.g.:: % ls Cfg/etc/motd info.xml motd.cheetah @@ -415,7 +413,7 @@ See :ref:`server-encryption` for more details on encryption in Bcfg2 in general. ``pubkey.xml`` -~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~ ``pubkey.xml`` only ever contains a single line: @@ -563,110 +561,162 @@ Example Hopefully, the performance concerns can be resolved in a future release and these features can be added. +.. _server-plugins-generators-cfg-ssl-certificates: + +SSL Keys and Certificates +========================= + +Cfg can also create SSL keys and certs on the fly, and store the +generated data in the repo so that subsequent requests do not result +in repeated key/cert recreation. In the event that a new key or cert +is needed, the old file can simply be removed from the +repository, and the next time that host checks in, a new file will be +created. If that file happens to be the key, any dependent +certificates will also be regenerated. + +See also :ref:`appendix-guides-sslca_howto` for a detailed example +that uses the SSL key management feature to automate Bcfg2 certificate +authentication. + +Getting started +--------------- + +In order to use the SSL certificate generation feature, you must first +have at least one CA configured on your system. For details on +setting up your own OpenSSL based CA, please see +http://www.openssl.org/docs/apps/ca.html for details of the suggested +directory layout and configuration directives. + +For SSL cert generation to work, the openssl.cnf (or other +configuration file) for that CA must contain full (not relative) +paths. + +#. 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. (If you only have one CA, + you can name it ``sslca_default``, and it will be the default CA + for all other operations.) + +#. Under that section, add a ``config`` option that gives the location + of the ``openssl.cnf`` file for your CA. + +#. If necessary, add a ``passphrase`` option containing the passphrase + for the CA's private key. If no passphrase is entry exists, it is + assumed that the private key is stored unencrypted. + +#. Optionally, add a ``chaincert`` option that points to the location + of your ssl chaining certificate. This is used when preexisting + certificate hostfiles are found, so that they can be validated and + only regenerated if they no longer meet the specification. If + you're using a self signing CA this would be the CA cert that you + generated. If the chain cert is a root CA cert (e.g., if it is a + self-signing CA), also add an entry ``root_ca = true``. If + ``chaincert`` is omitted, certificate verification will not be + performed. + +#. Once all this is done, you should have a section in your + ``/etc/bcfg2.conf`` that looks similar to the following:: + + [sslca_default] + config = /etc/pki/CA/openssl.cnf + passphrase = youReallyThinkIdShareThis? + chaincert = /etc/pki/CA/chaincert.crt + root_ca = true + +#. 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. + +#. Within the ``Cfg/etc/pki/tls/private/localhost.key`` directory, + create a `sslkey.xml`_ file containing the following: + + .. code-block:: xml + + <KeyInfo/> + +#. This will cause the generation of an SSL key when a client requests + that Path. (By default, it will be a 2048-bit RSA key; see + `sslkey.xml`_ for details on how to change the key type and size.) + +#. Similarly, create `sslcert.xml`_ in + ``Cfg/etc/pki/tls/certs/localhost.cfg/``, containing the following: + + .. code-block:: xml + + <CertInfo> + <Cert key="/etc/pki/tls/private/localhost.key" ca="foo"/> + </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="foo"`` will + match ``[sslca_default]`` in your ``/etc/bcfg2.conf`` + +The :ref:`Bcfg2 bundle example +<server-plugins-structures-bundler-bcfg2-server>` contains entries to +automate the process of setting up a CA. + Configuration ------------- -In addition to ``privkey.xml`` and ``authorized_keys.xml``, described -above, the behavior of the SSH key generation feature can be -influenced by several options in the ``[sshkeys]`` section of -``bcfg2.conf``: +``bcfg2.conf`` +~~~~~~~~~~~~~~ -+----------------+---------------------------------------------------------+-----------------------+------------+ -| Option | Description | Values | Default | -+================+=========================================================+=======================+============+ -| ``passphrase`` | Use the named passphrase to encrypt private keys on the | String | None | -| | filesystem. The passphrase must be defined in the | | | -| | ``[encryption]`` section. See :ref:`server-encryption` | | | -| | for more details on encryption in Bcfg2 in general. | | | -+----------------+---------------------------------------------------------+-----------------------+------------+ -| ``category`` | Generate keys specific to groups in the given category. | String | None | -| | It is best to pick a category that all clients have a | | | -| | group from. | | | -+----------------+---------------------------------------------------------+-----------------------+------------+ - -Deltas -====== +In ``bcfg2.conf``, you must declare your CA(s) in ``[sslca_<name>]`` +sections. At least one is required. Valid options are detailed +below, in `Cfg Configuration`_. -.. note:: +Only the ``config`` option is required; i.e., the simplest possible CA +section is:: + + [sslca_default] + config = /etc/pki/CA/openssl.cnf + +``sslcert.xml`` +~~~~~~~~~~~~~~~ + +.. xml:schema:: sslca-cert.xsd + :linktotype: + :inlinetypes: CertType + +Example +^^^^^^^ + +.. code-block:: xml + + <CertInfo> + <subjectAltName>test.example.com</subjectAltName> + <Group name="apache"> + <Cert key="/etc/pki/tls/private/foo.key" days="730"/> + </Group> + <Group name="nginx"> + <Cert key="/etc/pki/tls/private/foo.key" days="730" + append_chain="true"/> + </Group> + </CertInfo> + +``sslkey.xml`` +~~~~~~~~~~~~~~ + +.. xml:schema:: sslca-key.xsd + :linktotype: + :inlinetypes: KeyType + +Example +^^^^^^^ + +.. code-block:: xml + + <KeyInfo> + <Group name="fast"> + <Key type="rsa" bits="1024"/> + </Group> + <Group name="secure"> + <Key type="rsa" bits="4096"/> + </Group> + </KeyInfo> - In Bcfg2 1.3 and newer, deltas are deprecated. It is recommended - that you use templates instead. The - :ref:`TemplateHelper plugin - <server-plugins-connectors-templatehelper>` comes with an example - helper that can be used to include other files easily, a subset of - cat file functionality. ``bcfg2-lint`` checks for deltas and - warns about them. - -.. warning:: - - In Bcfg2 1.3, deltas **do not** work with `SSH key or - authorized_keys generation <SSH Keys>`_. - -Bcfg2 has finer grained control over how to deliver configuration -files to a host. Let's say we have a Group named file-server. Members -of this group need the exact same ``/etc/motd`` as all other hosts except -they need one line added. We could copy motd to ``motd.G01_file-server``, -add the one line to the Group specific version and be done with it, -but we're duplicating data in both files. What happens if we need to -update the motd? We'll need to remember to update both files then. Here's -where deltas come in. A delta is a small change to the base file. There -are two types of deltas: cats and diffs. The cat delta simply adds or -removes lines from the base file. The diff delta is more powerful since -it can take a unified diff and apply it to the base configuration file -to create the specialized file. Diff deltas should be used very sparingly. - -Cat Files ---------- - -Continuing our example for cat files, we would first create a file named -``motd.G01_file-server.cat``. The .cat suffix designates that the file is -a diff. We would then edit that file and add the following line:: - - +This is a file server - -The **+** at the begining of the file tells Bcfg2 that the line should be -appended to end of the file. You can also start a line with **-** to tell -Bcfg2 to remove that exact line wherever it might be in the file. How do -we know what base file Bcfg2 will choose to use to apply a delta? The -same rules apply as before: Bcfg2 will choose the highest priority, -most specific file as the base and then apply deltas in the order of -most specific and then increasing in priority. What does this mean in -real life. Let's say our machine is a web server, mail server, and file -server and we have the following configuration files:: - - motd - motd.G01_web-server - motd.G01_mail-server.cat - motd.G02_file-server.cat - motd.H_bar.example.com - motd.H_foo.example.com.cat - -If our machine isn't *foo.example.com* or *bar.example.com*, but -is a web server, then 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* and a web server, then 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.H_foo.example.com.cat`` delta to the ``motd.G01_web-server`` -base file. The reason the other deltas aren't applied to -*foo.example.com* is because a **.H_** delta is more specific than a -**.G##_** delta. Bcfg2 applies all the deltas at the most specific -level. - -If our machine is *bar.example.com*, then Bcfg2 would chose -``motd.H_foo.example.com`` as the base file because it is the most -specific base file for this host. Regardless of the groups -*bar.example.com* is a member of, **no cat files** would be applied, -because only cat files as specific or more specific than the base file -are applied. (In other words, if a group-specific base file is -selected, only group- or host-specific cat files can be applied; if a -host-specific base file is selected, only host-specific cat files can -be applied.) .. _server-plugins-generators-cfg-validation: @@ -721,3 +771,56 @@ File permissions File permissions for entries handled by Cfg are controlled via the use of :ref:`server-info` files. Note that you **cannot** use both a Permissions entry and a Path entry to handle the same file. + +.. _server-plugins-generators-cfg-configuration: + +Cfg Configuration +================= + +The behavior of many bits of the Cfg plugin can be configured in +``bcfg2.conf`` with the following options. + +In addition to ``privkey.xml`` and ``authorized_keys.xml``, described +above, the behavior of the SSH key generation feature can be +influenced by several options in the ``[sshkeys]`` section of +``bcfg2.conf``: + ++-------------+----------------+---------------------------------------------------------+-----------------------+------------+ +| Section | Option | Description | Values | Default | ++=============+================+=========================================================+=======================+============+ +| ``cfg`` | ``passphrase`` | Use the named passphrase to encrypt created data on the | String | None | +| | | filesystem. (E.g., SSH and SSL keys.) The passphrase | | | +| | | must be defined in the ``[encryption]`` section. | | | ++-------------+----------------+---------------------------------------------------------+-----------------------+------------+ +| ``cfg`` | ``category`` | Generate data (e.g., SSH keys, SSL keys and certs) | String | None | +| | | specific to groups in the given category. It is best to | | | +| | | pick a category that all clients have a group from. | | | ++-------------+----------------+---------------------------------------------------------+-----------------------+------------+ +| ``cfg`` | ``validation`` | Whether or not to perform `Content Validation`_ | Boolean | True | +| | | specific to groups in the given category. It is best to | | | +| | | pick a category that all clients have a group from. | | | ++-------------+----------------+---------------------------------------------------------+-----------------------+------------+ +| ``sshkeys`` | ``passphrase`` | Override the global Cfg passphrase with a specific | String | None | +| | | passphrase for encrypting created SSH private keys. | | | ++-------------+----------------+---------------------------------------------------------+-----------------------+------------+ +| ``sshkeys`` | ``category`` | Override the global Cfg category with a specific | String | None | +| | | category for created SSH keys. | | | ++-------------+----------------+---------------------------------------------------------+-----------------------+------------+ +| ``sslca`` | ``passphrase`` | Override the global Cfg passphrase with a specific | String | None | +| | | passphrase for encrypting created SSL keys. | | | ++-------------+----------------+---------------------------------------------------------+-----------------------+------------+ +| ``sslca`` | ``category`` | Override the global Cfg category with a specific | String | None | +| | | category for created SSL keys and certs. | | | ++-------------+----------------+---------------------------------------------------------+-----------------------+------------+ +| ``sslca_*`` | ``config`` | Path to the openssl config for the CA | String | None | ++-------------+----------------+---------------------------------------------------------+-----------------------+------------+ +| ``sslca_*`` | ``passphrase`` | Passphrase for the CA private key | String | None | ++-------------+----------------+---------------------------------------------------------+-----------------------+------------+ +| ``sslca_*`` | ``chaincert`` | Path to the SSL chaining certificate for verification | String | None | ++-------------+----------------+---------------------------------------------------------+-----------------------+------------+ +| ``sslca_*`` | ``root_ca`` | Whether or not ``<chaincert>`` is a root CA (as | Boolean | False | +| | | opposed to an intermediate cert) | | | ++-------------+----------------+---------------------------------------------------------+-----------------------+------------+ + +See :ref:`server-encryption` for more details on encryption in Bcfg2 +in general. diff --git a/doc/server/plugins/generators/decisions.txt b/doc/server/plugins/generators/decisions.txt index 9a40ab8fd..f0afeba0a 100644 --- a/doc/server/plugins/generators/decisions.txt +++ b/doc/server/plugins/generators/decisions.txt @@ -29,18 +29,23 @@ client's whitelists or blacklists. 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 and Probes, so you can use host- and -group-specific files and the like after their basename. File basenames -are either ``whitelist`` or ``blacklist``. These files have a simple -format; the following is an example. +Decisions, which may contain two files: ``whitelist.xml`` and +``blacklist.xml``. These files have a simple format: + +.. xml:type:: DecisionsType + :linktotype: + :noautodep: py:genshiElements + +For example: .. code-block:: xml - $ cat Decisions/whitelist + $ cat Decisions/whitelist.xml <Decisions> <Decision type='Service' name='*'/> - <Decision type='Path' name='/etc/apt/apt.conf'/> + <Group name="debian"> + <Decision type='Path' name='/etc/apt/apt.conf'/> + </Group> </Decisions> This example, included as a whitelist due to its name, enables all services, @@ -60,12 +65,6 @@ list. This list is sent to the client. 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 ============= diff --git a/doc/server/plugins/generators/examples/genshi/ganglia.txt b/doc/server/plugins/generators/examples/genshi/ganglia.txt index 3a20fde92..d7030e990 100644 --- a/doc/server/plugins/generators/examples/genshi/ganglia.txt +++ b/doc/server/plugins/generators/examples/genshi/ganglia.txt @@ -33,7 +33,7 @@ Bundler/ganglia.xml .. code-block:: xml - <Bundle name='ganglia'> + <Bundle> <Package name='ganglia-gmond' /> <Package name='ganglia-gmond-modules-python' /> <Path name='/etc/ganglia/gmond.conf' /> diff --git a/doc/server/plugins/generators/hostbase.txt b/doc/server/plugins/generators/hostbase.txt deleted file mode 100644 index c6007f70e..000000000 --- a/doc/server/plugins/generators/hostbase.txt +++ /dev/null @@ -1,228 +0,0 @@ -.. -*- mode: rst -*- - -.. _server-plugins-generators-hostbase: - -======== -Hostbase -======== - -IP management system built on top of Bcfg2. It has four main parts: a -django data model, a web frontend, command-line utilities, and a Bcfg2 -plugin that generates dhcp, dns, and yp configuration files. - -Installation -============ - -Installation of Hostbase requires installation of a python module, -configuration of database (mysql or postgres), and configuration of an -Apache webserver with mod_python. Hostbase was developed using MySQL, -so this document is aimed at MySQL users. - -Prerequisites -------------- - -* `mysql`_ -* `python-mysqldb`_ -* `Django`_ - -.. _Django: http://www.djangoproject.com -.. _python-mysqldb: http://mysql-python.sourceforge.net/MySQLdb.html -.. _mysql: http://www.mysql.com/ - -Configure the database ----------------------- - -Create the hostbase database and a user. For MySQL users:: - - mysql> CREATE DATABASE hostbase - mysql> quit - - systemprompt#: mysql -u root hostbase - mysql> GRANT ALL PRIVILEGES ON *.* TO hostbaseuser@mycomputer.private.net IDENTIFIED - BY 'password' WITH GRANT OPTION; - mysql> quit - -As of Bcfg2 v0.8.7 configuration options for Hostbase have moved to -``/etc/bcfg2.conf``. There is an example bcfg2.conf with Hostbase -options located at ``bcfg2-tarball/examples/bcfg2.confHostbase``. -Edit the hostbase options to correspond to the database you've -initialized and copy the configuration to ``/etc/bcfg2.conf``. To -finish creating the database, from your ``path to -python/Bcfg2/Server/Hostbase`` directory, run ``python manage.py -syncdb`` to do all table creation. - -Configure the web interface ---------------------------- - -Now it's possible to explore the Hostbase web interface. For -curiosity, you can run Django's built-in development server to take a -peek. Do this by running ``python manage.py runserver -[servername:port]`` from your Hostbase directory. Django will -default to ``localhost:8000`` if no server or port is entered. Now -you can explore the web interface. Try adding a host and a zone. -You'll see that a ".rev" zone already exists. This is where -information for reverse files will go. - -For production, you'll want to have this configured for Apache with -mod_python. Here is an example of how to configure Hostbase as a -virtual host. - -.. code-block:: html - - <VirtualHost hostbase.mcs.anl.gov:80> - ServerAdmin systems@mcs.anl.gov - - DocumentRoot /var/www/hostbase/ - <Directory /> - AllowOverride None - </Directory> - - # Possible values include: debug, info, notice, warn, error, crit, - # alert, emerg. - LogLevel warn - - ServerSignature Off - - # Stop TRACE/TRACK vulnerability - <IfModule mod_rewrite.c> - RewriteEngine on - RewriteCond %{REQUEST_METHOD} ^(TRACE|TRACK) - RewriteRule .* - [F] - </IfModule> - - Redirect / https://hostbase.mcs.anl.gov/ - </VirtualHost> - - <VirtualHost hostbase.mcs.anl.gov:443> - ServerAdmin systems@mcs.anl.gov - - DocumentRoot /var/www/hostbase/ - <Directory /> - AllowOverride None - </Directory> - - # Possible values include: debug, info, notice, warn, error, crit, - # alert, emerg. - LogLevel warn - - ServerSignature Off - - # Stop TRACE/TRACK vulnerability - <IfModule mod_rewrite.c> - RewriteEngine on - RewriteCond %{REQUEST_METHOD} ^(TRACE|TRACK) - RewriteRule .* - [F] - </IfModule> - - SSLEngine On - SSLCertificateFile /etc/apache2/ssl/hostbase_server.crt - SSLCertificateKeyfile /etc/apache2/ssl/hostbase_server.key - - <Location "/"> - SetHandler python-program - PythonHandler django.core.handlers.modpython - SetEnv DJANGO_SETTINGS_MODULE Bcfg2.Server.Hostbase.settings - PythonDebug On - </Location> - <Location "/site_media/"> - SetHandler None - </Location> - </VirtualHost> - - -You'll need to copy the contents of ``Hostbase/media`` into -``/var/www/hostbase/site_media`` in this configuration to serve the -correct css files. - -Enable the Hostbase plugin --------------------------- - -Now that the database is accessible and there is some data in it, you can -enable the Hostbase plugin on your Bcfg2 server to start generating some -configuration files. All that needs to be done is to add ``Hostbase`` -to the end of the list of generators in your bcfg2.conf file. To see -what's being generated by Hostbase, fire up a Bcfg2 development server: -``bcfg2-info``. For more information on how to use the Bcfg2 development -server, type help at the prompt. For our purposes, type ``debug``. -This will bring you to an interactive python prompt where you can access -bcfg's core data. - -.. code-block:: python - - for each in bcore.plugins['Hostbase'].filedata: - print each - - -The above loop will print out the name of each file that was generated -by Hostbase. You can see the contents of any of these by typing ``print -bcore.plugins['Hostbase'].filedata[filename]``. - -Create a bundle ---------------- - -Bcfg2 needs a way to distribute the files generated by Hostbase. -We'll do this with a bundle. In bcfg's ``Bundler`` directory, touch -``hostbase.xml``. - -.. code-block:: xml - - <Bundle name='hostbase' version='0.1'> - <Package name='dhcp3-server'/> - <Package name='bind9'/> - <Service name='dhcp3-server'/> - <Service name='bind9'/> - <Path name='/etc/dhcp3/dhcpd.conf'/> - <Path name='/etc/bind/[your domain]'/> - <Path name='/etc/bind/xxx.xxx.xxx.rev'/> - </Bundle> - -The above example is a bundle that will deliver both dhcp and dns files. -This can be trivially split into separate bundles. It is planned that -Hostbase will eventually be able to generate the list of ``Paths`` -in its bundles automatically. - -Do a Hostbase push ------------------- - -You'll want to be able to trigger the Hostbase plugin to rebuild -it's config files and push them out when data has been modified -in the database. This can be done through and XMLRPC function -available from the Bcfg2 server. From a client that is configured -to receive one or more hostbase bundles, you'll need to first -edit your ``python/site-packages/Bcfg2/Client/Proxy.py`` file. -Add ``'Hostbase.rebuildState'`` to the list of methods in the Bcfg2 -client proxy object. The modified list is shown below: - -.. code-block:: python - - class bcfg2(ComponentProxy): - '''bcfg2 client code''' - name = 'bcfg2' - methods = ['AssertProfile', 'GetConfig', 'GetProbes', 'RecvProbeData', 'RecvStats', 'Hostbase.rebuildState'] - -Now copy the file ``hostbasepush.py`` from ``bcfg2/tools`` in the Bcfg2 -source to your machine. When this command is run as root, it triggers -the Hostbase to rebuild it's files, then runs the Bcfg2 client on your -local machine to grab the new configs. - -NIS Authentication -================== - -Django allows for custom authentication backends to its login procedure. -Hostbase has an NIS authentication backend that verifies a user to be -in the unix group allowed to modify Hostbase. - -To enable this feature: - -* first edit your ``Hostbase/settings.py`` file and uncomment - the line **Hostbase.backends.NISBackend** in the list of - *AUTHENTICATION_BACKENDS* -* enter the name of the unix group you want to give access to Hostbase - in the *AUTHORIZED_GROUP* variable -* in your ``Hostbase/hostbase/views.py`` file at the very bottom, - uncomment the block(s) of lines that give you the desired level - of access - -Hostbase will now direct the user to a login page if he or she is not -authorized to view a certain page. Users should log in with their -regular Unix username and password. diff --git a/doc/server/plugins/generators/nagiosgen.txt b/doc/server/plugins/generators/nagiosgen.txt index 0ae922fa3..1ccdd66c1 100644 --- a/doc/server/plugins/generators/nagiosgen.txt +++ b/doc/server/plugins/generators/nagiosgen.txt @@ -12,7 +12,7 @@ This page describes the installation and use of the `NagiosGen`_ plugin. Update ``/etc/bcfg2.conf``, adding NagiosGen to plugins:: - plugins = Base,Bundler,Cfg,...,NagiosGen + plugins = Bundler,Cfg,...,NagiosGen Create the NagiosGen directory:: @@ -124,21 +124,21 @@ Create a nagios Bcfg2 bundle ``/var/lib/bcfg2/Bundler/nagios.xml`` .. code-block:: xml - <Bundle name='nagios' version='2.0'> + <Bundle> <Path name='/etc/nagiosgen.status'/> - <Group name='rh'> + <Group name='redhat'> <Group name='nagios-server'> - <Path name='/etc/nagios/nagiosgen.cfg'/> + <Path name='/etc/nagios/conf.d/bcfg2.cfg'/> <Package name='libtool-libs'/> <Package name='nagios'/> <Package name='nagios-www'/> <Service name='nagios'/> </Group> </Group> - <Group name='debian-lenny'> + <Group name='debian-wheezy'> <Group name='nagios-server'> - <Path name='/etc/nagios3/nagiosgen.cfg' - altsrc='/etc/nagios/nagiosgen.cfg'/> + <Path name='/etc/nagios3/conf.d/bcfg2.cfg' + altsrc='/etc/nagios/conf.d/bcfg2.cfg'/> <Package name='nagios3'/> <Package name='nagios3-common'/> <Package name='nagios3-doc'/> @@ -161,10 +161,6 @@ Assign clients to nagios groups in <Bundle name='nagios'/> </Group> -Update nagios configuration file to use ``nagiosgen.cfg``:: - - cfg_file=/etc/nagios/nagiosgen.cfg - 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 diff --git a/doc/server/plugins/generators/packages.txt b/doc/server/plugins/generators/packages.txt index 31f3ccf22..8b317552f 100644 --- a/doc/server/plugins/generators/packages.txt +++ b/doc/server/plugins/generators/packages.txt @@ -18,14 +18,10 @@ through those channels. Limiting sources to groups ========================== -`sources.xml`_ processes ``<Group>`` and ``<Client>`` tags just like -Bundles. In addition to any groups or clients specified that way, -clients must be a member of the appropriate architecture group as -specified in a Source stanza. In total, in order for a source to be -associated with a client, the client must be in any explicit groups or -clients specified in `sources.xml`_, and any specified architecture -groups. If `"Magic Groups"`_ are enabled, then the client must be a -member of a matching magic group as well. +``Packages/sources.xml`` processes ``<Group>`` and ``<Client>`` tags +just like Bundles. In addition to any groups or clients specified that +way, clients must be a member of the appropriate architecture group as +specified in a Source stanza. Memberships in architecture groups is needed so that Packages can map software sources to clients. There is no other way to handle this than @@ -36,62 +32,6 @@ source to which they apply (based on group memberships, as described above). Packages and dependencies are resolved from all applicable sources. -.. note:: - - To recap, a client needs to be a member of the **Architecture** - group and any other groups defined in your - `sources.xml`_ file in order for the client to be - associated to the proper sources. If you are using - :ref:`server-plugins-generators-packages-magic-groups`, then a - client must also be a member of the appropriate OS group. - -.. _server-plugins-generators-packages-magic-groups: - -"Magic Groups" -============== - -.. deprecated:: 1.3.0 - -Packages has the ability to use a feature known as "magic groups"; it -is the only plugin to use that feature. Most plugins operate based on -client group memberships, without any concern for the particular names -chosen for groups by the user. The Packages plugin is the sole -exception to this rule. Packages needs to "know" two different sorts -of facts about clients. The first is the basic OS/distro of the -client, enabling classes of sources. The second is the architecture of -the client, enabling sources for a given architecture. In addition to -these magic groups, each source may also specify non-magic groups to -limit the source's applicability to group member clients. - -+--------+----------+--------------+ -| Source | OS Group | Architecture | -+========+==========+==============+ -| Apt | debian | i386 | -+--------+----------+--------------+ -| Apt | ubuntu | amd64 | -+--------+----------+--------------+ -| Apt | nexenta | | -+--------+----------+--------------+ -| Apt | apt | | -+--------+----------+--------------+ -| Yum | redhat | i386 | -+--------+----------+--------------+ -| Yum | centos | x86_64 | -+--------+----------+--------------+ -| Yum | fedora | | -+--------+----------+--------------+ -| Yum | yum | | -+--------+----------+--------------+ - -Magic OS groups are disabled by default in Bcfg2 1.3 and greater. If -you require magic groups, you can enable them by setting -``magic_groups`` to ``1`` in the ``[packages]`` section of -``bcfg2.conf``. - -Magic groups will be removed in a future release. - -Magic architecture groups cannot be disabled. - Setup ===== @@ -102,14 +42,13 @@ Three basic steps are required for Packages to work properly. software repositories should be used, and which clients are eligible to use each one. #. Ensure that clients are members of the proper groups. Each client - should be a member of all of the groups listed in the `sources.xml` - (like ubuntu-intrepid or centos-5.2 in the following examples), one - of the architecture groups listed in the source configuration - (i386, amd64 or x86_64 in the following examples), and one of the - magic groups listed above, if magic groups are enabled. '''Failure - to do this will result in the source either not applying to the - client, or only architecture independent packages being made - available to the client.''' + should be a member of all of the groups listed in the + ``sources.xml`` (like ubuntu-intrepid or centos-5.2 in the + following examples), and one of the architecture groups listed in + the source configuration (i386, amd64 or x86_64 in the following + examples). '''Failure to do this will result in the source either + not applying to the client, or only architecture independent + packages being made available to the client.''' #. Add Package entries to bundles. #. Sit back and relax, as dependencies are resolved, and automatically added to client configurations. @@ -122,6 +61,7 @@ Packages plugin. It processes ``<Group>`` and ``<Client>`` tags just like Bundles. The primary element in ``sources.xml`` is the Source tag: .. xml:element:: Source + :noautodep: py:genshiElements Handling GPG Keys ----------------- @@ -198,9 +138,7 @@ processed. After this phase, but before entry binding, a list of packages and the client metadata instance is passed into Packages' resolver. This process determines a superset of packages that will fully satisfy dependencies of all package entries included in structures, and reports -any prerequisites that cannot be satisfied. This facility should largely -remove the need to use the :ref:`Base <server-plugins-structures-base>` -plugin. +any prerequisites that cannot be satisfied. Disabling dependency resolution ------------------------------- @@ -451,7 +389,7 @@ attribute, e.g.: .. code-block:: xml - <Bundle name="yum"> + <Bundle> <Group name="sles"> <Path name="/etc/yum/yum.repos.d/bcfg2.repo" altsrc="/etc/yum.repos.d/bcfg2.repo"/> diff --git a/doc/server/plugins/generators/pkgmgr.txt b/doc/server/plugins/generators/pkgmgr.txt index ace7c16ef..8d9979ba0 100644 --- a/doc/server/plugins/generators/pkgmgr.txt +++ b/doc/server/plugins/generators/pkgmgr.txt @@ -10,10 +10,10 @@ The Pkgmgr plugin resolves the Abstract Configuration Entity "Package" to a package specification that the client can use to detect, verify and install the specified package. -For a package specification to be included in the Literal configuration -the name attribute from an Abstract Package Tag (from Base or Bundler) -must match the name attribute of a Package tag in Pkgmgr, along with -the appropriate group associations of course. +For a package specification to be included in the Literal +configuration the name attribute from an abstract Package tag (from +Bundler) must match the name attribute of a Package tag in Pkgmgr, +along with the appropriate group associations of course. Each file in the Pkgmgr directory has a priority. This allows the same package to be served by multiple files. The priorities can be diff --git a/doc/server/plugins/generators/rules.txt b/doc/server/plugins/generators/rules.txt index a21dd217f..c5ff699a7 100644 --- a/doc/server/plugins/generators/rules.txt +++ b/doc/server/plugins/generators/rules.txt @@ -20,32 +20,14 @@ The Rules plugin resolves the following Abstract Configuration Entities: to literal configuration entries suitable for the client drivers to consume. -For an entity specification to be included in the Literal configuration -the name attribute from an Abstract Entity Tag (from Base or Bundler) -must match the name attribute of an Entity tag in Rules, along with the -appropriate group associations of course. +For an entity specification to be included in the Literal +configuration the name attribute from an abstract entity tag (from +Bundler) must match the name attribute of an entity tag in Rules, +along with the appropriate group associations of course. Each file in the Rules directory has a priority. This allows the same Entities to be served by multiple files. The priorities can be used to -break ties in the case that multiple files serve data for the same Entity. - - -Usage of Groups in Rules -======================== - -Groups are used by the Rules plugin, along with host metadata, for -selecting the Configuration Entity entries to include in the clients -literal configuration. They can be thought of as:: - - if client is a member of group1 then - assign to literal config - -Nested groups are conjunctive (logical and).:: - - if client is a member of group1 and group2 then - assign to literal config - -Group membership may be negated. +break ties in the case that multiple files serve data for the same entity. Tag Attributes in Rules ======================= @@ -511,8 +493,8 @@ If you wish, you can configure the Rules plugin to support regular expressions. This entails a small performance and memory usage penalty. To do so, add the following setting to ``bcfg2.conf``:: - [rules] - regex = yes + [rules] + regex = yes With regular expressions enabled, you can use a regex in the ``name`` attribute to match multiple abstract configuration entries. diff --git a/doc/server/plugins/generators/semodules.txt b/doc/server/plugins/generators/semodules.txt index 04d72e139..d75160cdf 100644 --- a/doc/server/plugins/generators/semodules.txt +++ b/doc/server/plugins/generators/semodules.txt @@ -41,7 +41,7 @@ SEModules handles ``<SEModule>`` entries. For instance: .. code-block:: xml - <Bundle name="foo"> + <Bundle> <SEModule name="foo.pp"/> </Bundle> @@ -50,7 +50,7 @@ The ``.pp`` extension is optional. .. note:: If you use a ``BoundSEModule`` tag, you must *not* include the - ``.pp`` extension. This is not recommend, though. + ``.pp`` extension. This is not recommended, though. You can also install a disabled module: diff --git a/doc/server/plugins/generators/sshbase.txt b/doc/server/plugins/generators/sshbase.txt index 2b6c8640b..641b9c598 100644 --- a/doc/server/plugins/generators/sshbase.txt +++ b/doc/server/plugins/generators/sshbase.txt @@ -160,6 +160,17 @@ in order to permit :ref:`pulling with bcfg2-admin <server-admin-pull>`. You should almost certainly set ``sensitive`` to "true" in ``info.xml``. +Encryption +========== + +SSHbase can optionally encrypt the private keys that it generates. To +enable this feature, set the ``passphrase`` option in the +``[sshbase]`` section of ``bcfg2.conf`` to the name of the passphrase +that should be used to encrypt all SSH keys. (The passphrases are +enumerated in the ``[encryption]`` section.) See +:ref:`server-encryption` for more details on Bcfg2 encryption in +general. + Blog post ========= diff --git a/doc/server/plugins/generators/sslca.txt b/doc/server/plugins/generators/sslca.txt deleted file mode 100644 index 7ef358a31..000000000 --- a/doc/server/plugins/generators/sslca.txt +++ /dev/null @@ -1,361 +0,0 @@ -.. -*- mode: rst -*- - -.. _server-plugins-generators-sslca: - -===== -SSLCA -===== - -SSLCA is a generator plugin designed to handle creation of SSL private -keys and certificates on request. - -Borrowing ideas from :ref:`server-plugins-generators-cfg-genshi` and -the :ref:`server-plugins-generators-sshbase` plugin, SSLCA automates -the generation of SSL certificates by allowing you to specify key and -certificate definitions. Then, when a client requests a Path that -contains such a definition within the SSLCA repository, the matching -key/cert is generated, and stored in a hostfile in the repo so that -subsequent requests do not result in repeated key/cert recreation. In -the event that a new key or cert is needed, the offending hostfile can -simply be removed from the repository, and the next time that host -checks in, a new file will be created. If that file happens to be the -key, any dependent certificates will also be regenerated. - -.. _getting-started: - -Getting started -=============== - -In order to use SSLCA, you must first have at least one CA configured -on your system. For details on setting up your own OpenSSL based CA, -please see http://www.openssl.org/docs/apps/ca.html for details of the -suggested directory layout and configuration directives. - -For SSLCA to work, the openssl.cnf (or other configuration file) for -that CA must contain full (not relative) paths. - -#. Add SSLCA to the **plugins** line in ``/etc/bcfg2.conf`` and - restart the 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. - -#. Under that section, add an entry for ``config`` that gives the - location of 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. - -#. Optionally, 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. If - you're using a self signing CA this would be the CA cert that you - generated. If the chain cert is a root CA cert (e.g., if it is a - self-signing CA), also add an entry ``root_ca = true``. If - ``chaincert`` is omitted, certificate verification will not be - performed. - -#. Once all this is done, you should have a section in your - ``/etc/bcfg2.conf`` that looks similar to the following:: - - [sslca_default] - config = /etc/pki/CA/openssl.cnf - passphrase = youReallyThinkIdShareThis? - chaincert = /etc/pki/CA/chaincert.crt - root_ca = true - -#. 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. - -#. Defining a key or certificate is similar to defining a Cfg file. - 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: - - .. code-block:: xml - - <KeyInfo> - <Key type="rsa" bits="2048" /> - </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. - -#. Similarly, create the matching directory structure for the - certificate path, and a `cert.xml`_ containing the following: - - .. code-block:: xml - - <CertInfo> - <Cert format="pem" key="/etc/pki/tls/private/localhost.key" - ca="default" days="365" c="US" l="New York" st="New York" - o="Your Company Name" /> - </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`` - -.. _sslca-configuration: - -Configuration -============= - -bcfg2.conf ----------- - -``bcfg2.conf`` contains miscellaneous configuration options for the -SSLCA plugin. These are described in some detail above in -`getting-started`, but are also enumerated here as a reference. Any -booleans in the config file accept the values "1", "yes", "true", and -"on" for True, and "0", "no", "false", and "off" for False. - -Each directive below should appear at most once in each -``[sslca_<name>]`` section. The following directives are understood: - -+--------------+------------------------------------------+---------+---------+ -| Name | Description | Values | Default | -+==============+==========================================+=========+=========+ -| config | Path to the openssl config for the CA | String | None | -+--------------+------------------------------------------+---------+---------+ -| passphrase | Passphrase for the CA private key | String | None | -+--------------+------------------------------------------+---------+---------+ -| chaincert | Path to the SSL chaining certificate for | String | None | -| | verification | | | -+--------------+------------------------------------------+---------+---------+ -| root_ca | Whether or not ``<chaincert>`` is a root | Boolean | false | -| | CA (as opposed to an intermediate cert) | | | -+--------------+------------------------------------------+---------+---------+ - -Only ``config`` is required. - -cert.xml --------- - -.. xml:schema:: sslca-cert.xsd - :linktotype: - :inlinetypes: CertType - -Example -^^^^^^^ - -.. code-block:: xml - - <CertInfo> - <subjectAltName>test.example.com</subjectAltName> - <Group name="apache"> - <Cert key="/etc/pki/tls/private/foo.key" days="730"/> - </Group> - <Group name="nginx"> - <Cert key="/etc/pki/tls/private/foo.key" days="730" - append_chain="true"/> - </Group> - </CertInfo> - -key.xml -------- - -.. xml:schema:: sslca-key.xsd - :linktotype: - :inlinetypes: KeyType - -Example -^^^^^^^ - -.. code-block:: xml - - <KeyInfo> - <Group name="fast"> - <Key type="rsa" bits="1024"/> - </Group> - <Group name="secure"> - <Key type="rsa" bits="4096"/> - </Group> - </KeyInfo> - -Automated Bcfg2 SSL Authentication -================================== - -This section describes one possible scenario for automating ssl -certificate generation and distribution for bcfg2 client/server -communication using SSLCA. The process involves configuring a -certificate authority (CA), generating the CA cert and key pair, -configuring the bcfg2 SSLCA plugin and a Bundle to use the SSLCA -generated certs to authenticate the bcfg2 client and server. - -OpenSSL CA ----------- - -If you already have a SSL CA available you can skip this section, -otherwise you can easily build one on the server using openssl. The -paths should be adjusted to suite your preferences. - -#. Prepare the directories and files:: - - mkdir -p /etc/pki/CA/newcerts - mkdir /etc/pki/CA/crl - echo '01' > /etc/pki/CA/serial - touch /etc/pki/CA/index.txt - touch /etc/pki/CA/crlnumber - -#. Edit the ``openssl.cnf`` config file, and in the **[ CA_default ]** - section adjust the following parameters:: - - dir = /etc/pki # Where everything is kept - certs = /etc/pki/CA/certs # Where the issued certs are kept - database = /etc/pki/CA/index.txt # database index file. - new_certs_dir = /etc/pki/CA/newcerts # default place for new certs. - certificate = /etc/pki/CA/certs/bcfg2ca.crt # The CA certificate - serial = /etc/pki/CA/serial # The current serial number - crl_dir = /etc/pki/CA/crl # Where the issued crl are kept - crlnumber = /etc/pki/CA/crlnumber # the current crl number - crl = /etc/pki/CA/crl.pem # The current CRL - private_key = /etc/pki/CA/private/bcfg2ca.key # The private key - -#. Create the CA root certificate and key pair. You'll be asked to - supply a passphrase, and some organizational info. The most - important bit is **Common Name** which you should set to be the - hostname of your bcfg2 server that your clients will see when doing - a reverse DNS query on it's ip address.:: - - openssl req -new -x509 -extensions v3_ca -keyout bcfg2ca.key \ - -out bcfg2ca.crt -days 3650 - -#. Move the generated cert and key to the locations specified in - ``openssl.cnf``:: - - mv bcfg2ca.key /etc/pki/CA/private/ - mv bcfg2ca.crt /etc/pki/CA/certs/ - -Your self-signing CA is now ready to use. - -Bcfg2 ------ - -SSLCA -^^^^^ - -The SSLCA plugin was not designed specifically to manage bcfg2 -client/server communication though it is certainly able to provide -certificate generation and management services for that -purpose. You'll need to configure the **SSLCA** plugin to serve the -key, and certificate paths that we will define later in our client's -``bcfg2.conf`` file. - -The rest of these instructions will assume that you've configured the -**SSLCA** plugin as described above and that the files -``SSLCA/etc/pki/tls/certs/bcfg2client.crt/cert.xml`` and -``SSLCA/etc/pki/tls/private/bcfg2client.key/key.xml`` represent the -cert and key paths you want generated for SSL auth. - -Client Bundle -^^^^^^^^^^^^^ - -To automate the process of generating and distributing certs to the -clients we need define at least the Cert and Key paths served by the -SSLCA plugin, as well as the ca certificate path in a Bundle. For -example: - -.. code-block:: xml - - <Path name='/etc/pki/tls/certs/bcfg2ca.crt'/> - <Path name='/etc/pki/tls/bcfg2client.crt'/> - <Path name='/etc/pki/tls/private/bcfg2client.key'/> - -Here's a more complete example bcfg2-client bundle: - -.. code-block:: xml - - <Bundle name='bcfg2-client'> - <Path name='/etc/bcfg2.conf'/> - <Path name='/etc/cron.d/bcfg2-client'/> - <Package name='bcfg2'/> - <Service name='bcfg2'/> - <Group name='rpm'> - <Path name='/etc/sysconfig/bcfg2'/> - <Path name='/etc/pki/tls/certs/bcfg2ca.crt'/> - <Path name='/etc/pki/tls/certs/bcfg2client.crt'/> - <Path name='/etc/pki/tls/private/bcfg2client.key'/> - </Group> - <Group name='deb'> - <Path name='/etc/default/bcfg2' altsrc='/etc/sysconfig/bcfg2'/> - <Path name='/etc/ssl/certs/bcfg2ca.crt' altsrc='/etc/pki/tls/certs/bcfg2ca.crt'/> - <Path name='/etc/ssl/certs/bcfg2client.crt' altsrc='/etc/pki/tls/certs/bcfg2client.crt'/> - <Path name='/etc/ssl/private/bcfg2client.key' altsrc='/etc/pki/tls/private/bcfg2client.key'/> - </Group> - </Bundle> - -In the above example we told Bcfg2 that it also needs to serve -``/etc/bcfg2.conf``. This is optional but convenient. - -The ``bcfg2.conf`` client config needs at least 5 parameters set for -SSL auth. - -#. ``key`` : This is the host specific key that SSLCA will generate. -#. ``certificate`` : This is the host specific cert that SSLCA will - generate. -#. ``ca`` : This is a copy of your CA certificate. Not generated by - SSLCA. -#. ``user`` : Usually set to fqdn of client. This *shouldn't* be - required but is as of 1.3.0. See: - http://trac.mcs.anl.gov/projects/bcfg2/ticket/1019 -#. ``password`` : Set to arbitrary string when using certificate - auth. This also *shouldn't* be required. See: - http://trac.mcs.anl.gov/projects/bcfg2/ticket/1019 - -Here's what a functional **[communication]** section in a -``bcfg2.conf`` genshi template for clients might look like.:: - - [communication] - protocol = xmlrpc/ssl - {% if metadata.uuid != None %}\ - user = ${metadata.uuid} - {% end %}\ - password = DUMMYPASSWORDFORCERTAUTH - {% choose %}\ - {% when 'rpm' in metadata.groups %}\ - certificate = /etc/pki/tls/certs/bcfg2client.crt - key = /etc/pki/tls/private/bcfg2client.key - ca = /etc/pki/tls/certs/bcfg2ca.crt - {% end %}\ - {% when 'deb' in metadata.groups %}\ - certificate = /etc/ssl/certs/bcfg2client.crt - key = /etc/ssl/private/bcfg2client.key - ca = /etc/ssl/certs/bcfg2ca.crt - {% end %}\ - {% end %}\ - -As a client will not be able to authenticate with certificates it does -not yet posses we need to overcome the chicken and egg scenario the -first time we try to connect such a client to the server. We can do so -using password based auth to boot strap the client manually specifying -all the relevant auth parameters like so:: - - bcfg2 -qv -S https://fqdn.of.bcfg2-server:6789 -u fqdn.of.client \ - -x SUPER_SECRET_PASSWORD - -If all goes well the client should recieve a freshly generated key and -cert and you should be able to run ``bcfg2`` again without specifying -the connection parameters. - -If you do run into problems you may want to review -:ref:`appendix-guides-authentication`. - -TODO -==== - -#. Add generation of pkcs12 format certs diff --git a/doc/server/plugins/generators/tcheetah.txt b/doc/server/plugins/generators/tcheetah.txt deleted file mode 100644 index c79a8ced5..000000000 --- a/doc/server/plugins/generators/tcheetah.txt +++ /dev/null @@ -1,197 +0,0 @@ -.. -*- mode: rst -*- - -.. _server-plugins-generators-tcheetah: - -======== -TCheetah -======== - -.. warning:: - - TCheetah is deprecated. You should instead use - :ref:`server-plugins-generators-cfg-cheetah` in the Cfg plugin. - -This document reflects the ``TCheetah`` plugin. - -The ``TCheetah`` plugin allows you to use the `cheetah templating system -<http://www.cheetahtemplate.org/>`_ to create files, instead of the -various diff-based methods offered by the ``Cfg`` plugin. It also allows -you to include the results of probes executed on the client in the -created files. - -To begin, you will need to download and install the Cheetah templating -engine from http://www.cheetahtemplate.org/. Once it is installed, -you can enable it by adding ``TCheetah`` to the ``plugins`` line in -``/etc/bcfg2.conf`` on your Bcfg server. For example:: - - plugins = Base,Bundler,Cfg,...,TCheetah - -The ``TCheetah`` plugin makes use of a ``Cfg``-like directory structure -located in in a ``TCheetah`` subdirectory of your repository, usually -``/var/lib/bcfg2/TCheetah``. Each file has a directory containing two -files, ``template`` and ``info``. The template is a standard Cheetah -template with two additions: - -* `self.metadata` is the client's :ref:`metadata <server-plugins-grouping-metadata-clientmetadata>` -* `self.metadata.Properties.xdata` is an xml document of unstructured data - -The ``info`` file is formatted like ``:info`` files from Cfg. - -Mostly, people will want to use client metadata. - -File permissions -================ - -File permissions for entries handled by TCheetah are controlled via the -use of :ref:`server-info` files. Note that you **cannot** use both a -Permissions entry and a Path entry to handle the same file. - -self.metadata variables -======================= - -self.metadata is an instance of the class ClientMetadata and documented -:ref:`here <server-plugins-grouping-metadata-clientmetadata>`. - -self.metadata.Properties.xdata -============================== - -.. note:: - - If you want to use Properties, you will need to enable the - :ref:`server-plugins-connectors-properties` plugin in - ``/etc/bcfg2.conf``. - -Properties.xdata is a python `ElementTree <http://codespeak.net/lxml/>`_ -object, loaded from the data in ``/var/lib/bcfg2/Properties/<properties -file>.xml``. That file should have a ``Properties`` node at its root. - -Example ``Properties/example.xml``: - -.. code-block:: xml - - <Properties> - <host> - <www.example.com> - <rootdev>/dev/sda</rootdev> - </www.example.com> - </host> - </Properties> - -You may use any of the ElementTree methods to access data in your -template. Several examples follow, each producing an identical result -on the host 'www.example.com':: - - $self.metadata.Properties['example.xml'].xdata.find('host').find('www.example.com').find('rootdev').text - $self.metadata.Properties['example.xml'].xdata.find('host').find($self.metadata.hostname).find('rootdev').text - ${self.metadata.Properties['example.xml'].xdata.xpath('host/www.example.com/rootdev')[0].text} - ${self.metadata.Properties['example.xml'].xdata.xpath('host/' + self.metadata.hostname + '/rootdev')[0].text} - #set $path = 'host/' + $self.metadata.hostname + '/rootdev' - ${self.metadata.Properties['example.xml'].xdata.xpath($path)[0].text} - ${self.metadata.Properties['example.xml'].xdata.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 -============== - -TCheetah works similar to Cfg in that you define all literal information -about a particular file in a directory rooted at TCheetah/path_to_file. -The actual file contents are placed in a file named `template` in that -directory. Below is a simple example a file ``/foo``. - -``/var/lib/bcfg2/TCheetah/foo/template`` - -.. code-block:: none - - > 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 - #end for - Categories: - #for $category in $self.metadata.categories: - * $category -- $self.metadata.categories[$category] - #end for - - Probes: - #for $probe in $self.metadata.Probes: - * $probe -- $self.metadata.Probes[$probe] - #end for - -``/var/lib/bcfg2/TCheetah/foo/info`` - -.. code-block:: none - - mode: 624 - -Output ------- - -The following output can be generated with bcfg2-info. Note that probe -information is not persistent, hence, it only works when clients directly -query the server. For this reason, bcfg2-info output doesn't reflect -current client probe state. - -.. code-block:: xml - - <Path type="file" name="/foo" owner="root" mode="0624" group="root"> - Hostname is topaz.mcs.anl.gov - Filename is /foo - Template is /var/lib/bcfg2/TCheetah/foo/template - Groups: - * desktop - * mcs-base - * ypbound - * workstation - * xserver - * debian-sarge - * debian - * a - Categories: - * test -- a - - Probes: - </Path> - -Example: Replace the crontab plugin -=================================== - -In many cases you can use the TCheetah plugin to avoid writing custom -plugins in Python. This example randomizes the time of cron.daily -execution with a stable result. Cron.daily is run at a consistent, -randomized time between midnight and 7am.:: - - #import random - #silent random.seed($self.metadata.hostname) - - # /etc/crontab: system-wide crontab - # Unlike any other crontab you don't have to run the `crontab` - # command to install the new version when you edit this file. - # This file also has a username field, that none of the other crontabs do. - - SHELL=/bin/sh - PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin://bin - - # m h dom mon dow user command - 17 * * * * root run-parts --report /etc/cron.hourly - $random.randrange(0,59) $random.randrange(0,6) * * * root test -x /usr/sbin/anacron || run-parts --report /etc/cron.daily - 47 6 * * 7 root test -x /usr/sbin/anacron || run-parts --report /etc/cron.weekly - 52 6 1 * * root test -x /usr/sbin/anacron || run-parts --report /etc/cron.monthly. - -.. note:: Comments and Cheetah - As Cheetah processes your templates it will consider hash "#" style - comments to be actual comments in the template and will strip them - from the final config file. If you would like to preserve the comment - in the final config file you need to escape the hash character '\#' - which will tell Cheetah (and Python) that you do in fact want the - comment to appear in the final config file.:: - - # This is a comment in my template which will be stripped when it's processed through Cheetah - \# This comment will appear in the generated config file. diff --git a/doc/server/plugins/generators/tgenshi.txt b/doc/server/plugins/generators/tgenshi.txt deleted file mode 100644 index 43a02f253..000000000 --- a/doc/server/plugins/generators/tgenshi.txt +++ /dev/null @@ -1,213 +0,0 @@ -.. -*- mode: rst -*- - -.. _server-plugins-generators-tgenshi-index: - -======= -TGenshi -======= - -.. warning:: - - The TGenshi plugin is deprecated. You should instead use - :ref:`server-plugins-generators-cfg-genshi` in the Cfg plugin. - -This page documents the TGenshi plugin. This plugin works with version -0.4 and newer of the genshi library. - -The TGenshi plugin allows you to use the `Genshi -<http://genshi.edgewall.org>`_ templating system to create files, -instead of the various diff-based methods offered by the Cfg -plugin. It also allows you to include the results of probes executed -on the client in the created files. - -To begin, you will need to download and install the Genshi templating engine. - -To install on CentOS or RHEL, run:: - - sudo yum install python-genshi - -Once it is installed, you can enable it by adding ``TGenshi`` to the -generators line in ``/etc/bcfg2.conf`` on your Bcfg server. For example:: - - plugins = Base,Bundler,Cfg,...,TGenshi - -The TGenshi plugin makes use of a Cfg-like directory structure -located in in a TGenshi subdirectory of your repository, usually -``/var/lib/bcfg2/TGenshi``. Each file has a directory containing two file -types, template and info. Templates are named according to the genshi -format used; template.txt uses the genshi text format, and template.xml -uses the XML format. - -If used with Genshi 0.5 or later the plugin also supports the `new -style -<http://genshi.edgewall.org/wiki/Documentation/0.5.x/text-templates.html>`_ -text template format for files named template.newtxt. One of the -advantages of the new format is that it does not use # as a command -delimiter, making it easier to utilize for configuration files that -use # as a comment character. - -Only one template format may be used per file served. Info files are -identical to those used in ``Cfg``, and ``info.xml`` files are -supported. - -Inside of templates -=================== - -* **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. 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 -Genshi syntax. - -Examples: Old Genshi Syntax ---------------------------- - -Genshi's web pages recommend against using this syntax, as it may -disappear from future releases. - -Group Negation -^^^^^^^^^^^^^^ - -Templates are also useful for cases where more sophisticated boolean -operations than those supported by Cfg are needed. For example, the -template:: - - #if "ypbound" in metadata.groups and "workstation" in metadata.groups - client is ypbound workstation - #end - #if "ubuntu" not in metadata.groups and "desktop" in metadata.groups - client is a desktop, but not an ubuntu desktop - #end - -Produces: - -.. code-block:: xml - - <Path type="file" name="/bar.conf" owner="root" mode="0644" group="root">client is ypbound workstation - client is a desktop, but not an ubuntu desktop - </Path> - -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 - -To generate a file with an altsrc attribute, you can run:: - - bcfg2-info buildfile /etc/foo/foo.conf --altsrc=/etc/foo.conf \ - foo.example.com - -Sometimes, it's useful to be able to do more in-depth troubleshooting -by running the template manually. 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)>" - -``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. - -Then, run:: - - import os, Bcfg2.Options - from genshi.template import TemplateLoader, NewTextTemplate - name = os.path.dirname(path[path.find('/', 1):]) - setup = Bcfg2.Options.OptionParser({'repo': - Bcfg2.Options.SERVER_REPOSITORY}) - setup.parse('--') - template = TemplateLoader().load(setup['repo'] + 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" - name = "/etc/sysconfig/network-scripts/ifcfg-bond0" - -File permissions -================ - -File permissions for entries handled by TGenshi are controlled via the -use of :ref:`server-info` files. Note that you **cannot** use both a -Permissions entry and a Path entry to handle the same file. - -Error handling -================ - -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:: - - {% python - from genshi.template import TemplateError - grp = None - for g in metadata.groups: - if g.startswith('ganglia-gmond-'): - grp = g - break - else: - raise TemplateError, "Missing group" - %}\ - -will fail to bind if the client is not a member of a group starting with -"ganglia-gmond-". The syslogs on the server will contain this message:: - - bcfg2-server[5957]: Genshi template error: Missing group - bcfg2-server[5957]: Failed to bind entry: Path /etc/ganglia/gmond.conf - -indicating the bind failure and message raised with the TemplateError. - -FAQs -==== - -**Question** - -How do I escape the $ (dollar sign) in a TGenshi text template? For -example, if I want to include SVN (subversion) keywords like $Id$ or -$HeadURL$ in TGenshi-generated files, or am templating a bourne shell -(sh/bash) script or Makefile (make). - -**Answer** - -Use $$ (double dollar sign) to output a literal $ (dollarsign) -in a TGenshi text template. So instead of $Id$, you'd use -$$Id$$. See also Genshi tickets `#282: Document $$ escape -convention <http://genshi.edgewall.org/ticket/282>`_ and -`#283: Allow for redefinition of template syntax per-file -<http://genshi.edgewall.org/ticket/283>`_. - -Examples -======== - -.. toctree:: - :glob: - :maxdepth: 1 - - examples/genshi/* diff --git a/doc/server/plugins/grouping/metadata.txt b/doc/server/plugins/grouping/metadata.txt index ceac5dc24..832b1a13f 100644 --- a/doc/server/plugins/grouping/metadata.txt +++ b/doc/server/plugins/grouping/metadata.txt @@ -90,6 +90,8 @@ Database Settings <server-database>`. The `clients.xml`_-based model remains the default. +.. _server-plugins-grouping-metadata-groups-xml: + groups.xml ========== @@ -180,76 +182,6 @@ groups: .. xml:schema:: metadata.xsd - -XInclude -======== - -.. versionadded:: 0.9.0 - -`XInclude <http://www.w3.org/TR/xinclude/>`_ is a W3C specification -for the inclusion of external XML documents into XML source files, -allowing complex definitions to be split into smaller, more manageable -pieces. The `Metadata`_ plugin supports the use of XInclude -specifications to split the `clients.xml`_ and `groups.xml`_ -files. This mechanism allows the following specification to produce -useful results: - -.. code-block:: xml - - <Groups xmlns:xi="http://www.w3.org/2001/XInclude"> - <xi:include href="my-groups.xml" /> - <xi:include href="their-groups.xml" /> - </Groups> - -Each of the included groups files has the same format. These files are -properly validated by ``bcfg2-lint``. This mechanism is useful for -composing group definitions from multiple sources, or setting -different permissions in an svn repository. - -You can also optionally include a file that may or may not exist with -the ``fallback`` tag: - -.. code-block:: xml - - <Groups xmlns:xi="http://www.w3.org/2001/XInclude"> - <xi:include href="my-groups.xml"/> - <xi:include href="their-groups.xml"><xi:fallback/></xi:include> - </Groups> - -In this case, if ``their-groups.xml`` does not exist, no error will be -raised and everything will work fine. (You can also use ``fallback`` -to include a different file, or explicit content in the case that the -parent include does not exist.) - -Wildcard XInclude ------------------ - -.. versionadded:: 1.3.1 - -Bcfg2 supports an extension to XInclude that allows you to use shell -globbing in the hrefs. (Stock XInclude doesn't support this, since -the href is supposed to be a URL.) - -For instance: - -.. code-block:: xml - - <Groups xmlns:xi="http://www.w3.org/2001/XInclude"> - <xi:include href="groups/*.xml"/> - </Groups> - -This would include all ``*.xml`` files in the ``groups`` subdirectory. - -Note that if a glob finds no files, that is treated the same as if a -single included file does not exist. You should use the ``fallback`` -tag, described above, if a glob may potentially find no files. - -Probes -====== - -The metadata plugin includes client-side probing functionality. This -is fully documented :ref:`here <server-plugins-probes-index>`. - Metadata Caching ================ diff --git a/doc/server/plugins/misc/acl.txt b/doc/server/plugins/misc/acl.txt new file mode 100644 index 000000000..226b56a44 --- /dev/null +++ b/doc/server/plugins/misc/acl.txt @@ -0,0 +1,235 @@ +.. -*- mode: rst -*- + +.. _server-plugins-misc-acl: + +=== +ACL +=== + +The ACL plugin lets you set client communication ACLs to prevent +clients from accessing the full range of exposed XML-RPC methods. + +You can get a list of all exposed methods by running:: + + bcfg2-admin xcmd listMethods + +Note that this will only list methods that are available to the client +this is run from; that is, if the ACL plugin is in place, +``listMethods`` will reflect the ACLs. + +ACLs can be set in two different ways: + +* IP-based ACLs allow you to set ACLs based on client IP address or + CIDR range. +* Metadata-based ACLs allow you to set ACLs based on client hostname, + group membership, or complex combinations thereof. + +IP-based ACLs are much faster, but metadata-based ACLs are often +easier and better. + +If you are not going to use any ACLs, it is recommended that you +disable this plugin because using it can incur a slight performance +hit. If you are using IP-based ACLs but *not* metadata-based ACLs, it +is similarly recommended that you ensure that your IP-based ACL file +ends with an explicit Deny for all clients; this will ensure that +metadata-based ACLs are never checked. If you are using +metadata-based ACLs, :ref:`server-caching` can alleviate most of the +performance penalty. + +Enabling the ACL plugin +======================= + +First, create ``/var/lib/bcfg2/ACL/``. Then, add ``ACL`` to your +``plugins`` list in ``bcfg2.conf``:: + + plugins = Bundler, Cfg, ..., Packages, ACL + +Finally, create ``/var/lib/bcfg2/ACL/ip.xml`` (for `IP-based ACLs`_), +``/var/lib/bcfg2/ACL/metadata.xml`` (for `Metadata-based ACLs`_), or +both. + +IP-based ACLs +============= + +IP-based ACLs allow you to set ACLs based on client IP address or CIDR +range. IP-based ACLs are very fast. If you are using IP-based ACLs +but *not* metadata-based ACLs, it is recommended that you ensure that +your IP-based ACL file ends with an explicit Deny for all clients; +this will ensure that metadata-based ACLs are never checked. + +IP-based ACLs are defined in ``ACL/ip.xml``. The file is parsed +sequentially; the first matching rule applies. Each rule is either +Allow (to allow the client access), Deny (to deny the client access), +or Defer (to defer to `Metadata-based ACLs`_). The last rule in +``ip.xml`` is an implicit default allow for 127.0.0.1, and an implicit +default defer for all other machines. + +If no ``ip.xml`` file exists, then ACL checking will be deferred to +metadata-based ACLs. + +Example +------- + +.. code-block:: xml + + <ACL> + <Allow address="192.168.1.10" method="*.*"/> + <Deny address="192.168.2.0" netmask="255.255.255.0" + method="AssertProfile"/> + <Allow address="192.168.1.12" method="Git.Update"/> + <Allow method="*"/> + </ACL> + +In this example: + +* The machine at 192.168.1.10 (perhaps the Bcfg2 server) can call all + plugin XML-RPC methods; +* Machines in the 192.168.2.0/24 network cannot assert their own + profiles; +* The machine at 192.168.1.12 (perhaps the Git server) can call the + Git.Update method; +* All machines can call core methods (except 192.168.2.0/24, which can + call all core methods except AssertProfile). + +Implicitly, all machines (except localhost) except 192.168.1.10 are +disallowed access to the plugin methods. + +You can also provide a minimal configuration to try to weed out some +obvious bad requests before doing the more expensive `Metadata-based +ACLs`_. For instance: + +.. code-block:: xml + + <ACL> + <Allow method="*"/> + <Defer address="192.168.1.0" netmask="24" method="*.*"/> + <Deny method="*.*"/> + </ACL> + +In this example: + +* All machines can call all core methods without checking metadata + ACLs; +* Plugin method calls from machines in 192.168.1.0/24 are deferred to + metadata ACLs; and +* All other plugin method calls are denied. + +The only time metadata ACLs would be checked in this example would be +plugin method calls by machines in 192.168.1.0/24. + +Reference +--------- + +.. xml:type: IPACLContainerType + +Metadata-based ACLs +=================== + +Metadata-based ACLs let you set ACLs based on client hostname or group +membership, which is much more flexible and maintainable than +`IP-based ACLs`_. The downside is that it is slower, because it +requires generating client metadata for each machine that tries to +authenticate. Without :ref:`server-caching`, using metadata-based +ACLs will double the number of client metadata builds per client run, +which could be a sizeable performance penalty. + +In order to limit the performance penalty, it's highly recommended +to: + +* Enable :ref:`server-caching` in ``cautious`` or ``aggressive`` mode; + and +* Deny as many clients as possible with `IP-based ACLs`_. + +Metadata-based ACLs are defined in ``ACL/metadata.xml``. Only Allow +and Deny rules are supported, not Defer rules. The file is parsed +sequentially; the first matching rule applies. The last rule in +``metadata.xml`` is an implicit default allow for machines called +``localhost`` or ``localhost.localdomain``, and an implicit default +deny for all other machines. + +If no ``metadata.xml`` file exists, then all requests are implicitly +allowed. + +Example +------- + +This example is functionally identical to the `IP-based ACLs` example +above, but more maintainable in several ways: + +.. code-block:: xml + + <ACL> + <Group name="bcfg2-server"> + <Allow method="*.*"/> + </Group> + <Group name="user-workstations"> + <Deny method="AssertProfile"/> + </Group> + <Group name="git-server"> + <Allow method="Git.Update"/> + </Group> + <Allow method="*"/> + </ACL> + +In this case, if you add a Bcfg2 server or Git server, or one of those +servers changes IP address, you don't need to rewrite your ACLs. +Similarly, you could add a new subnet of user workstations. + +Reference +--------- + +.. xml:type: MetadataACLContainerType + +.. _server-plugins-misc-acl-wildcards: + +Wildcards +========= + +The ACL descriptions allow you to use '*' as a wildcard for any number +of characters *other than* ``.``. That is: + +* ``*`` would match ``DeclareVersion`` and ``GetProbes``, but would + *not* match ``Git.Update``. +* ``*.*`` would match ``Git.Update``, but not ``DeclareVersion`` or + ``GetProbes``. + +Since all plugin methods are scoped to their plugin (i.e., they are +all ``<plugin name>.<method name>``), and all core methods have no +scope, this lets you easily allow or deny core or plugin methods. You +could also do something like ``*.toggle_debug`` to allow a host to +enable or disable debugging for all plugins. + +No other bash globbing is supported. + +Examples +======== + +The :ref:`default ACL list <server-access-control>` can be described +in ``ip.xml`` fairly simply: + +.. code-block:: xml + + <ACL> + <Allow address="127.0.0.1" method="*.*"/> + <Allow address="127.0.0.1" method="*"/> + <Deny method="*.*"/> + <Deny method="*_debug"/> + <Deny method="get_statistics"/> + <Allow method="*"/> + </ACL> + +A basic configuration that is still very secure but perhaps more +functional could be given in ``metadata.xml``: + +.. code-block:: xml + + <ACL> + <Group name="bcfg2-server"> + <Allow method="*.*"/> + <Allow method="*"/> + </Group> + <Deny method="*.*"/> + <Deny method="*_debug"/> + <Deny method="get_statistics"/> + <Allow method="*"/> + </ACL> diff --git a/doc/server/plugins/probes/fileprobes.txt b/doc/server/plugins/probes/fileprobes.txt index 0baec2c59..1bee38c5a 100644 --- a/doc/server/plugins/probes/fileprobes.txt +++ b/doc/server/plugins/probes/fileprobes.txt @@ -1,3 +1,5 @@ +.. -*- mode: rst -*- + .. _server-plugins-probes-fileprobes: ========== diff --git a/doc/server/plugins/statistics/reporting.txt b/doc/server/plugins/statistics/reporting.txt index c3c51cd29..74ea61e62 100644 --- a/doc/server/plugins/statistics/reporting.txt +++ b/doc/server/plugins/statistics/reporting.txt @@ -9,7 +9,7 @@ Reporting Reporting can be enabled by adding Reporting to the plugins line in ``/etc/bcfg2.conf``: - plugins = Base,Bundler,Cfg,...,Reporting + plugins = Bundler,Cfg,...,Reporting For more information on how to use Reporting to setup reporting, see :ref:`reports-dynamic`. diff --git a/doc/server/plugins/statistics/statistics.txt b/doc/server/plugins/statistics/statistics.txt deleted file mode 100644 index d16f5a828..000000000 --- a/doc/server/plugins/statistics/statistics.txt +++ /dev/null @@ -1,7 +0,0 @@ -.. -*- mode: rst -*- - -.. _server-plugins-statistics-statistics: - -========== -Statistics -========== diff --git a/doc/server/plugins/structures/altsrc.txt b/doc/server/plugins/structures/altsrc.txt index 1268a8584..f3911e33e 100644 --- a/doc/server/plugins/structures/altsrc.txt +++ b/doc/server/plugins/structures/altsrc.txt @@ -11,7 +11,7 @@ altsrc Altsrc is a generic, Bcfg2 server-side mechanism for performing configuration entry name remapping for the purpose of data binding. Altsrc can be used as a parameter for any entry type, and can be used -in any structure, including Bundler and Base. +in any structure. Use Cases ========= @@ -36,7 +36,7 @@ Examples .. code-block:: xml - <Bundle name='netinfo'> + <Bundle> <Group name='solaris'> <Path name='/etc/inet/hosts' altsrc='/etc/hosts'/> </Group> @@ -58,7 +58,7 @@ Examples .. code-block:: xml - <Bundle name='openssl'> + <Bundle> <Package name='openssl' altsrc='openssl-encap'/> <Package name='openssl' altsrc='openssl-rpm'/> </Bundle> @@ -76,7 +76,7 @@ Examples .. code-block:: xml - <Bundle name='firewall'> + <Bundle> ... <Group name='conduit'> <Path name='/etc/firewall-rules' altsrc='/etc/firewall-rules-external'/> @@ -97,7 +97,7 @@ Examples .. code-block:: xml - <Bundle name='netconfig'> + <Bundle> <Path name='/etc/sysconfig/network-scripts/ifcfg-eth0' altsrc='/etc/ifcfg-template'/> <Path name='/etc/sysconfig/network-scripts/ifcfg-eth1' altsrc='/etc/ifcfg-template'/> <Path name='/etc/sysconfig/network-scripts/ifcfg-eth2' altsrc='/etc/ifcfg-template'/> diff --git a/doc/server/plugins/structures/base.txt b/doc/server/plugins/structures/base.txt deleted file mode 100644 index 03eae0573..000000000 --- a/doc/server/plugins/structures/base.txt +++ /dev/null @@ -1,83 +0,0 @@ -.. -*- mode: rst -*- - -.. _server-plugins-structures-base: - -==== -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. - -Base works much like Bundler in its file format. The main difference -between Base and Bundler is that Base files are included in all clients' -configuration whereas bundles must be included explicitly in your -Metadata. See the :ref:`server-plugins-structures-bundler-index` page -for details. - -If you have lots of unconnected items (for instance: software packages -whose configuration wasn't modified, and that are also not depended -on by other packages; or single directories or files not belonging -to a package), using Bundles in Metadata would clutter or enlarge -your ``Metadata/groups.xml`` file, because they all would need to be -explicitly specified. ``Base/`` on the other hand is the perfect place -to put these items. - -Without using Base, you would be forced to put them directly -into your group definitions in ``groups.xml``, either as many -small bundles (substantially enlarging it) or into something like -``Bundler/unrelated-entries.xml``. Using the latter is especially bad -if you mix packages and services in your Bundle, since for any updated -package in that bundle, the now-related services would be restarted. - -The Base entries can still be assigned based on group membership, but when -they aren't part of a group, each and every client gets the entry. So Base is -also a great place to put entries that a large number of your clients will -get. - -For example, you could have a file ``Base/packages.xml`` - -.. code-block:: xml - - <Base> - <Package name='acpid'/> - <Package name='auditd'/> - [...] - <Group name='openSUSE11.2'> - <Package name='syslog-ng'/> - </Group> - <Group name='openSUSE11.3'> - <Package name='rsyslog'/> - </Group> - [...] - <Package name='zlib'/> - </Base> - -.. note:: - - You don't have to reference to the files in Base from anywhere. As long - as you include ``Base`` in your ``plugins = ...`` line in ``bcfg2.conf``, - these are included automatically. - -.. note:: - - Your Base files have to match the pattern ``Base/*.xml`` to be included. - - -The decision when to use Base and when to use Bundler depends on the -configuration entry in question, and what you are trying to achieve. - -Base is mainly used for cases where you don't want/need to explicitly -include particular configuration items. Let's say all your machines are -various linux distributions. In this case, you may want to manage the -``/etc/hosts`` file using Base instead of Bundler since you will not have -to include any Bundles in your Metadata. However, you could alternatively -have a base 'linux' group that all the clients inherit which includes a -*linux* Bundle with the ``/etc/hosts`` configuration entry. diff --git a/doc/server/plugins/structures/bundler/bcfg2.txt b/doc/server/plugins/structures/bundler/bcfg2.txt new file mode 100644 index 000000000..0fd0a3fdf --- /dev/null +++ b/doc/server/plugins/structures/bundler/bcfg2.txt @@ -0,0 +1,87 @@ +.. -*- mode: rst -*- + +.. _server-plugins-structures-bundler-bcfg2-server: + +Bcfg2 Server +============ + +These two bundles split out the entries that do require a restart of +``bcfg2-server`` from those that don't. + +These bundles also demonstrate use of bound entries to avoid splitting +entries between Bundler and Rules. + +``Bundler/bcfg2-server.xml``: + +.. code-block:: xml + + <Bundle> + <Bundle name="bcfg2-server-base.xml"/> + + <Path name="/etc/pki/tls/private/bcfg2.key"/> + <Path name="/etc/sysconfig/bcfg2-server"/> + <Path name="/etc/bcfg2.conf"/> + + <BoundPath name="/var/lib/bcfg2/Packages/cache" type="directory" + owner="bcfg2" group="bcfg2" mode="0755"/> + <BoundPath name="/var/lib/bcfg2" type="symlink" + to="/var/lib/bcfg2-vcs/bcfg2/public"/> + <BoundPath name="/var/lib/bcfg2/etc/bcfg2.sqlite" type="permissions" + owner="bcfg2" group="apache" mode="0660"/> + + <BoundService name="bcfg2-server" type="chkconfig" status="on"/> + + <Package name="bcfg2-server"/> + <Package name="python-genshi"/> + <Package name="python-inotify"/> + <Package name="Django"/> + <Package name="Django-south"/> + <Package name="m2crypto"/> + <Package name="GitPython"/> + </Bundle> + +``Bundler/bcfg2-server-base.xml``: + +.. code-block:: xml + + <Bundle> + <Path name="/etc/bcfg2-web.conf"/> + <Path name="/etc/cron.daily/bcfg2_cleanup_db"/> + + <BoundPOSIXGroup name='bcfg2'/> + <BoundPOSIXUser name='bcfg2' shell='/sbin/nologin' gecos='Bcfg2 User'/> + <Path name="/home/bcfg2/.ssh/id_rsa"/> + + <!-- SSL CA setup --> + <BoundPath name="/etc/pki/CA" type="directory" important="true" + owner="bcfg2" group="bcfg2" mode="755"/> + <BoundPath name="/etc/pki/CA/crl" type="directory" owner="bcfg2" + group="bcfg2" mode="755"/> + <BoundPath name="/etc/pki/CA/certs" type="directory" owner="bcfg2" + group="bcfg2" mode="755"/> + <BoundPath name="/etc/pki/CA/newcerts" type="directory" owner="bcfg2" + group="bcfg2" mode="755"/> + <BoundPath name="/etc/pki/CA/private" type="directory" owner="bcfg2" + group="bcfg2" mode="755"/> + <Path name="/etc/pki/CA/openssl.cnf" altsrc="/etc/pki/CA/openssl.cnf"/> + <Path name="/etc/pki/CA/index.txt.attr"/> + <Path name="/etc/pki/CA/CA.crt"/> + <Path name="/etc/pki/CA/CA.key"/> + <Path name="/etc/pki/CA/CA.pem"/> + <Path name="/etc/pki/tls/certs/server-chain.crt"/> + <BoundPath name="/etc/pki/CA/serial" type="permissions" owner="bcfg2" + group="bcfg2" mode="0600"/> + <BoundPath name="/etc/pki/CA/index.txt" type="permissions" owner="bcfg2" + group="bcfg2" mode="0600"/> + <BoundPath name="/etc/pki/CA/crlnumber" type="permissions" owner="bcfg2" + group="bcfg2" mode="0644"/> + <BoundAction + name="create-CA-serial" timing="post" when="always" status="check" + command="[ -e /etc/pki/CA/serial ] || echo '01' > /etc/pki/CA/serial"/> + <BoundAction + name="create-CA-index" timing="post" when="always" status="check" + command="[ -e /etc/pki/CA/index.txt ] || touch /etc/pki/CA/index.txt"/> + <BoundAction + name="create-CA-crlnumber" timing="post" when="always" status="check" + command="[ -e /etc/pki/CA/crlnumber ] || touch /etc/pki/CA/crlnumber"/> + </Bundle> diff --git a/doc/server/plugins/structures/bundler/index.txt b/doc/server/plugins/structures/bundler/index.txt index a19959e66..0b6b8eb50 100644 --- a/doc/server/plugins/structures/bundler/index.txt +++ b/doc/server/plugins/structures/bundler/index.txt @@ -19,142 +19,112 @@ will receive. 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. +one Linux distro may have a package called ``openssh`` while another +uses the name ``ssh``. See :ref:`xml-group-client-tags` for details +and a longer example. -The following is an annotated copy of a bundle: +A brief example: .. code-block:: xml - <Bundle name='ssh' version='2.0'> - <Path name='/etc/ssh/ssh_host_dsa_key'/> - <Path name='/etc/ssh/ssh_host_rsa_key'/> - <Path name='/etc/ssh/ssh_host_dsa_key.pub'/> - <Path name='/etc/ssh/ssh_host_rsa_key.pub'/> - <Path name='/etc/ssh/ssh_host_key'/> - <Path name='/etc/ssh/ssh_host_key.pub'/> - <Path name='/etc/ssh/sshd_config'/> + <Bundle> <Path name='/etc/ssh/ssh_config'/> - <Path name='/etc/ssh/ssh_known_hosts'/> <Group name='rpm'> - <Package name='openssh'/> - <Package name='openssh-askpass'/> <Service name='sshd'/> - <Group name='fedora' > - <Group name='fc14' negate='true'> - <Package name='openssh-clients'/> - </Group> - <Package name='openssh-server'/> - </Group> + <Package name='openssh-server'/> </Group> <Group name='deb'> <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. 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/Hostname | Entry | -+============================+===============================+ -| all | /etc/ssh/ssh_host_dsa_key | -+----------------------------+-------------------------------+ -| all | /etc/ssh/ssh_host_rsa_key | -+----------------------------+-------------------------------+ -| all | /etc/ssh/ssh_host_dsa_key.pub | -+----------------------------+-------------------------------+ -| all | /etc/ssh/ssh_host_rsa_key.pub | -+----------------------------+-------------------------------+ -| all | /etc/ssh/ssh_host_key | -+----------------------------+-------------------------------+ -| all | /etc/ssh/ssh_host_key.pub | -+----------------------------+-------------------------------+ -| all | /etc/ssh/sshd_config | -+----------------------------+-------------------------------+ -| all | /etc/ssh/ssh_config | -+----------------------------+-------------------------------+ -| all | /etc/ssh/ssh_known_hosts | -+----------------------------+-------------------------------+ -| rpm | Package openssh | -+----------------------------+-------------------------------+ -| rpm | Package openssh-askpass | -+----------------------------+-------------------------------+ -| rpm | Service sshd | -+----------------------------+-------------------------------+ -| rpm and fedora | Package openssh-server | -+----------------------------+-------------------------------+ -| rpm and fedora and not fc4 | Package openssh-clients | -+----------------------------+-------------------------------+ -| deb | Package ssh | -+----------------------------+-------------------------------+ -| deb | Service ssh | -+----------------------------+-------------------------------+ -| trust.example.com | /etc/ssh/shosts.equiv | -+----------------------------+-------------------------------+ +Note that we do not specify *how* a given entry should be managed, +only that it should be. The concrete specification of each entry will +be provided by a different plugin such as +:ref:`server-plugins-generators-cfg`, +:ref:`server-plugins-generators-rules`, or +:ref:`server-plugins-generators-packages`. -Genshi templates -================ +Alternatively, you can use fully-bound entries in Bundler, which has +various uses. For instance: -Genshi XML templates allow you to use the `Genshi -<http://genshi.edgewall.org>`_ templating system to dynamically -generate a bundle. Genshi templates can be specified one of two ways: +.. code-block:: xml -1. Add an XML-style genshi template to the Bundler directory with a - ``.genshi`` and the associated namespace attribute. -2. Simply add the appropriate namespace attribute to your existing XML - bundle. + <Bundle> + <Path name='/etc/ssh/ssh_config'/> + <Group name='rpm'> + <BoundService name='sshd' type="chkconfig" status="on"/> + <BoundPackage name='openssh-server' version='5.8p2' type="yum" /> + </Group> + <Group name='deb'> + <Package name='ssh'/> + <BoundService name='ssh' type="chkconfig" status="on"/> + </Group> + </Bundle> -The top-level Bundle tag should look like the following:: +In this example, both Service tags and one Package tag are fully bound +-- i.e., all information required by the client to manage those +entries is provided in the bundle itself. - <Bundle name="foo" xmlns:py="http://genshi.edgewall.org/"> +.. _server-plugins-structures-bundler-magic: -Several variables are pre-defined inside templates: +Bundle "Magic" +============== -+-------------+--------------------------------------------------------+ -| Name | Description | -+=============+========================================================+ -| metadata | :ref:`Client metadata | -| | <server-plugins-grouping-metadata-clientmetadata>` | -+-------------+--------------------------------------------------------+ -| repo | The path to the Bcfg2 repository on the filesystem | -+-------------+--------------------------------------------------------+ +Bundles are collections of *related* entries. That point is very, +very important, because a bundle performs certain "magic" actions when +one or more entries in it are modified: + +* :xml:type:`Service <ServiceType>` entries whose ``restart`` + attribute is ``true`` (the default) will be restarted. +* :xml:type:`Action <ActionType>` entries whose ``when`` attribute is + ``modified`` will be run. + +Because of these two magic actions, it's extremely important to +structure your bundles around Service and Action entries, rather than +around some loose idea of which entries are related. For instance, in +order to manage a Bcfg2 server, a number of packages, paths, services, +etc. must be managed. But not all of these entries would require +``bcfg2-server`` to be restarted, so to limit restarts it's wise to +split these entries into two bundles. See +:ref:`server-plugins-structures-bundler-bcfg2-server` for an example +of this. + +Disabling Magic +--------------- -.. note:: +Disabling magic bundler actions can be done in one of two ways: - ``<Group>`` and ``<Client>`` tags are allowed inside of Genshi - templates as of Bcfg2 1.2. However, they do not behave the same - as using a Genshi conditional, e.g.:: +* On a per-entry basis. Set ``restart="false"`` on a Service to + prevent it from being restarted when the bundle is modified. Set + ``when="always"`` on an Action to cause it to run every time, + regardless of whether or not the bundle was modified. +* On a per-bundle basis. Set ``independent="true"`` on the top-level + ``Bundle`` tag to signify that the bundle is a collection of + independent (i.e., unrelated) entries, and to prevent any magic + actions from being performed. (This is similar to the ``Base`` + plugin in older versions of Bcfg2.) This was added in Bcfg2 1.4. - <py:if test="'groupname' in metadata.groups"> - </py:if> +Service entries in independent bundles are never restarted, and Action +entries in independent bundles are only executed if ``when="always"``. +(I.e., an Action entry in an independent bundle with +``when="modified"`` is useless.) + +Genshi templates +================ + +Genshi XML templates allow you to use the `Genshi +<http://genshi.edgewall.org>`_ templating system to dynamically +generate a bundle. Genshi templates can be specified one of two ways: - The conditional is evaluated when the template is rendered, so - code inside the conditional is not executed if the conditional - fails. A ``<Group>`` tag is evaluated *after* the template is - rendered, so code inside the tag is always executed. This is an - important distinction: if you have code that will fail on some - groups, you *must* use a Genshi conditional, not a ``<Group>`` - tag. The same caveats apply to ``<Client>`` tags. +1. Add an XML-style genshi template to the Bundler directory with a + ``.genshi`` and the associated namespace attribute. *This is + deprecated as of Bcfg2 1.4.* +2. Add the Genshi namespace to your existing XML + bundle. -See also the :ref:`xml-genshi-reference`. +See :ref:`xml-genshi-templating` for details. Troubleshooting --------------- @@ -168,6 +138,55 @@ entries in the bundle. See :ref:`bcfg2-info <server-bcfg2-info>` for more details. +Dependencies +============ + +Dependencies on other bundles can be specified by adding an empty +bundle tag that adds another bundle by name, e.g.: + +.. code-block:: xml + + <Bundle> + <Bundle name="nfs-client"/> + ... + </Bundle> + +The dependent bundle is added to the list of bundles sent to the +client, *not* to the parent bundle itself. In other words, if an +entry in the dependent bundle changes, Services are restarted and +Actions are run in the dependent bundle *only*. An example: + +``nfs-client.xml``: + +.. code-block:: xml + + <Bundle> + <Package name="nfs-utils"/> + <Service name="nfslock"/> + <Service name="rpcbind"/> + <Service name="nfs"/> + </Bundle> + +``automount.xml``: + +.. code-block:: xml + + <Bundle> + <Bundle name="nfs-client"/> + + <Path name="/mnt/home"/> + <Path name="/etc/auto.master"/> + <Path name="/etc/auto.misc"/> + <Service name="autofs"/> + <Package name="automount"/> + </Bundle> + +If a new ``nfs-utils`` package was installed, the ``nfslock``, +``rpcbind``, and ``nfs`` services would be restarted, but *not* the +``autofs`` service. Similarly, if a new ``/etc/auto.misc`` file was +sent out, the ``autofs`` service would be restarted, but the +``nfslock``, ``rpcbind``, and ``nfs`` services would not be restarted. + Altsrc ====== @@ -184,8 +203,8 @@ in their name. The following template produces such a config file entry. .. code-block:: xml - <Bundle name='foo' xmlns:py="http://genshi.edgewall.org/"> - <Path name='/etc/package-${metadata.hostname}'/> + <Bundle xmlns:py="http://genshi.edgewall.org/"> + <Path name='/etc/package-${metadata.hostname}'/> </Bundle> Depending on the circumstance, these configuration files can either be @@ -199,7 +218,7 @@ and returns them in a newline delimited string. .. code-block:: xml - <Bundle name="networkinterfaces" xmlns:py="http://genshi.edgewall.org/"> + <Bundle xmlns:py="http://genshi.edgewall.org/"> <?python files = metadata.Probes["getmacs"].split("\n") ?> @@ -219,7 +238,7 @@ if declaration. .. code-block:: xml - <Bundle name='bacula' xmlns:py="http://genshi.edgewall.org/"> + <Bundle xmlns:py="http://genshi.edgewall.org/"> <Path name="/etc/bacula/bconsole.conf"/> <Path name="/etc/bacula/bacula-fd.conf"/> <Path name="/etc/bacula/bacula-sd.conf"/> @@ -231,7 +250,7 @@ or alternately .. code-block:: xml - <Bundle name='bacula' xmlns:py="http://genshi.edgewall.org/"> + <Bundle xmlns:py="http://genshi.edgewall.org/"> <Path name="/etc/bacula/bconsole.conf"/> <Path name="/etc/bacula/bacula-fd.conf"/> <Path name="/etc/bacula/bacula-sd.conf"/> @@ -244,7 +263,7 @@ or yet another way .. code-block:: xml - <Bundle name='bacula' xmlns:py="http://genshi.edgewall.org/"> + <Bundle xmlns:py="http://genshi.edgewall.org/"> <Path name="/etc/bacula/bconsole.conf"/> <Path name="/etc/bacula/bacula-fd.conf"/> <Path name="/etc/bacula/bacula-sd.conf"/> @@ -274,6 +293,7 @@ more complex example Bundles. .. toctree:: :maxdepth: 1 + bcfg2 kernel moab nagios diff --git a/doc/server/plugins/structures/bundler/kernel.txt b/doc/server/plugins/structures/bundler/kernel.txt index d83679683..54f70606f 100644 --- a/doc/server/plugins/structures/bundler/kernel.txt +++ b/doc/server/plugins/structures/bundler/kernel.txt @@ -22,7 +22,7 @@ some of which might be better than this one. Feel free to hack as needed. .. code-block:: xml - <Bundle name='kernel'> + <Bundle> <Group name='sles8'> <!-- =================== ia32 ==================== --> <Group name='ia32'> diff --git a/doc/server/plugins/structures/bundler/moab.txt b/doc/server/plugins/structures/bundler/moab.txt index e0d96be74..8f747376a 100644 --- a/doc/server/plugins/structures/bundler/moab.txt +++ b/doc/server/plugins/structures/bundler/moab.txt @@ -9,7 +9,7 @@ This is a fairly simple Bundle for the Moab workload manager. .. code-block:: xml - <Bundle name='moab' version='2.0'> + <Bundle> <Path name='/var/spool/moab'/> <Path name='/var/spool/moab/moab.cfg'/> <Group name='moab-server'> diff --git a/doc/server/plugins/structures/bundler/nagios.txt b/doc/server/plugins/structures/bundler/nagios.txt index fa5b67f30..d25e1cf0a 100644 --- a/doc/server/plugins/structures/bundler/nagios.txt +++ b/doc/server/plugins/structures/bundler/nagios.txt @@ -12,7 +12,7 @@ the clients. .. code-block:: xml - <Bundle name='nagios-client' version='2.0'> + <Bundle> <Group name='sles8'> <Package name='ucdsnmp'/> </Group> diff --git a/doc/server/plugins/structures/bundler/ntp.txt b/doc/server/plugins/structures/bundler/ntp.txt index b1264b5ee..31bc8a97a 100644 --- a/doc/server/plugins/structures/bundler/ntp.txt +++ b/doc/server/plugins/structures/bundler/ntp.txt @@ -12,7 +12,7 @@ better through use of groups. .. code-block:: xml - <Bundle name='ntp'> + <Bundle> <Package name='xntp'/> <Path name='/etc/sysconfig/xntp'/> <Path name='/etc/sysconfig/clock'/> diff --git a/doc/server/plugins/structures/bundler/snmpd.txt b/doc/server/plugins/structures/bundler/snmpd.txt index 2318f8ca1..859e07f7f 100644 --- a/doc/server/plugins/structures/bundler/snmpd.txt +++ b/doc/server/plugins/structures/bundler/snmpd.txt @@ -10,7 +10,7 @@ configuration file. .. code-block:: xml - <Bundle name="snmpd" version="3.0"> + <Bundle> <Package name="snmpd"/> <Service name="snmpd"/> <Path name="/etc/snmp/snmpd.conf"/> diff --git a/doc/server/plugins/structures/bundler/torque.txt b/doc/server/plugins/structures/bundler/torque.txt index 32e6d4c30..f6349df6e 100644 --- a/doc/server/plugins/structures/bundler/torque.txt +++ b/doc/server/plugins/structures/bundler/torque.txt @@ -11,7 +11,7 @@ A longer Bundle that includes many group-specific entries. .. code-block:: xml - <Bundle name='torque' version='1.0'> + <Bundle> <Service name='nfs'/> <Service name='nfslock'/> <BoundPath type='directory' owner='root' group='root' mode='0755' name='/var/spool/torque'/> diff --git a/doc/server/plugins/structures/bundler/yp.txt b/doc/server/plugins/structures/bundler/yp.txt index 6eecb3304..9990fbc2c 100644 --- a/doc/server/plugins/structures/bundler/yp.txt +++ b/doc/server/plugins/structures/bundler/yp.txt @@ -14,7 +14,7 @@ treatment too. .. code-block:: xml - <Bundle name='yp' version='2.0'> + <Bundle> <Package name='yp-tools'/> <Path name='/etc/nsswitch.conf'/> <Path name='/etc/yp.conf'/> diff --git a/doc/server/plugins/version/bzr.txt b/doc/server/plugins/version/bzr.txt index 0755bf80c..ae247985f 100644 --- a/doc/server/plugins/version/bzr.txt +++ b/doc/server/plugins/version/bzr.txt @@ -21,7 +21,7 @@ How to enable the Bazaar plugin Simply add "Bzr" to your plugins line in ``/etc/bcfg2.conf``:: [server] - plugins = Base,Bundler,Cfg,...,Bzr + plugins = Bundler,Cfg,...,Bzr Usage notes =========== diff --git a/doc/server/plugins/version/cvs.txt b/doc/server/plugins/version/cvs.txt index a80b1edbc..f969302d0 100644 --- a/doc/server/plugins/version/cvs.txt +++ b/doc/server/plugins/version/cvs.txt @@ -21,4 +21,4 @@ How to enable the CVS plugin Simply add "Cvs" to your plugins line in ``/etc/bcfg2.conf``:: [server] - plugins = Base,Bundler,Cfg,...,Cvs + plugins = Bundler,Cfg,...,Cvs diff --git a/doc/server/plugins/version/darcs.txt b/doc/server/plugins/version/darcs.txt index 30ac0176a..6fa384679 100644 --- a/doc/server/plugins/version/darcs.txt +++ b/doc/server/plugins/version/darcs.txt @@ -6,7 +6,7 @@ Darcs ===== -This page describes the new Darcs plugin which is experimental. +This page describes the new Darcs plugin which is experimental. Why use the Darcs plugin ======================== @@ -25,4 +25,4 @@ You will need to install Darcs on the Bcfg2 server first. Once installed, simply add Darcs to your plugins line in ``/etc/bcfg2.conf``:: [server] - plugins = Base,Bundler,Cfg,...,Darcs + plugins = Bundler,Cfg,...,Darcs diff --git a/doc/server/plugins/version/fossil.txt b/doc/server/plugins/version/fossil.txt index 7bf523a9e..a19c21760 100644 --- a/doc/server/plugins/version/fossil.txt +++ b/doc/server/plugins/version/fossil.txt @@ -21,4 +21,4 @@ How to enable the Fossil plugin Simply add "Fossil" to your plugins line in ``/etc/bcfg2.conf``:: [server] - plugins = Base,Bundler,Cfg,...,Fossil + plugins = Bundler,Cfg,...,Fossil diff --git a/doc/server/plugins/version/hg.txt b/doc/server/plugins/version/hg.txt index 747699f0e..a11623836 100644 --- a/doc/server/plugins/version/hg.txt +++ b/doc/server/plugins/version/hg.txt @@ -22,4 +22,4 @@ You will need to install Mercurial on the Bcfg2 server first. Simply add Hg to your plugins line in ``/etc/bcfg2.conf``:: [server] - plugins = Base,Bundler,Cfg,...,Hg + plugins = Bundler,Cfg,...,Hg |