diff options
Diffstat (limited to 'doc/server/plugins/generators')
| -rw-r--r-- | doc/server/plugins/generators/account.txt | 115 | ||||
| -rw-r--r-- | doc/server/plugins/generators/cfg.txt | 78 | ||||
| -rw-r--r-- | doc/server/plugins/generators/decisions.txt | 25 | ||||
| -rw-r--r-- | doc/server/plugins/generators/examples/genshi/ganglia.txt | 2 | ||||
| -rw-r--r-- | doc/server/plugins/generators/hostbase.txt | 228 | ||||
| -rw-r--r-- | doc/server/plugins/generators/nagiosgen.txt | 4 | ||||
| -rw-r--r-- | doc/server/plugins/generators/packages.txt | 90 | ||||
| -rw-r--r-- | doc/server/plugins/generators/pkgmgr.txt | 8 | ||||
| -rw-r--r-- | doc/server/plugins/generators/rules.txt | 28 | ||||
| -rw-r--r-- | doc/server/plugins/generators/semodules.txt | 4 | ||||
| -rw-r--r-- | doc/server/plugins/generators/sslca.txt | 2 | ||||
| -rw-r--r-- | doc/server/plugins/generators/tcheetah.txt | 197 | ||||
| -rw-r--r-- | doc/server/plugins/generators/tgenshi.txt | 213 |
13 files changed, 47 insertions, 947 deletions
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 f31923866..4d35a5970 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 @@ -583,72 +581,8 @@ influenced by several options in the ``[sshkeys]`` section of | | group from. | | | +----------------+---------------------------------------------------------+-----------------------+------------+ -Deltas -====== - -.. note:: - - 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. - -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_foo.example.com.cat - -If our machine **isn't** *foo.example.com* then here's what would happen: - -Bcfg2 would choose ``motd.G01_web-server`` as the base file. It is -the most specific base file for this host. Bcfg2 would apply the -``motd.G01_mail-server.cat`` delta to the ``motd.G01_web-server`` -base file. It is the least specific delta. Bcfg2 would then apply the -``motd.G02_file-server.cat`` delta to the result of the delta before -it. If our machine **is** *foo.example.com* then here's what would happen: - -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. +See :ref:`server-encryption` for more details on encryption in Bcfg2 +in general. .. _server-plugins-generators-cfg-validation: 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 ee99b2dc1..137d6abde 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,7 +124,7 @@ 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='nagios-server'> diff --git a/doc/server/plugins/generators/packages.txt b/doc/server/plugins/generators/packages.txt index cdc4f7282..a7cdfad2d 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 2493be53f..a85cd3fc9 100644 --- a/doc/server/plugins/generators/rules.txt +++ b/doc/server/plugins/generators/rules.txt @@ -19,32 +19,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 ======================= 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/sslca.txt b/doc/server/plugins/generators/sslca.txt index 7ef358a31..2a7e3ecad 100644 --- a/doc/server/plugins/generators/sslca.txt +++ b/doc/server/plugins/generators/sslca.txt @@ -280,7 +280,7 @@ Here's a more complete example bcfg2-client bundle: .. code-block:: xml - <Bundle name='bcfg2-client'> + <Bundle> <Path name='/etc/bcfg2.conf'/> <Path name='/etc/cron.d/bcfg2-client'/> <Package name='bcfg2'/> diff --git a/doc/server/plugins/generators/tcheetah.txt b/doc/server/plugins/generators/tcheetah.txt deleted file mode 100644 index ab147ce56..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 TGenshi/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/* |