diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/appendix/guides/authentication.txt | 2 | ||||
-rw-r--r-- | doc/client/tools/vcs.txt | 28 | ||||
-rw-r--r-- | doc/development/compat.txt | 12 | ||||
-rw-r--r-- | doc/man/bcfg2.conf.txt | 7 | ||||
-rw-r--r-- | doc/releases/1.3.6.txt | 11 | ||||
-rw-r--r-- | doc/releases/1.4.0pre2.txt | 15 | ||||
-rw-r--r-- | doc/server/plugins/connectors/templatehelper.txt | 6 | ||||
-rw-r--r-- | doc/server/plugins/generators/cfg.txt | 4 | ||||
-rw-r--r-- | doc/server/plugins/generators/nagiosgen.txt | 1 | ||||
-rw-r--r-- | doc/server/plugins/generators/rules.txt | 25 | ||||
-rw-r--r-- | doc/server/plugins/grouping/ldap.txt | 185 | ||||
-rw-r--r-- | doc/server/plugins/structures/defaults.txt | 7 |
12 files changed, 202 insertions, 101 deletions
diff --git a/doc/appendix/guides/authentication.txt b/doc/appendix/guides/authentication.txt index 93a34c9bc..eba01ee3c 100644 --- a/doc/appendix/guides/authentication.txt +++ b/doc/appendix/guides/authentication.txt @@ -145,7 +145,7 @@ Allowed values are: +-------------------+------------------------------------------+ ``cert+password`` is the default. This can be changed by setting the -``authentication`` parameter in the ``[communcation]`` section of +``authentication`` parameter in the ``[communication]`` section of ``bcfg2.conf``. For instance, to set ``bootstrap`` mode as the global default, you would add the following to ``bcfg2.conf``:: diff --git a/doc/client/tools/vcs.txt b/doc/client/tools/vcs.txt index fb9c33684..f21d097ff 100644 --- a/doc/client/tools/vcs.txt +++ b/doc/client/tools/vcs.txt @@ -8,8 +8,34 @@ VCS Client Tool .. warning: This tool is currently under development. -.. note: Currently, the only supported VCS is git. +.. note: Currently, the only supported VCS is git and svn. The VCS tool allows you to checkout particular revisions from a VCS repository on the client to a specified path. The tool requires the appropriate python libraries for the VCS used to be installed. + +See :ref:`server-plugins-generators-rules-vcs` for possible options. + +Example usage: + +You may want to create a `Rules/paths.xml` with the following: + +.. code-block:: xml + + <Rules priority="1"> + <Path name="/srv/bcfg2" type="vcs" + sourceurl="https://github.com/Bcfg2/bcfg2.git" + vcstype="git" + revision="cf6dfd8ca28e941b1e638ff0fa7e7a0a1ebb6a6f"/> + </Rules> + +Once the rule is created a client can reference the path from a +bundle, this path will then be populated from the repository. To +continue the above example, a file `Bundle/bcfg2.xml` might contain +this: + +.. code-block:: xml + + <Bundle name="bcfg"> + <Path name="/srv/bcfg2"> + <Bundle/> diff --git a/doc/development/compat.txt b/doc/development/compat.txt index 8700c46d3..132bf67c0 100644 --- a/doc/development/compat.txt +++ b/doc/development/compat.txt @@ -113,7 +113,7 @@ with Python 2.4 (and occasionally 2.5). Be sure to read the notes below, since some of these implementations may be feature-incomplete. +----------------+--------------------------------+--------------------------------------------+ -| Name | Python 2.4 | Python 2.4+ | +| Name | Python 2.4 | Python 2.5+ | +================+================================+============================================+ | formatdate | :func:`email.Utils.formatdate` | :func:`email.utils.formatdate` | +----------------+--------------------------------+--------------------------------------------+ @@ -129,6 +129,8 @@ below, since some of these implementations may be feature-incomplete. +----------------+--------------------------------+--------------------------------------------+ | MutableMapping | :class:`UserDict.DictMixin` | :class:`collections.MutableMapping` (2.6+) | +----------------+--------------------------------+--------------------------------------------+ +| literal_eval | :func:`eval` | :func:`ast.literal_eval`(2.6+) | ++----------------+--------------------------------+--------------------------------------------+ walk_packages ~~~~~~~~~~~~~ @@ -171,6 +173,14 @@ mind. :class:`collections.MutableMapping` is available in Python 2.6+, and will be used if available. +literal_eval +~~~~~~~~~~~~ + +:func:`ast.literal_eval` is a safe version of :func:`eval` that will only +allow delaration of literal strings, ints, list, dicts, etc. This was +introduced in Python 2.6, and as such Python 2.4 uses the plain-old +:func:`eval`. + Other Symbols ------------- diff --git a/doc/man/bcfg2.conf.txt b/doc/man/bcfg2.conf.txt index 62c4ac1a8..6c801ff1e 100644 --- a/doc/man/bcfg2.conf.txt +++ b/doc/man/bcfg2.conf.txt @@ -267,7 +267,7 @@ revision information out of your repository for reporting purposes. Ldap Plugin +++++++++++ -The Ldap plugin makes it possible to fetch data from an LDAP directory, +The Ldap plugin makes it possible to fetch data from a LDAP directory, process it and attach it to your metadata. Metadata Plugin @@ -718,6 +718,11 @@ Reporting options Maximum number of children for the reporting collector. Use 0 to disable the limit. (default is 0) + django_settings + Arbitrary options for the Django installation. The value expected + is a literal python dictionary, that is merged with the already set + django settings. + See Also -------- diff --git a/doc/releases/1.3.6.txt b/doc/releases/1.3.6.txt index 757fbf6f5..9ab024674 100644 --- a/doc/releases/1.3.6.txt +++ b/doc/releases/1.3.6.txt @@ -30,5 +30,14 @@ This is primarily a bugfix release. https://docs.djangoproject.com/en/1.7/ref/settings/#std:setting-OPTIONS +* SYSV: change instances of simplename to simplefile + + Previous configurations can be updated using the migration tool. + +* Authentication: Reject passwd auth, if authentication is set to "cert" +* Server/Core: drop privileges even if not running as daemon +* Packages/Yum.py: Fix dependency resolution logic +* Handle filesystem secontexts properly for contextless filesystems + Special thanks to the following contributors for this release: Michael -Fenn, Matt Kemp, Alexander Sulfrian, Jonathan Billings. +Fenn, Matt Kemp, Alexander Sulfrian, Jonathan Billings, Ross Smith. diff --git a/doc/releases/1.4.0pre2.txt b/doc/releases/1.4.0pre2.txt index a5c10777a..1ed2ae70f 100644 --- a/doc/releases/1.4.0pre2.txt +++ b/doc/releases/1.4.0pre2.txt @@ -19,6 +19,7 @@ environments. * NagiosGen: Add bundles to configuration * HomeBrew: Initial add of plugin +* Rules/Defaults: Add possibility to use name of entry in attributes backwards-incompatible user-facing changes ------------------------------------------ @@ -31,6 +32,20 @@ backwards-incompatible user-facing changes This fixes potentially long client runs when comparing files that have diverged significantly. +* The database options in the config (options and reporting_options in database + section) now have to be literal python dictionaries. + + This allows to set arbitrary options with nested settings. + +* The Ldap plugin changed significantly. The configuration interface was + simplified and new configuration options for the number of retries and the + delay in between were added. + + You have to register your ldap queries in the global list, there is no + distinction between LdapQueries and LdapSubQueries anymore, the names of + your queries default to the class names and the Ldap plugin expires + the metadata caches if the config file changes. + Thanks ------ diff --git a/doc/server/plugins/connectors/templatehelper.txt b/doc/server/plugins/connectors/templatehelper.txt index d113dcab7..e24ba10cb 100644 --- a/doc/server/plugins/connectors/templatehelper.txt +++ b/doc/server/plugins/connectors/templatehelper.txt @@ -54,9 +54,9 @@ See ``examples/TemplateHelper`` for examples of helper modules. Usage ===== -Specific helpers can be referred to in -templates as ``metadata.TemplateHelper[<modulename>]``. That accesses -a HelperModule object will have, as attributes, all symbols listed in +Specific helpers can be referred to in templates as +``metadata.TemplateHelper[<modulename>]``. That returns a HelperModule +object which will have, as attributes, all symbols listed in ``__export__``. For example, consider this helper module:: __export__ = ["hello"] diff --git a/doc/server/plugins/generators/cfg.txt b/doc/server/plugins/generators/cfg.txt index c991f20c9..7e7a7c72e 100644 --- a/doc/server/plugins/generators/cfg.txt +++ b/doc/server/plugins/generators/cfg.txt @@ -275,9 +275,7 @@ Several variables are pre-defined inside templates: | | <server-plugins-grouping-metadata-clientmetadata>` | +-------------+--------------------------------------------------------+ | name | The value of the ``name`` attribute as specified in | -| | the Path entry in Bcfg2. If an :ref:`altsrc | -| | <server-plugins-structures-altsrc>` attribute is used, | -| | then ``name`` will be the value of that attribute. | +| | the Path entry in Bcfg2. | +-------------+--------------------------------------------------------+ | source_path | The path to the template file on the filesystem | +-------------+--------------------------------------------------------+ diff --git a/doc/server/plugins/generators/nagiosgen.txt b/doc/server/plugins/generators/nagiosgen.txt index 1ccdd66c1..746adf44c 100644 --- a/doc/server/plugins/generators/nagiosgen.txt +++ b/doc/server/plugins/generators/nagiosgen.txt @@ -29,7 +29,6 @@ Create default host, and group specs in: check_period 24x7 contact_groups admins event_handler_enabled 1 - failure_prediction_enabled 1 flap_detection_enabled 1 initial_state o max_check_attempts 10 diff --git a/doc/server/plugins/generators/rules.txt b/doc/server/plugins/generators/rules.txt index 86478a5ae..7aeec6990 100644 --- a/doc/server/plugins/generators/rules.txt +++ b/doc/server/plugins/generators/rules.txt @@ -248,10 +248,13 @@ Manage symlinks. :onlyattrs: to :requiredattrs: to +.. _server-plugins-generators-rules-vcs: + vcs ^^^ -Check out the specified VCS repository to the given path. +Check out the specified VCS repository to the given path. See +:ref:`client-tools-vcs` for more details. .. xml:type:: PathType :nochildren: @@ -509,3 +512,23 @@ you'd have to explicitly specify ``<Service name="bcfg2.*".../>``. Note that only one Rule can apply to any abstract entry, so you cannot specify multiple regexes to match the same rule. + +Replacing the name of the Entry in Attributes +============================================= + +If you are using regular expressions to match the abstract configuration +entries, you may need the concrete name of the entry in some attributes. +To use this feature, you have to enable it. It is only useful, if used +together with regex matching. :: + + [rules] + regex = yes + replace_name = yes + +You now can write something like that in your xml file: + +.. code-block:: xml + + <POSIXUser name='.*' home='/somewhere/%{name}'/> + +``%{name}`` will be correctly replaced with the username for each POSIXUser. diff --git a/doc/server/plugins/grouping/ldap.txt b/doc/server/plugins/grouping/ldap.txt index 90590a272..96e224761 100644 --- a/doc/server/plugins/grouping/ldap.txt +++ b/doc/server/plugins/grouping/ldap.txt @@ -33,39 +33,38 @@ next section. Configuration ------------- -As processing LDAP search results can get pretty complex, the configuration has +As processing LDAP search results can get pretty complex, the configuration has to be written in Python. Here is a minimal example to get you started:: - from Bcfg2.Server.Plugins.Ldap import LdapConnection, LdapQuery, LdapSubQuery, register_query - - conn_default = LdapConnection() - conn_default.binddn = "uid=example,ou=People,dc=example,dc=com" - conn_default.bindpw = "foobat" - - @register_query + from Bcfg2.Server.Plugins.Ldap import LdapConnection, LdapQuery + + __queries__ = ['ExampleQuery'] + + conn_default = LdapConnection( + binddn="uid=example,ou=People,dc=example,dc=com", + bindpw = "foobat") + class ExampleQuery(LdapQuery): - name = "example" base = "ou=People,dc=example,dc=com" scope = "one" attrs = ["cn", "uid"] connection = conn_default - + def prepare_query(self, metadata): self.filter = "(personalServer=" + metadata.hostname + ")" - + def process_result(self, metadata): if not self.result: admin_uid = None admin_name = "This server has no admin." - return { + return { "admin_uid" : self.result[0][1]["uid"], "admin_name" : self.result[0][1]["cn"] } -The first line provides three classes for dealing with connections and queries -(details below) and a decorator function for registering your queries with the plugin. +The first line provides the two required classes for dealing with connections and queries. In this example our LDAP directory has a number of user objects in it. Each of those may have a personal server they administer. Whenever metadata for this machine is being @@ -73,7 +72,20 @@ generated by the Bcfg2 server, the UID and name of the admin are retrieved from In your bundles and config templates, you can access this data via the metadata object:: - ${metadata.Ldap["example"]["admin_name"]} + ${metadata.Ldap["ExampleQuery"]["admin_name"]} + +Connection retry +++++++++++++++++ + +If the LDAP server is down during a request, the LDAP plugin tries to reconnect after a +short delay. By default, it waits 3 seconds during the retries and tries to reconnect +up to three times. + +If you wish, you could customize these values in your ``bcfg2.conf``:: + + [ldap] + retries = 3 + retry_delay = 3.0 Class reference --------------- @@ -83,23 +95,23 @@ LdapConnection .. class:: LdapConnection - This class represents an LDAP connection. Every query must be associated with exactly + This class represents an LDAP connection. Every query must be associated with exactly one connection. - -.. attribute:: LdapConnection.binddn - + +.. attribute:: LdapConnection.binddn + DN used to authenticate against LDAP (required). - + .. attribute:: LdapConnection.bindpw - + Password for the previously mentioned **binddn** (required). - + .. attribute:: LdapConnection.host - + Hostname of host running the LDAP server (defaults to "localhost"). .. attribute:: LdapConnection.port - + Port where LDAP server is listening (defaults to 389). You may pass any of these attributes as keyword arguments when creating the connection object. @@ -108,143 +120,140 @@ LdapQuery +++++++++ .. class:: LdapQuery - + This class defines a single query that may adapt itself depending on the current metadata. .. attribute:: LdapQuery.attrs - + Can be used to retrieve only a certain subset of attributes. May either be a list of strings (attribute names) or ``None``, meaning all attributes (defaults to ``None``). .. attribute:: LdapQuery.base - - This is the search base. Only LDAP entries below this DN will be included in your + + This is the search base. Only LDAP entries below this DN will be included in your search results (required). - + .. attribute:: LdapQuery.connection - + Set this to an instance of the LdapConnection class (required). .. attribute:: LdapQuery.filter - + LDAP search filter used to narrow down search results (defaults to ``(objectClass=*)``). .. attribute:: LdapQuery.name - + This will be used as the dictionary key that provides access to the query results from - the metadata object (``metadata.Ldap["NAMEGOESHERE"]``) (required). + the metadata object: ``metadata.Ldap["NAMEGOESHERE"]`` (defaults to the class name). .. attribute:: LdapQuery.scope - - Set this to one of "base", "one" or "sub" to specify LDAP search depth (defaults to "sub"). + + Set this to one of "base", "one" or "sub" to specify LDAP search depth (defaults to "sub"). .. method:: LdapQuery.is_applicable(self, metadata) - + You can override this method to indicate whether this query makes sense for a given set of metadata (e.g. you need a query only for a certain bundle or group). - + (defaults to returning True) - -.. method:: LdapQuery.prepare_query(self, metadata) - + +.. method:: LdapQuery.prepare_query(self, metadata, \**kwargs) + Override this method to alter the query prior to execution. This is useful if your filter depends on the current metadata, e.g.:: - + self.filter = "(cn=" + metadata.hostname + ")" - + (defaults to doing nothing) -.. method:: LdapQuery.process_result(self, metadata) - +.. method:: LdapQuery.process_result(self, metadata, \**kwargs) + You will probably override this method in every query to reformat the results from LDAP. The raw result is stored in ``self.result``, you must return the altered data. Note that LDAP search results are presented in this structure:: - + ( ("DN of first entry returned", { "firstAttribute" : 1, "secondAttribute" : 2, - } + } ), ("DN of second entry returned", { "firstAttribute" : 1, "secondAttribute" : 2, - } + } ), ) - + Therefore, to return just the value of the firstAttribute of the second object returned, you'd write:: - + return self.result[1][1][0] - + (defaults to returning ``self.result`` unaltered) -LdapSubQuery -++++++++++++ - -.. class:: LdapSubQuery - - Sometimes you need more than one query to obtain the data you need (e.g. use the first - query to return all websites running on metadata.hostname and another query to find all - customers that should have access to those sites). - - LdapSubQueries are the same as LdapQueries, except for that the methods - - * ``get_result()`` - * ``prepare_query()`` - * ``process_result()`` - - allow any additional keyword arguments that may contain additional data as needed. Note - that ``get_result()`` will call ``prepare_query()`` and ``process_result()`` for you, - so you shouldn't ever need to invoke these yourself, just override them. - -Here is another example that uses LdapSubQuery:: - - class WebSitesQuery(LdapSubQuery): - name = "web_sites" +.. method:: LdapQuery.get_result(self, metadata, \**kwargs) + + This executes the query. First it will call ``prepare_query() for you, then it will try + to execute the query with the specified connection and last it will call ``process_result()`` + and return that return value. + +If you use a LdapQuery class by yourself, you could pass additional keyword arguments to +``get_result()``. It will call ``prepare_query()`` and ``process_result()`` for you and +also supply this additional arguments to this methods. + +Here is an example:: + + __queries__ = ['WebPackageQuery'] + + class WebSitesQuery(LdapQuery): filter = "(objectClass=webHostingSite)" attrs = ["dc"] connection = conn_default - + def prepare_query(self, metadata, base_dn): self.base = base_dn - - def process_result(self, metadata): + + def process_result(self, metadata, **kwargs): [...] # build sites dict from returned dc attributes return sites - - @register_query + class WebPackagesQuery(LdapQuery): - name = "web_packages" base = "dc=example,dc=com" attrs = ["customerId"] connection = conn_default - + def prepare_query(self, metadata): self.filter = "(&(objectClass=webHostingPackage)(cn:dn:=" + metadata.hostname + "))" - + def process_result(self, metadata): customers = {} for customer in self.result: dn = customer[0] cid = customer[1]["customerId"][0] - customers[cid]["sites"] = WebSitesQuery().get_result(metadata, base_dn = dn) + customers[cid]["sites"] = WebSitesQuery().get_result(metadata, base_dn=dn) return customers This example assumes that we have a number of webhosting packages that contain various -sites. We need a first query ("web_packages") to get a list of the packages our customers -have and another query for each of those to find out what sites are contained in each -package. The magic happens in the second class where ``WebSitesQuery.get_result()`` is -called with the additional ``base_dn`` parameter that allows our LdapSubQuery to only +sites. We need the ``WebPackagesQuery`` to get a list of the packages our customers +have and another query for each of those to find out what sites are contained in each +package. The magic happens in the second class where ``WebSitesQuery.get_result()`` is +called with the additional ``base_dn`` parameter that allows our LdapQuery to only search below that DN. -.. warning:: - Do NOT apply the ``register_query`` decorator to LdapSubQueries. +You do not need to add all LdapQueries to the ``__queries__`` list. Only add those to +that list, that should be called automatically and whose results should be added to the +client metadata. Known Issues ------------ * At this point there is no support for SSL/TLS. +* This module could not know, if a value changed on the LDAP server. So it could not + expire the client metadata cache sanely. + If you are using aggressive caching mode, this plugin will expire the metadata cache + for a single client at the start of a client run. If you are using LDAP data from + another client in a template, you will probably get the cached values from the last + client run of that other client. diff --git a/doc/server/plugins/structures/defaults.txt b/doc/server/plugins/structures/defaults.txt index 58b9feddb..9d37b8e64 100644 --- a/doc/server/plugins/structures/defaults.txt +++ b/doc/server/plugins/structures/defaults.txt @@ -29,3 +29,10 @@ on Fedora 15 and the ``chkconfig`` tool on Fedora 14, you could do:: If you were to specify a ``type`` attribute for a Service entry in Rules (or a ``type`` attribute for a BoundService entry in Bundler), that would take precendence over the default. + +Like :ref:`server-plugins-generators-rules`, Defaults can also replace +``%{name}`` in attributes with the real name of the entry. To enable this, +add the following setting to ``bcfg2.conf``:: + + [defaults] + replace_name = yes |