Bcfg2 Plugin development¶

While the Bcfg2 server provides a good interface for representing general system configurations, its plugin interface offers the ability to implement configuration interfaces and representation tailored to problems encountered by a particular site. This chapter describes what plugins are good for, what they can do, and how to implement them.

Several plugins themselves have pluggable backends, and for narrow cases you may want to develop a backend for an existing plugin rather than an entirely new plugin. See the following pages for more information:

Bcfg2 Plugins¶

Bcfg2 plugins are loadable python modules that the Bcfg2 server loads at initialization time. These plugins can contribute to the functions already offered by the Bcfg2 server or can extend its functionality. In general, plugins will provide some portion of the configuration for clients, with a data representation that is tuned for a set of common tasks. Much of the core functionality of Bcfg2 is implemented by several plugins, however, they are not special in any way; new plugins could easily supplant one or all of them.

Bcfg2.Server.Plugin contains server plugin base classes, interfaces, exceptions, and helper objects. This module is split into a number of submodules to make it more manageable, but it imports all symbols from the submodules, so with the exception of some documentation it’s not necessary to use the submodules. E.g., you can (and should) do:

from Bcfg2.Server.Plugin import Plugin

...rather than:

from Bcfg2.Server.Plugin.base import Plugin

Server Plugin Types¶

A plugin must implement at least one of the interfaces described below. Each interface is available as a class in Bcfg2.Server.Plugin. In most cases, a plugin must also inherit from Bcfg2.Server.Plugin.base.Plugin, which is the base Plugin object (described below). Some of the interfaces listed below are themselves Plugin objects, so your custom plugin would only need to inherit from the plugin type.

Plugin¶

class Bcfg2.Server.Plugin.base.Plugin(core)[source]¶

Bases: Bcfg2.Logger.Debuggable

The base class for all Bcfg2 Server plugins.

Parameters:	core (Bcfg2.Server.Core) – The Bcfg2.Server.Core initializing the plugin
Raises :	`OSError` if adding a file monitor failed; `Bcfg2.Server.Plugin.exceptions.PluginInitError` on other errors

Debuggable.__rmi__ = ['toggle_debug', 'set_debug']¶: List of names of methods to be exposed as XML-RPC functions, if applicable to the child class

conflicts = []¶: Plugin conflicts with the list of other plugin names

create = True¶: Whether or not to automatically create a data directory for this plugin

debug_log(message, flag=None)¶

Log a message at the debug level.

Parameters:	message (string) – The message to log flag (bool) – Override the current debug flag with this value
Returns:	None

deprecated = False¶: Plugin is deprecated and will be removed in a future release. Use of this plugin will produce a log message alerting the administrator that an experimental plugin is in use.

experimental = False¶: Plugin is experimental. Use of this plugin will produce a log message alerting the administrator that an experimental plugin is in use.

classmethod init_repo(repo)[source]¶

Perform any tasks necessary to create an initial Bcfg2 repository.

Parameters:	repo (string) – The path to the Bcfg2 repository on the filesystem
Returns:	None

name = 'Plugin'¶: The name of the plugin.

shutdown()[source]¶

Perform shutdown tasks for the plugin

Returns:	None

sort_order = 500¶: Plugins of the same type are processed in order of ascending sort_order value. Plugins with the same sort_order are sorted alphabetically by their name.

toggle_debug()¶

Turn debugging output on or off.

Returns:	bool - The new value of the debug flag

With the exceptions of Bcfg2.Server.Plugin.interfaces.Statistics and Bcfg2.Server.Plugin.interfaces.ThreadedStatistics, the plugin interfaces listed below do not inherit from Plugin; they simply provide interfaces that a given plugin may or must implement.

Interfaces¶

class Bcfg2.Server.Plugin.interfaces¶

Interface definitions for Bcfg2 server plugins

class Bcfg2.Server.Plugin.interfaces.ClientACLs[source]¶

Bases: object

ClientACLs are used to grant or deny access to different XML-RPC calls based on client IP or metadata.

check_acl_ip(address, rmi)[source]¶

Check if the given IP address is authorized to make the named XML-RPC call.

Parameters:	address (tuple of (<ip address>, <port>)) – The address pair of the client to check ACLs for rmi – The fully-qualified name of the RPC call rmi – string
Returns:	bool or None - True to allow, False to deny, None to defer to metadata ACLs

check_acl_metadata(metadata, rmi)[source]¶

Check if the given client is authorized to make the named XML-RPC call.

Parameters:	metadata (Bcfg2.Server.Plugins.Metadata.ClientMetadata) – The client metadata rmi – The fully-qualified name of the RPC call rmi – string
Returns:	bool

class Bcfg2.Server.Plugin.interfaces.ClientRunHooks[source]¶

Bases: object

ClientRunHooks can hook into various parts of a client run to perform actions at various times without needing to pretend to be a different plugin type.

end_client_run(metadata)[source]¶

Invoked at the end of a client run, immediately after GoalValidator plugins have been run and just before the configuration is returned to the client.

Parameters:	metadata (Bcfg2.Server.Plugins.Metadata.ClientMetadata) – The client metadata object
Returns:	None

end_statistics(metadata)[source]¶

Invoked after statistics are processed for a client.

Parameters:	metadata (Bcfg2.Server.Plugins.Metadata.ClientMetadata) – The client metadata object
Returns:	None

start_client_run(metadata)[source]¶

Invoked at the start of a client run, after all probe data has been received and decision lists have been queried (if applicable), but before the configuration is generated.

Parameters:	metadata (Bcfg2.Server.Plugins.Metadata.ClientMetadata) – The client metadata object
Returns:	None

class Bcfg2.Server.Plugin.interfaces.Connector[source]¶

Bases: object

Connector plugins augment client metadata instances with additional data, additional groups, or both.

get_additional_data(metadata)[source]¶

Return arbitrary additional data for the given ClientMetadata object. By convention this is usually a dict object, but doesn’t need to be.

Parameters:	metadata (Bcfg2.Server.Plugins.Metadata.ClientMetadata) – The client metadata
Returns:	dict

get_additional_groups(metadata)[source]¶

Return a list of additional groups for the given client. Each group can be either the name of a group (a string), or a Bcfg2.Server.Plugins.Metadata.MetadataGroup object that defines other data besides just the name. Note that you cannot return a Bcfg2.Server.Plugins.Metadata.MetadataGroup object that clobbers a group defined by another plugin; the original group will be used instead. For instance, assume the following in Metadata/groups.xml:

<Groups>
  ...
  <Group name="foo" public="false"/>
</Groups>

You could not subsequently return a Bcfg2.Server.Plugins.Metadata.MetadataGroup object with public=True; a warning would be issued, and the original (non-public) foo group would be used.

Parameters:	metadata (Bcfg2.Server.Plugins.Metadata.ClientMetadata) – The client metadata
Returns:	list of strings or `Bcfg2.Server.Plugins.Metadata.MetadataGroup` objects.

class Bcfg2.Server.Plugin.interfaces.Decision[source]¶

Bases: object

Decision plugins produce decision lists for affecting which entries are actually installed on clients.

GetDecisions(metadata, mode)[source]¶

Return a list of tuples of (<entry type>, <entry name>) to be used as the decision list for the given client in the specified mode.

Parameters:	metadata (Bcfg2.Server.Plugins.Metadata.ClientMetadata) – The client metadata mode (string) – The decision mode (“whitelist” or “blacklist”)
Returns:	list of tuples

class Bcfg2.Server.Plugin.interfaces.Generator[source]¶

Bases: object

Generator plugins contribute to literal client configurations. That is, they generate entry contents.

An entry is generated in one of two ways:

The Bcfg2 core looks in the Entries dict attribute of the plugin object. Entries is expected to be a dict whose keys are entry tags (e.g., "Path", "Service", etc.) and whose values are dicts; those dicts should map the name attribute of an entry to a callable that will be called to generate the content. The callable will receive two arguments: the abstract entry (as an lxml.etree._Element object), and the client metadata object the entry is being generated for.
If the entry is not listed in Entries, the Bcfg2 core calls HandlesEntry(); if that returns True, then it calls HandleEntry().

HandleEntry(entry, metadata)[source]¶

HandleEntry is the slow path method for binding configuration binding requests. It is called if the Entries dict does not contain a method for binding the entry, and HandlesEntry() returns True.

Parameters:	entry (lxml.etree._Element) – The entry to bind metadata (Bcfg2.Server.Plugins.Metadata.ClientMetadata) – The client metadata
Returns:	lxml.etree._Element - The fully bound entry
Raises :	`Bcfg2.Server.Plugin.exceptions.PluginExecutionError`

HandlesEntry(entry, metadata)[source]¶

HandlesEntry is the slow path method for routing configuration binding requests. It is called if the Entries dict does not contain a method for binding the entry.

Parameters:	entry (lxml.etree._Element) – The entry to bind metadata (Bcfg2.Server.Plugins.Metadata.ClientMetadata) – The client metadata
Returns:	bool - Whether or not this plugin can handle the entry
Raises :	`Bcfg2.Server.Plugin.exceptions.PluginExecutionError`

class Bcfg2.Server.Plugin.interfaces.GoalValidator[source]¶

Bases: object

GoalValidator plugins can modify the concretely-bound configuration of a client as a last stage before the configuration is sent to the client.

validate_goals(metadata, config)[source]¶

Given a monolithic XML document of the full configuration, modify the document in-place.

Parameters:	metadata (Bcfg2.Server.Plugins.Metadata.ClientMetadata) – The client metadata config (lxml.etree._Element) – The full configuration for the client
Returns:	None
Raises :	`Bcfg2.Server.Plugin.exceptions:ValidationError`

class Bcfg2.Server.Plugin.interfaces.Metadata[source]¶

Bases: object

Metadata plugins handle initial metadata construction, accumulating data from Connector plugins, and producing Bcfg2.Server.Plugins.Metadata.ClientMetadata objects.

AuthenticateConnection(cert, user, password, address)[source]¶

Authenticate the given client.

Parameters:	cert (dict) – an x509 certificate user (string) – The username of the user trying to authenticate password (string) – The password supplied by the client addresspair (tuple) – An address pair of `(<ip address>, <hostname>)`
Returns:	bool - True if the authenticate succeeds, False otherwise

get_initial_metadata(client_name)[source]¶

Return a Bcfg2.Server.Plugins.Metadata.ClientMetadata object that fully describes everything the Metadata plugin knows about the named client.

Parameters:	client_name (string) – The hostname of the client
Returns:	Bcfg2.Server.Plugins.Metadata.ClientMetadata

merge_additional_data(imd, source, data)[source]¶

Add arbitrary data from a Connector plugin to the given metadata object.

Parameters:	imd (Bcfg2.Server.Plugins.Metadata.ClientMetadata) – An initial metadata object source (string) – The name of the plugin providing this data data (any) – The data to add
Returns:	None

merge_additional_groups(imd, groups)[source]¶

Add groups from a Connector plugin to the given metadata object.

Parameters:	imd (Bcfg2.Server.Plugins.Metadata.ClientMetadata) – An initial metadata object groups (list of strings) – The groups to add
Returns:	None

resolve_client(address, cleanup_cache=False)[source]¶

Resolve the canonical name of this client. If this method is not implemented, the hostname claimed by the client is used. (This may be a security risk; it’s highly recommended that you implement resolve_client if you are writing a Metadata plugin.)

Parameters:	address (tuple) – Address pair of `(<ip address>, <hostname>)` cleanup_cache (bool) – Whether or not to remove expire the entire client hostname resolution class
Returns:	string - canonical client hostname
Raises :	`Bcfg2.Server.Plugin.exceptions.MetadataRuntimeError`, `Bcfg2.Server.Plugin.exceptions.MetadataConsistencyError`

set_profile(client, profile, address)[source]¶

Set the profile for the named client to the named profile group.

Parameters:	client (string) – Hostname of the client profile (string) – Name of the profile group address (tuple) – Address pair of `(<ip address>, <hostname>)`
Returns:	None
Raises :	`Bcfg2.Server.Plugin.exceptions.MetadataRuntimeError`, `Bcfg2.Server.Plugin.exceptions.MetadataConsistencyError`

set_version(client, version)[source]¶

Set the version for the named client to the specified version string.

Parameters:	client (string) – Hostname of the client profile (string) – Client Bcfg2 version
Returns:	None
Raises :	`Bcfg2.Server.Plugin.exceptions.MetadataRuntimeError`, `Bcfg2.Server.Plugin.exceptions.MetadataConsistencyError`

update_client_list()[source]¶: Re-read the cached list of clients

viz(hosts, bundles, key, only_client, colors)[source]¶

Return a string containing a graphviz document that maps out the Metadata for bcfg2-admin viz

Parameters:	hosts (bool) – Include hosts in the graph bundles (bool) – Include bundles in the graph key (bool) – Include a key in the graph only_client (string) – Only include data for the specified client colors (list of strings) – Use the specified graphviz colors
Returns:	string

class Bcfg2.Server.Plugin.interfaces.Probing[source]¶

Bases: object

Probing plugins can collect data from clients and process it.

GetProbes(metadata)[source]¶

Return a list of probes for the given client. Each probe should be an lxml.etree._Element object that adheres to the following specification. Each probe must the following attributes:

name: The unique name of the probe.
source: The origin of the probe; probably the name of the plugin that supplies the probe.
interpreter: The command that will be run on the client to interpret the probe script. Compiled (i.e., non-interpreted) probes are not supported.

The text of the XML tag should be the contents of the probe, i.e., the code that will be run on the client.

Parameters:	metadata (Bcfg2.Server.Plugins.Metadata.ClientMetadata) – The client metadata
Returns:	list of lxml.etree._Element objects

ReceiveData(metadata, datalist)[source]¶

Process data returned from the probes for the given client. datalist is a list of lxml.etree._Element objects, each of which is a single tag; the name attribute holds the unique name of the probe that was run, and the text contents of the tag hold the results of the probe.

Parameters:	metadata (Bcfg2.Server.Plugins.Metadata.ClientMetadata) – The client metadata datalist (list of lxml.etree._Element objects) – The probe data
Returns:	None

class Bcfg2.Server.Plugin.interfaces.Statistics(core)[source]¶

Bases: Bcfg2.Server.Plugin.base.Plugin

Statistics plugins handle statistics for clients. In general, you should avoid using Statistics and use ThreadedStatistics instead.

Parameters:	core (Bcfg2.Server.Core) – The Bcfg2.Server.Core initializing the plugin
Raises :	`OSError` if adding a file monitor failed; `Bcfg2.Server.Plugin.exceptions.PluginInitError` on other errors

Debuggable.__rmi__ = ['toggle_debug', 'set_debug']¶: List of names of methods to be exposed as XML-RPC functions, if applicable to the child class

process_statistics(client, xdata)[source]¶

Process the given XML statistics data for the specified client.

Parameters:	metadata (Bcfg2.Server.Plugins.Metadata.ClientMetadata) – The client metadata data (lxml.etree._Element) – The statistics data
Returns:	None

class Bcfg2.Server.Plugin.interfaces.Structure[source]¶

Bases: object

Structure Plugins contribute to abstract client configurations. That is, they produce lists of entries that will be generated for a client.

BuildStructures(metadata)[source]¶

Build a list of lxml.etree._Element objects that will be added to the top-level <Configuration> tag of the client configuration. Consequently, each object in the list returned by BuildStructures() must consist of a container tag (e.g., <Bundle> or <Independent>) which contains the entry tags. It must not return a list of entry tags.

Parameters:	metadata (Bcfg2.Server.Plugins.Metadata.ClientMetadata) – The client metadata
Returns:	list of lxml.etree._Element objects

class Bcfg2.Server.Plugin.interfaces.StructureValidator[source]¶

Bases: object

StructureValidator plugins can modify the list of structures after it has been created but before the entries have been concretely bound.

validate_structures(metadata, structures)[source]¶

Given a list of structures (i.e., of tags that contain entry tags), modify that list or the structures in it in-place.

Parameters:	metadata (Bcfg2.Server.Plugins.Metadata.ClientMetadata) – The client metadata config (list of lxml.etree._Element) – A list of lxml.etree._Element objects describing the structures (i.e., bundles) for this client. This can be modified in place.
Returns:	None
Raises :	`Bcfg2.Server.Plugin.exceptions.ValidationError`

class Bcfg2.Server.Plugin.interfaces.TemplateDataProvider[source]¶

Bases: object

TemplateDataProvider plugins provide variables to templates for use in rendering.

get_template_data(entry, metadata, template)[source]¶: Get a dict of variables that will be supplied to a Cfg template for rendering

get_xml_template_data(structfile, metadata)[source]¶: Get a dict of variables that will be supplied to an XML template (e.g., a bundle) for rendering

class Bcfg2.Server.Plugin.interfaces.Threaded[source]¶

Bases: object

Threaded plugins use threads in any way. The thread must be started after daemonization, so this class implements a single method, start_threads(), that can be used to start threads after daemonization of the server core.

start_threads()[source]¶

Start this plugin’s threads after daemonization.

Returns:	None
Raises :	`Bcfg2.Server.Plugin.exceptions.PluginInitError`

class Bcfg2.Server.Plugin.interfaces.ThreadedStatistics(core)[source]¶

Bases: Bcfg2.Server.Plugin.interfaces.Statistics, Bcfg2.Server.Plugin.interfaces.Threaded, threading.Thread

ThreadedStatistics plugins process client statistics in a separate thread.

handle_statistic(metadata, data)[source]¶

Process the given XML statistics data for the specified client object. This differs from the Statistics.process_statistics() method only in that ThreadedStatistics first adds the data to a queue, and then processes them in a separate thread.

Parameters:	metadata (Bcfg2.Server.Plugins.Metadata.ClientMetadata) – The client metadata data (lxml.etree._Element) – The statistics data
Returns:	None

class Bcfg2.Server.Plugin.interfaces.Version(core)[source]¶

Bases: Bcfg2.Server.Plugin.base.Plugin

Version plugins interact with various version control systems.

param core: The Bcfg2.Server.Core initializing the plugin

type core: Bcfg2.Server.Core

raises: OSError if adding a file monitor failed; Bcfg2.Server.Plugin.exceptions.PluginInitError on other errors

Debuggable.__rmi__ = ['toggle_debug', 'set_debug']¶

List of names of methods to be exposed as XML-RPC functions, if applicable to the child class

__vcs_metadata_path__ = None¶: The path to the VCS metadata file or directory, relative to the base of the Bcfg2 repository. E.g., for Subversion this would be ”.svn”

get_revision()[source]¶

Return the current revision of the Bcfg2 specification. This will be included in the revision attribute of the top-level tag of the XML configuration sent to the client.

Returns:	string - the current version

Exposing XML-RPC Functions¶

Plugins can expose XML-RPC functions that can then be called with bcfg2-admin xcmd. Note that there is absolutely no access control beyond the initial authentication, so take care to not expose any data or behavior via XML-RPC that you would not want all of your clients to be able to see or use.

To expose a function, simply add its name to the __rmi__ class attribute. (RMI stands for “Remote Method Invocation.”) Consider this example from the Packages plugin:

class Packages(Bcfg2.Server.Plugin.Plugin,
               Bcfg2.Server.Plugin.StructureValidator,
               Bcfg2.Server.Plugin.Generator,
               Bcfg2.Server.Plugin.Connector,
               Bcfg2.Server.Plugin.ClientRunHooks):
    name = 'Packages'
    conflicts = ['Pkgmgr']
    __rmi__ = Bcfg2.Server.Plugin.Plugin.__rmi__ + ['Refresh', 'Reload']

def Refresh(self):
    self._load_config(force_update=True)
    return True

def Reload(self):
    self._load_config()
    return True

This exposes two functions, Refresh and Reload, in addition to any default methods that are already exposed. To call one of these functions, you could run:

bcfg2-admin xcmd Packages.Refresh

Invalidating Caches¶

New in version 1.3.0.

In Bcfg2 1.3.0, some limited Server-side Caching was introduced. If you are writing a Bcfg2.Server.Plugin.interfaces.Connector plugin that implements Bcfg2.Server.Plugin.interfaces.Connector.get_additional_groups() or Bcfg2.Server.Plugin.interfaces.Connector.get_additional_data(), then you need to be able to invalidate the server metadata cache in order to be compatible with the cautious or aggressive caching modes.

The two attributes you need to know about are:

Bcfg2.Server.Core.metadata_cache_mode: A string description of the caching mode. See Server-side Caching for a description of each mode.
Bcfg2.Server.Core.metadata_cache: A dict-like Bcfg2.Server.Cache.Cache object that stores the cached data.

Bcfg2.Server.Plugin.base.Plugin objects have access to the Bcfg2.Server.Core object as self.core. In general, you’ll be interested in the Bcfg2.Server.Cache.Cache.expire() method; if called with no arguments, it expires all cached data; if called with one string argument, it expires cached data for the named client.

It’s important, therefore, that your Connector plugin can either track when changes are made to the data or group membership it reports, and expire cached data appropriately when in cautious or aggressive mode; or prudently flag an incompatibility with those two modes.

For examples, see:

Bcfg2.Server.Plugins.Probes.ReceiveData() takes a copy of the groups that have been assigned to a client by Probes, and if that data changes when new probe data is received, it invalidates the cache for that client.
Bcfg2.Server.Plugins.GroupPatterns.Index() expires the entire cache whenever a FAM event is received for the GroupPatterns config file.
Bcfg2.Server.Plugins.PuppetENC.end_client_run() expires the entire cache at the end of every client run and produces a message at the warning level that the PuppetENC plugin is incompatible with aggressive caching.

Tracking Execution Time¶

New in version 1.3.0.

Statistics can and should track execution time statistics using Bcfg2.Server.Statistics. This module tracks execution time for the server core and for plugins, and exposes that data via bcfg2-admin perf. This data can be invaluable for locating bottlenecks or other performance issues.

The simplest way to track statistics is to use the Bcfg2.Server.Statistics.track_statistics() decorator to decorate functions that you would like to track execution times for:

from Bcfg2.Server.Statistics import track_statistics

@track_statistics()
def do_something(self, ...):
    ...

This will track the execution time of do_something.

More granular usage is possible by using time.time() to manually determine the execution time of a given event and calling Bcfg2.Server.Statistics.Statistics.add_value() with an appropriate statistic name.

Bcfg2.Server.Statistics¶

Module for tracking execution time statistics from the Bcfg2 server core. This data is exposed by Bcfg2.Server.Core.BaseCore.get_statistics().

class Bcfg2.Server.Statistics.Statistic(name, initial_value)[source]¶

Bases: object

A single named statistic, tracking minimum, maximum, and average execution time, and number of invocations.

Parameters:	name (string) – The name of this statistic initial_value (int or float) – The initial value to be added to this statistic

add_value(value)[source]¶

Add a value to the statistic, recalculating the various metrics.

Parameters:	value (int or float) – The value to add to this statistic

get_value()[source]¶

Get a tuple of all the stats tracked on this named item. The tuple is in the format:

(<name>, (min, max, average, number of values))

This makes it very easy to cast to a dict in Statistics.display().

Returns:	tuple

class Bcfg2.Server.Statistics.Statistics[source]¶

Bases: object

A collection of named Statistic objects.

add_value(name, value)[source]¶

Add a value to the named Statistic. This just proxies to Statistic.add_value() or the Statistic constructor as appropriate.

Parameters:	name (string) – The name of the `Statistic` to add the value to value (int or float) – The value to add to the Statistic

display()[source]¶: Return a dict of all Statistic object values. Keys are the statistic names, and values are tuples of the statistic metrics as returned by Statistic.get_value().

Bcfg2.Server.Statistics.stats = <Bcfg2.Server.Statistics.Statistics object at 0x68c6110>¶: A module-level Statistics objects used to track all execution time metrics for the server.

class Bcfg2.Server.Statistics.track_statistics(name=None)[source]¶

Bases: object

Decorator that tracks execution time for the given method with Bcfg2.Server.Statistics for reporting via bcfg2-admin perf

Parameters:	name (string) – The name under which statistics for this function will be tracked. By default, the name will be the name of the function concatenated with the name of the class the function is a member of.

Plugin Helper Classes¶

Helper classes for Bcfg2 server plugins

class Bcfg2.Server.Plugin.helpers.DatabaseBacked(core)[source]¶

Bases: Bcfg2.Server.Plugin.base.Plugin

Provides capabilities for a plugin to read and write to a database. The plugin must add an option to flag database use with something like:

options = Bcfg2.Server.Plugin.Plugins.options + [

Bcfg2.Options.BooleanOption(: cf=(‘metadata’, ‘use_database’), dest=”metadata_db”, help=”Use database capabilities of the Metadata plugin”)

This must be done manually due to various limitations in Python.

_must_lock[source]¶: Whether or not the backend database must acquire a thread lock before writing, because it does not allow multiple threads to write.

_use_db[source]¶: Whether or not this plugin is configured to use the database.

debug_log(message, flag=None)¶

Log a message at the debug level.

Parameters:	message (string) – The message to log flag (bool) – Override the current debug flag with this value
Returns:	None

static get_db_lock(func)[source]¶: Decorator to be used by a method of a DatabaseBacked plugin that will update database data.

classmethod init_repo(repo)¶

Perform any tasks necessary to create an initial Bcfg2 repository.

Parameters:	repo (string) – The path to the Bcfg2 repository on the filesystem
Returns:	None

shutdown()¶

Perform shutdown tasks for the plugin

Returns:	None

toggle_debug()¶

Turn debugging output on or off.

Returns:	bool - The new value of the debug flag

class Bcfg2.Server.Plugin.helpers.DefaultTemplateDataProvider[source]¶

Bases: Bcfg2.Server.Plugin.interfaces.TemplateDataProvider

A base Bcfg2.Server.Plugin.interfaces.TemplateDataProvider that provides default data for text and XML templates.

Note that, since Cheetah and Genshi text templates treat the path variable differently, this is overridden, by Bcfg2.Server.Plugins.Cfg.CfgCheetahGenerator.DefaultCheetahDataProvider and Bcfg2.Server.Plugins.Cfg.CfgGenshiGenerator.DefaultGenshiDataProvider, respectively.

class Bcfg2.Server.Plugin.helpers.DirectoryBacked(data)[source]¶

Bases: Bcfg2.Logger.Debuggable

DirectoryBacked objects represent a directory that contains files, represented by objects of the type listed in __child__, and other directories recursively. It monitors for new files and directories to be added, and creates new objects as required to track those.

Parameters:	data (string) – The path to the data directory that will be monitored

__child__ = <class 'Bcfg2.Server.Plugin.helpers.FileBacked'>¶: The type of child objects to create for files contained within the directory that is tracked. Default is Bcfg2.Server.Plugin.helpers.FileBacked

HandleEvent(event)[source]¶

Handle FAM events.

This method is invoked by the FAM when it detects a change to a filesystem object we have requsted to be monitored.

This method manages the lifecycle of events related to the monitored objects, adding them to our list of entries and creating objects of type __child__ that actually do the domain-specific processing. When appropriate, it propogates events those objects by invoking their HandleEvent method in turn.

Parameters:	event (Bcfg2.Server.FileMonitor.Event) – FAM event that caused this entry to be added.
Returns:	None

add_directory_monitor(relative)[source]¶

Add a new directory to the FAM for monitoring.

Parameters:	relative (string) – Path name to monitor. This must be relative to the plugin’s directory. An empty string value (“”) will cause the plugin directory itself to be monitored.
Returns:	None

add_entry(relative, event)[source]¶

Add a new file to our tracked entries, and to our FAM for monitoring.

Parameters:	relative (string:) – Path name to monitor. This must be relative to the plugin’s directory. event (Bcfg2.Server.FileMonitor.Event) – FAM event that caused this entry to be added.
Returns:	None

debug_log(message, flag=None)¶

Log a message at the debug level.

Parameters:	message (string) – The message to log flag (bool) – Override the current debug flag with this value
Returns:	None

entries = None¶: self.entries contains information about the files monitored by this object. The keys of the dict are the relative paths to the files. The values are the objects (of type __child__) that handle their contents.

handles = None¶: self.handles contains information about the directories monitored by this object. The keys of the dict are the values returned by the initial fam.AddMonitor() call (which appear to be integers). The values are the relative paths of the directories.

ignore = None¶: Preemptively ignore files whose names (not paths) match this compiled regex. ignore can be set to None to ignore no files. If a file is encountered that does not match patterns or ignore, then a warning will be produced.

patterns = <_sre.SRE_Pattern object at 0x3c8deb8>¶: Only track and include files whose names (not paths) match this compiled regex.

toggle_debug()¶

Turn debugging output on or off.

Returns:	bool - The new value of the debug flag

class Bcfg2.Server.Plugin.helpers.EntrySet(basename, path, entry_type)[source]¶

Bases: Bcfg2.Logger.Debuggable

EntrySets deal with a collection of host- and group-specific files (e.g., Bcfg2.Server.Plugin.helpers.SpecificData objects) in a single directory. EntrySets are usually used as part of Bcfg2.Server.Plugin.helpers.GroupSpool objects.

Parameters:

basename (string) – The filename or regular expression that files in this EntrySet must match. See basename_is_regex for more details.
path (string) – The full path to the directory containing files for this EntrySet
entry_type (callable) – A callable that returns an object that represents files in this EntrySet. This will usually be a class object, but it can be an object factory or similar callable. See below for the expected signature.

The entry_type callable must have the following signature:

entry_type(filepath, specificity)

Where the parameters are:

Parameters:	filepath (string) – Full path to file specific (Bcfg2.Server.Plugin.helpers.Specificity) – A `Bcfg2.Server.Plugin.helpers.Specificity` object describing what clients this file applies to.

Additionally, the object returned by entry_type must have a specific attribute that is sortable (e.g., a Bcfg2.Server.Plugin.helpers.Specificity object).

See Bcfg2.Server.Plugin.helpers.SpecificData for an example of a class that can be used as an entry_type.

basename_is_regex = False¶: processed as a string that contains a regular expression (i.e., not a compiled regex object) if basename_is_regex is True, and all files that match the regex will be cincluded in the EntrySet. If basename_is_regex is False, then it will be considered a plain string and filenames must match exactly.

best_matching(metadata, matching=None)[source]¶

Return the single most specific matching entry from the set of matching entries. You can use get_matching() to get all matching entries.

Parameters:	metadata (Bcfg2.Server.Plugins.Metadata.ClientMetadata) – The client metadata to get matching entries for matching (list of `entry_type` objects (see the constructor docs for more details)) – The set of matching entries to pick from. If this is not provided, `get_matching()` will be called.
Returns:	a single object from the list of matching `entry_type` objects
Raises :	`Bcfg2.Server.Plugin.exceptions.PluginExecutionError` if no matching entries are found

bind_entry(entry, metadata)[source]¶

Return the single best fully-bound entry from the set of available entries for the specified client.

Parameters:	entry (lxml.etree._Element) – The abstract entry to bind the info to metadata (Bcfg2.Server.Plugins.Metadata.ClientMetadata) – The client metadata to get info for
Returns:	lxml.etree._Element - the fully-bound entry

bind_info_to_entry(entry, metadata)[source]¶

Bind the metadata for the given client in the base info.xml for this EntrySet to the entry.

Parameters:	entry (lxml.etree._Element) – The abstract entry to bind the info to. This will be modified in place metadata (Bcfg2.Server.Plugins.Metadata.ClientMetadata) – The client metadata to get info for
Returns:	None

debug_log(message, flag=None)¶

Log a message at the debug level.

Parameters:	message (string) – The message to log flag (bool) – Override the current debug flag with this value
Returns:	None

entry_init(event, entry_type=None, specific=None)[source]¶

Handle the creation of a file on the filesystem and the creation of an object in this EntrySet to track it.

Parameters:	event (Bcfg2.Server.FileMonitor.Event) – An event that applies to a file handled by this EntrySet entry_type (callable) – Override the default `entry_type` for this EntrySet object and create a different object for this entry. See the constructor docs for more information on `entry_type`. specific (compiled regular expression object) – Override the default `specific` regular expression used by this object with a custom regular expression that will be used to determine the specificity of this entry.
Returns:	None
Raises :	`Bcfg2.Server.Plugin.exceptions.SpecificityError`

get_matching(metadata)[source]¶

Get a list of all entries that apply to the given client. This gets all matching entries; for example, there could be an entry that applies to all clients, multiple group-specific entries, and a client-specific entry, all of which would be returned by get_matching(). You can use best_matching() to get the single best matching entry.

Parameters:	metadata (Bcfg2.Server.Plugins.Metadata.ClientMetadata) – The client metadata to get matching entries for
Returns:	list – all matching `entry_type` objects (see the constructor docs for more details)

handle_event(event)[source]¶

Dispatch a FAM event to the appropriate function or child entry_type object. This will probably be handled by a call to update_metadata(), reset_metadata(), entry_init(), or to the entry_type handle_event() function.

Parameters:	event (Bcfg2.Server.FileMonitor.Event) – An event that applies to a file handled by this EntrySet
Returns:	None

ignore = <_sre.SRE_Pattern object at 0x405fe50>¶: Preemptively ignore files whose names (not paths) match this compiled regex. ignore cannot be set to None. If a file is encountered that does not match the basename argument passed to the constructor or ignore, then a warning will be produced.

reset_metadata(event)[source]¶

Reset metadata to defaults if info.xml is removed.

Parameters:	event (Bcfg2.Server.FileMonitor.Event) – An event that applies to an info handled by this EntrySet
Returns:	None

specific = None¶: specific is a regular expression that is used to determine the specificity of a file in this entry set. It must have three named groups: hostname, prio (the priority of a group-specific file), and group. The base regex is constructed from the basename argument. It can be overridden on a per-entry basis in entry_init().

specificity_from_filename(fname, specific=None)[source]¶

Construct a Bcfg2.Server.Plugin.helpers.Specificity object from a filename and regex. See specific for details on the regex.

Parameters:	fname (string) – The filename (not full path) of a file that is in this EntrySet’s directory. It is not necessary to determine first if the filename matches this EntrySet’s basename; that can be done by catching `Bcfg2.Server.Plugin.exceptions.SpecificityError` from this function. specific (compiled regular expression object) – Override the default `specific` regular expression used by this object with a custom regular expression that will be used to determine the specificity of this entry.
Returns:	Object representing the specificity of the file
Return type:	`Bcfg2.Server.Plugin.helpers.Specificity`
Raises :	`Bcfg2.Server.Plugin.exceptions.SpecificityError` if the regex does not match the filename

toggle_debug()¶

Turn debugging output on or off.

Returns:	bool - The new value of the debug flag

update_metadata(event)[source]¶

Process changes to or creation of info.xml files for the EntrySet.

Parameters:	event (Bcfg2.Server.FileMonitor.Event) – An event that applies to an info handled by this EntrySet
Returns:	None

class Bcfg2.Server.Plugin.helpers.FileBacked(name)[source]¶

Bases: Bcfg2.Logger.Debuggable

This object caches file data in memory. FileBacked objects are principally meant to be used as a part of Bcfg2.Server.Plugin.helpers.DirectoryBacked.

Parameters:	name (string) – The full path to the file to cache and monitor

HandleEvent(event=None)[source]¶

HandleEvent is called whenever the FAM registers an event.

Parameters:	event (Bcfg2.Server.FileMonitor.Event) – The event object
Returns:	None

Index()[source]¶: Index() is called by HandleEvent() every time the data changes, and parses the data into usable data as required.

data = None¶: A string containing the raw data in this file

debug_log(message, flag=None)¶

Log a message at the debug level.

Parameters:	message (string) – The message to log flag (bool) – Override the current debug flag with this value
Returns:	None

fam = None¶: The FAM object used to receive notifications of changes

name = None¶: The full path to the file

set_debug(debug)¶

Explicitly enable or disable debugging.

Returns:	bool - The new value of the debug flag

toggle_debug()¶

Turn debugging output on or off.

Returns:	bool - The new value of the debug flag

class Bcfg2.Server.Plugin.helpers.GroupSpool(core)[source]¶

Bases: Bcfg2.Server.Plugin.base.Plugin, Bcfg2.Server.Plugin.interfaces.Generator

A GroupSpool is a collection of Bcfg2.Server.Plugin.helpers.EntrySet objects – i.e., a directory tree, each directory in which may contain files that are specific to groups/clients/etc.

Parameters:	core (Bcfg2.Server.Core) – The Bcfg2.Server.Core initializing the plugin
Raises :	`OSError` if adding a file monitor failed; `Bcfg2.Server.Plugin.exceptions.PluginInitError` on other errors

Debuggable.__rmi__ = ['toggle_debug', 'set_debug']¶: List of names of methods to be exposed as XML-RPC functions, if applicable to the child class

AddDirectoryMonitor(relative)[source]¶

Add a FAM monitor to a new directory and set the appropriate event handler.

Parameters:	relative (string) – The path to the directory relative to the base data directory of the GroupSpool object.
Returns:	None

HandleEntry(entry, metadata)¶

HandleEntry is the slow path method for binding configuration binding requests. It is called if the Entries dict does not contain a method for binding the entry, and HandlesEntry() returns True.

Parameters:	entry (lxml.etree._Element) – The entry to bind metadata (Bcfg2.Server.Plugins.Metadata.ClientMetadata) – The client metadata
Returns:	lxml.etree._Element - The fully bound entry
Raises :	`Bcfg2.Server.Plugin.exceptions.PluginExecutionError`

HandleEvent(event)[source]¶

HandleEvent is the event dispatcher for GroupSpool objects. It receives all events and dispatches them the appropriate handling object (e.g., one of the es_cls objects in entries), function (e.g., add_entry()), or behavior (e.g., deleting an entire entry set).

Parameters:	event (Bcfg2.Server.FileMonitor.Event) – An event that applies to a file or directory handled by this GroupSpool
Returns:	None

HandlesEntry(entry, metadata)¶

HandlesEntry is the slow path method for routing configuration binding requests. It is called if the Entries dict does not contain a method for binding the entry.

Parameters:	entry (lxml.etree._Element) – The entry to bind metadata (Bcfg2.Server.Plugins.Metadata.ClientMetadata) – The client metadata
Returns:	bool - Whether or not this plugin can handle the entry
Raises :	`Bcfg2.Server.Plugin.exceptions.PluginExecutionError`

add_entry(event)[source]¶

This method handles two functions:

Adding a new entry of type es_cls to track a new directory.
Passing off an event on a file to the correct entry object to handle it.

Parameters:	event (Bcfg2.Server.FileMonitor.Event) – An event that applies to a file or directory handled by this GroupSpool
Returns:	None

debug_log(message, flag=None)¶

Log a message at the debug level.

Parameters:	message (string) – The message to log flag (bool) – Override the current debug flag with this value
Returns:	None

entries = None¶: entries is a dict whose keys are event_id() return values and whose values are es_cls objects. It ties the directories handled by this GroupSpools to the es_cls objects that handle each directory.

entry_type = 'Path'¶: The entry type (i.e., the XML tag) handled by this GroupSpool object.

es_child_cls¶

es_child_cls is a callable that will be used as the entry_type argument to the es_cls callable. It must return objects that will represent individual files in the GroupSpool. For instance, Bcfg2.Server.Plugin.helpers.SpecificData.

alias of object

es_cls¶

es_cls is a callable that must return objects that will be used to represent directories (i.e., sets of entries) within the GroupSpool. E.g., Bcfg2.Server.Plugin.helpers.EntrySet. The returned object must implement a callable called bind_entry that has the same signature as EntrySet.bind_entry.

alias of EntrySet

event_id(event)[source]¶

Return a string that can be used to relate the event unambiguously to a single es_cls object in the entries dict. In practice, this means:

If the event is on a directory, event_id returns the full path to the directory.
If the event is on a file, event_id returns the full path to the directory the file is in.

Parameters:	event (Bcfg2.Server.FileMonitor.Event) – An event that applies to a file or directory handled by this GroupSpool
Returns:	string

event_path(event)[source]¶

Return the full path to the filename affected by an event. Bcfg2.Server.FileMonitor.Event objects just contain the filename, not the full path, so this function reconstructs the fill path based on the path to the es_cls object that handles the event.

Parameters:	event (Bcfg2.Server.FileMonitor.Event) – An event that applies to a file or directory handled by this GroupSpool
Returns:	string

filename_pattern = ''¶: filename_pattern is used as the basename argument to the es_cls callable. It may or may not be a regex, depending on the EntrySet.basename_is_regex setting.

classmethod init_repo(repo)¶

Perform any tasks necessary to create an initial Bcfg2 repository.

Parameters:	repo (string) – The path to the Bcfg2 repository on the filesystem
Returns:	None

shutdown()¶

Perform shutdown tasks for the plugin

Returns:	None

toggle_debug()¶

Turn debugging output on or off.

Returns:	bool - The new value of the debug flag

class Bcfg2.Server.Plugin.helpers.InfoXML(filename, should_monitor=False, create=None)[source]¶

Bases: Bcfg2.Server.Plugin.helpers.StructFile

InfoXML files contain Group, Client, and Path tags to set the metadata (permissions, owner, etc.) of files.

BindEntry(entry, metadata)[source]¶

Bind the matching file metadata for this client and entry to the entry.

Parameters:	entry (lxml.etree._Element) – The abstract entry to bind the info to. This will be modified in place metadata (Bcfg2.Server.Plugins.Metadata.ClientMetadata) – The client metadata to get info for
Returns:	None

HandleEvent(event=None)¶

HandleEvent is called whenever the FAM registers an event.

Parameters:	event (Bcfg2.Server.FileMonitor.Event) – The event object
Returns:	None

Index()¶: Index() is called by HandleEvent() every time the data changes, and parses the data into usable data as required.

Match(metadata, entry)[source]¶: Implementation of Bcfg2.Server.Plugin.helpers.StructFile.Match() that considers Path tags to allow info.xml files to set different file metadata for different file paths.

XMLMatch(metadata, entry)[source]¶: Implementation of Bcfg2.Server.Plugin.helpers.StructFile.XMLMatch() that considers Path tags to allow info.xml files to set different file metadata for different file paths.

add_monitor(fpath)¶

Add a FAM monitor to a file that has been XIncluded.

Parameters:	fpath (string) – The full path to the file to monitor
Returns:	None

debug_log(message, flag=None)¶

Log a message at the debug level.

Parameters:	message (string) – The message to log flag (bool) – Override the current debug flag with this value
Returns:	None

set_debug(debug)¶

Explicitly enable or disable debugging.

Returns:	bool - The new value of the debug flag

toggle_debug()¶

Turn debugging output on or off.

Returns:	bool - The new value of the debug flag

class Bcfg2.Server.Plugin.helpers.PluginDatabaseModel[source]¶

Bases: object

A database model mixin that all database models used by Bcfg2.Server.Plugin.helpers.DatabaseBacked plugins must inherit from. This is just a mixin; models must also inherit from django.db.models.Model to be valid Django models.

class Meta[source]¶

Bases: object

Model metadata options

class Bcfg2.Server.Plugin.helpers.PrioDir(core)[source]¶

Bases: Bcfg2.Server.Plugin.base.Plugin, Bcfg2.Server.Plugin.interfaces.Generator, Bcfg2.Server.Plugin.helpers.XMLDirectoryBacked

PrioDir handles a directory of XML files where each file has a set priority.

__child__ = <class 'Bcfg2.Server.Plugin.helpers.PriorityStructFile'>¶: The type of child objects to create for files contained within the directory that is tracked. Default is Bcfg2.Server.Plugin.helpers.PriorityStructFile

Parameters:	core (Bcfg2.Server.Core) – The Bcfg2.Server.Core initializing the plugin
Raises :	`OSError` if adding a file monitor failed; `Bcfg2.Server.Plugin.exceptions.PluginInitError` on other errors

Debuggable.__rmi__ = ['toggle_debug', 'set_debug']¶: List of names of methods to be exposed as XML-RPC functions, if applicable to the child class

BindEntry(entry, metadata)[source]¶

Bind the attributes that apply to an entry to it. The entry is modified in-place.

Parameters:	entry (lxml.etree._Element) – The entry to add attributes to. metadata (Bcfg2.Server.Plugins.Metadata.ClientMetadata) – The metadata to get attributes for
Returns:	None

HandleEntry(entry, metadata)¶

HandleEntry is the slow path method for binding configuration binding requests. It is called if the Entries dict does not contain a method for binding the entry, and HandlesEntry() returns True.

Parameters:	entry (lxml.etree._Element) – The entry to bind metadata (Bcfg2.Server.Plugins.Metadata.ClientMetadata) – The client metadata
Returns:	lxml.etree._Element - The fully bound entry
Raises :	`Bcfg2.Server.Plugin.exceptions.PluginExecutionError`

HandleEvent(event)[source]¶

Handle FAM events.

This method is invoked by the FAM when it detects a change to a filesystem object we have requsted to be monitored.

This method manages the lifecycle of events related to the monitored objects, adding them to our list of entries and creating objects of type __child__ that actually do the domain-specific processing. When appropriate, it propogates events those objects by invoking their HandleEvent method in turn.

Parameters:	event (Bcfg2.Server.FileMonitor.Event) – FAM event that caused this entry to be added.
Returns:	None

HandlesEntry(entry, metadata)¶

HandlesEntry is the slow path method for routing configuration binding requests. It is called if the Entries dict does not contain a method for binding the entry.

Parameters:	entry (lxml.etree._Element) – The entry to bind metadata (Bcfg2.Server.Plugins.Metadata.ClientMetadata) – The client metadata
Returns:	bool - Whether or not this plugin can handle the entry
Raises :	`Bcfg2.Server.Plugin.exceptions.PluginExecutionError`

add_directory_monitor(relative)¶

Add a new directory to the FAM for monitoring.

Parameters:	relative (string) – Path name to monitor. This must be relative to the plugin’s directory. An empty string value (“”) will cause the plugin directory itself to be monitored.
Returns:	None

add_entry(relative, event)¶

Add a new file to our tracked entries, and to our FAM for monitoring.

Parameters:	relative (string:) – Path name to monitor. This must be relative to the plugin’s directory. event (Bcfg2.Server.FileMonitor.Event) – FAM event that caused this entry to be added.
Returns:	None

debug_log(message, flag=None)¶

Log a message at the debug level.

Parameters:	message (string) – The message to log flag (bool) – Override the current debug flag with this value
Returns:	None

classmethod init_repo(repo)¶

Perform any tasks necessary to create an initial Bcfg2 repository.

Parameters:	repo (string) – The path to the Bcfg2 repository on the filesystem
Returns:	None

shutdown()¶

Perform shutdown tasks for the plugin

Returns:	None

toggle_debug()¶

Turn debugging output on or off.

Returns:	bool - The new value of the debug flag

class Bcfg2.Server.Plugin.helpers.PriorityStructFile(filename, should_monitor=False)[source]¶

Bases: Bcfg2.Server.Plugin.helpers.StructFile

A StructFile where each file has a priority, given as a top-level XML attribute.

HandleEvent(event=None)¶

HandleEvent is called whenever the FAM registers an event.

Parameters:	event (Bcfg2.Server.FileMonitor.Event) – The event object
Returns:	None

Index()[source]¶: Index() is called by HandleEvent() every time the data changes, and parses the data into usable data as required.

Match(metadata)¶

Return matching fragments of the data in this file. A tag is considered to match if all <Group> and <Client> tags that are its ancestors match the metadata given. Since tags are included unmodified, it’s possible for a tag to itself match while containing non-matching children. Consequently, only the tags contained in the list returned by Match() (and not their descendents) should be considered to match the metadata.

Match() returns matching fragments in document order.

Parameters:	metadata (Bcfg2.Server.Plugins.Metadata.ClientMetadata) – Client metadata to match against.
Returns:	list of lxml.etree._Element objects

XMLMatch(metadata)¶

Return a rebuilt XML document that only contains the matching portions of the original file. A tag is considered to match if all <Group> and <Client> tags that are its ancestors match the metadata given. Unlike Match(), the document returned by XMLMatch will only contain matching data. All <Group> and <Client> tags will have been stripped out.

The new document produced by XMLMatch() is not necessarily in the same order as the original document.

Parameters:	metadata (Bcfg2.Server.Plugins.Metadata.ClientMetadata) – Client metadata to match against.
Returns:	lxml.etree._Element

add_monitor(fpath)¶

Add a FAM monitor to a file that has been XIncluded.

Parameters:	fpath (string) – The full path to the file to monitor
Returns:	None

debug_log(message, flag=None)¶

Log a message at the debug level.

Parameters:	message (string) – The message to log flag (bool) – Override the current debug flag with this value
Returns:	None

set_debug(debug)¶

Explicitly enable or disable debugging.

Returns:	bool - The new value of the debug flag

toggle_debug()¶

Turn debugging output on or off.

Returns:	bool - The new value of the debug flag

class Bcfg2.Server.Plugin.helpers.SpecificData(name, specific)[source]¶

Bases: Bcfg2.Logger.Debuggable

A file that is specific to certain clients, groups, or all clients.

Parameters:	name (string) – The full path to the file specific (Bcfg2.Server.Plugin.helpers.Specificity) – A `Bcfg2.Server.Plugin.helpers.Specificity` object describing what clients this file applies to.

debug_log(message, flag=None)¶

Log a message at the debug level.

Parameters:	message (string) – The message to log flag (bool) – Override the current debug flag with this value
Returns:	None

handle_event(event)[source]¶

Handle a FAM event. Note that the SpecificData object itself has no FAM, so this must be produced by a parent object (e.g., Bcfg2.Server.Plugin.helpers.EntrySet).

Parameters:	event (Bcfg2.Server.FileMonitor.Event) – The event that applies to this file
Returns:	None
Raises :	`Bcfg2.Server.Plugin.exceptions.PluginExecutionError`

set_debug(debug)¶

Explicitly enable or disable debugging.

Returns:	bool - The new value of the debug flag

toggle_debug()¶

Turn debugging output on or off.

Returns:	bool - The new value of the debug flag

class Bcfg2.Server.Plugin.helpers.Specificity(all=False, group=False, hostname=False, prio=0, delta=False)[source]¶

Bases: Bcfg2.Compat.CmpMixin

Represent the specificity of an object; i.e., what client(s) it applies to. It can be group- or client-specific, or apply to all clients.

Specificity objects are sortable; objects that are less specific are considered less than objects that are more specific. Objects that apply to all clients are the least specific; objects that apply to a single client are the most specific. Objects that apply to groups are sorted by priority.

Parameters:

all (bool) – The object applies to all clients.
group (string or False) – The object applies only to the given group.
hostname (string or False) – The object applies only to the named client.
prio (int) – The object has the given priority relative to other objects that also apply to the same group. <group> must be specified with <prio>.
delta (bool) – The object is a delta (i.e., a .cat or .diff file, not a full file). Deltas are deprecated.

Exactly one of {all|group|hostname} should be given.

matches(metadata)[source]¶

Return True if the object described by this Specificity object applies to the given client. That is, if this Specificity applies to all clients, or to a group the client is a member of, or to the client individually.

Parameters:	metadata (Bcfg2.Server.Plugins.Metadata.ClientMetadata) – The client metadata
Returns:	bool

class Bcfg2.Server.Plugin.helpers.StructFile(filename, should_monitor=False, create=None)[source]¶

Bases: Bcfg2.Server.Plugin.helpers.XMLFileBacked

StructFiles are XML files that contain a set of structure file formatting logic for handling <Group> and <Client> tags.

__identifier__ = None¶: If __identifier__ is not None, then it must be the name of an XML attribute that will be required on the top-level tag of the file being cached

_include_element(item, metadata, *args)[source]¶

Determine if an XML element matches the other arguments.

The first argument is always the XML element to match, and the second will always be a single Bcfg2.Server.Plugins.Metadata.ClientMetadata object representing the metadata to match against. Subsequent arguments are as given to Bcfg2.Server.Plugin.helpers.StructFile.Match() or Bcfg2.Server.Plugin.helpers.StructFile.XMLMatch(). In the base StructFile implementation, there are no additional arguments; in classes that inherit from StructFile, see the Match() and XMLMatch() method signatures.

HandleEvent(event=None)¶

HandleEvent is called whenever the FAM registers an event.

Parameters:	event (Bcfg2.Server.FileMonitor.Event) – The event object
Returns:	None

Index()[source]¶: Index() is called by HandleEvent() every time the data changes, and parses the data into usable data as required.

Match(metadata)[source]¶

Return matching fragments of the data in this file. A tag is considered to match if all <Group> and <Client> tags that are its ancestors match the metadata given. Since tags are included unmodified, it’s possible for a tag to itself match while containing non-matching children. Consequently, only the tags contained in the list returned by Match() (and not their descendents) should be considered to match the metadata.

Match() returns matching fragments in document order.

Parameters:	metadata (Bcfg2.Server.Plugins.Metadata.ClientMetadata) – Client metadata to match against.
Returns:	list of lxml.etree._Element objects

XMLMatch(metadata)[source]¶

Return a rebuilt XML document that only contains the matching portions of the original file. A tag is considered to match if all <Group> and <Client> tags that are its ancestors match the metadata given. Unlike Match(), the document returned by XMLMatch will only contain matching data. All <Group> and <Client> tags will have been stripped out.

The new document produced by XMLMatch() is not necessarily in the same order as the original document.

Parameters:	metadata (Bcfg2.Server.Plugins.Metadata.ClientMetadata) – Client metadata to match against.
Returns:	lxml.etree._Element

add_monitor(fpath)¶

Add a FAM monitor to a file that has been XIncluded.

Parameters:	fpath (string) – The full path to the file to monitor
Returns:	None

debug_log(message, flag=None)¶

Log a message at the debug level.

Parameters:	message (string) – The message to log flag (bool) – Override the current debug flag with this value
Returns:	None

encryption = True¶: Whether or not to enable encryption

set_debug(debug)¶

Explicitly enable or disable debugging.

Returns:	bool - The new value of the debug flag

toggle_debug()¶

Turn debugging output on or off.

Returns:	bool - The new value of the debug flag

class Bcfg2.Server.Plugin.helpers.XMLDirectoryBacked(data)[source]¶

Bases: Bcfg2.Server.Plugin.helpers.DirectoryBacked

Bcfg2.Server.Plugin.helpers.DirectoryBacked for XML files.

Parameters:	data (string) – The path to the data directory that will be monitored

__child__ = <class 'Bcfg2.Server.Plugin.helpers.XMLFileBacked'>¶: The type of child objects to create for files contained within the directory that is tracked. Default is Bcfg2.Server.Plugin.helpers.XMLFileBacked

HandleEvent(event)¶

Handle FAM events.

This method is invoked by the FAM when it detects a change to a filesystem object we have requsted to be monitored.

This method manages the lifecycle of events related to the monitored objects, adding them to our list of entries and creating objects of type __child__ that actually do the domain-specific processing. When appropriate, it propogates events those objects by invoking their HandleEvent method in turn.

Parameters:	event (Bcfg2.Server.FileMonitor.Event) – FAM event that caused this entry to be added.
Returns:	None

add_directory_monitor(relative)¶

Add a new directory to the FAM for monitoring.

Parameters:	relative (string) – Path name to monitor. This must be relative to the plugin’s directory. An empty string value (“”) will cause the plugin directory itself to be monitored.
Returns:	None

add_entry(relative, event)¶

Add a new file to our tracked entries, and to our FAM for monitoring.

Parameters:	relative (string:) – Path name to monitor. This must be relative to the plugin’s directory. event (Bcfg2.Server.FileMonitor.Event) – FAM event that caused this entry to be added.
Returns:	None

debug_log(message, flag=None)¶

Log a message at the debug level.

Parameters:	message (string) – The message to log flag (bool) – Override the current debug flag with this value
Returns:	None

patterns = <_sre.SRE_Pattern object at 0x3758e90>¶: Only track and include files whose names (not paths) match this compiled regex.

toggle_debug()¶

Turn debugging output on or off.

Returns:	bool - The new value of the debug flag

class Bcfg2.Server.Plugin.helpers.XMLFileBacked(filename, should_monitor=False, create=None)[source]¶

Bases: Bcfg2.Server.Plugin.helpers.FileBacked

This object parses and caches XML file data in memory. It can be used as a standalone object or as a part of Bcfg2.Server.Plugin.helpers.XMLDirectoryBacked

Parameters:

filename (string) – The full path to the file to cache and monitor
should_monitor (bool) – Whether or not to monitor this file for changes. It may be useful to disable monitoring when, for instance, the file is monitored by another object (e.g., an Bcfg2.Server.Plugin.helpers.XMLDirectoryBacked object).
create (lxml.etree._Element or string) – Create the file if it doesn’t exist. create can be either an lxml.etree._Element object, which will be used as initial content, or a string, which will be used as the name of the (empty) tag that will be the initial content of the file.

__identifier__ = 'name'¶: If __identifier__ is set, then a top-level tag with the specified name will be required on the file being cached. Its value will be available as label. To disable this behavior, set __identifier__ to None.

HandleEvent(event=None)¶

HandleEvent is called whenever the FAM registers an event.

Parameters:	event (Bcfg2.Server.FileMonitor.Event) – The event object
Returns:	None

Index()[source]¶: Index() is called by HandleEvent() every time the data changes, and parses the data into usable data as required.

add_monitor(fpath)[source]¶

Add a FAM monitor to a file that has been XIncluded.

Parameters:	fpath (string) – The full path to the file to monitor
Returns:	None

create = None¶: If create is set, then it overrides the create argument to the constructor.

debug_log(message, flag=None)¶

Log a message at the debug level.

Parameters:	message (string) – The message to log flag (bool) – Override the current debug flag with this value
Returns:	None

entries = None¶: All entries in this file. By default, all immediate children of the top-level XML tag.

extra_monitors = None¶: Extra FAM monitors set by this object for files included by XInclude.

extras = None¶: “Extra” files included in this file by XInclude.

label = None¶: The label of this file. This is determined from the top-level tag in the file, which must have an attribute specified by __identifier__.

set_debug(debug)¶

Explicitly enable or disable debugging.

Returns:	bool - The new value of the debug flag

should_monitor = None¶: Whether or not to monitor this file for changes.

toggle_debug()¶

Turn debugging output on or off.

Returns:	bool - The new value of the debug flag

xdata = None¶: The raw XML data contained in the file as an lxml.etree.ElementTree object, with XIncludes processed.

Bcfg2.Server.Plugin.helpers.bind_info(entry, metadata, infoxml=None, default=None)[source]¶

Bind the file metadata in the given Bcfg2.Server.Plugin.helpers.InfoXML object to the given entry.

Parameters:	entry (lxml.etree._Element) – The abstract entry to bind the info to metadata (Bcfg2.Server.Plugins.Metadata.ClientMetadata) – The client metadata to get info for infoxml (Bcfg2.Server.Plugin.helpers.InfoXML) – The info.xml file to pull file metadata from default (dict) – Default metadata to supply when the info.xml file does not include a particular attribute
Returns:	None
Raises :	`Bcfg2.Server.Plugin.exceptions.PluginExecutionError`

Bcfg2.Server.Plugin.helpers.default_path_metadata()[source]¶

Get the default Path entry metadata from the config.

Returns:	dict of metadata attributes and their default values

Bcfg2.Server.Plugin.helpers.get_template_data(entry, metadata, template, default=<object object at 0x3b1edb0>)[source]¶: Get all template variables for a text (i.e., Cfg) template

Bcfg2.Server.Plugin.helpers.get_xml_template_data(structfile, metadata, default=<object object at 0x3b1edb0>)[source]¶: Get all template variables for an XML template

Bcfg2.Server.Plugin.helpers.removecomment(stream)[source]¶

A Genshi filter that removes comments from the stream. This function is a generator.

Parameters:	stream (genshi.core.Stream) – The Genshi stream to remove comments from
Returns:	tuple of `(kind, data, pos)`, as when iterating through a Genshi stream

class Bcfg2.Server.Plugin.base.Debuggable(name=None)¶

Bases: object

Mixin to add a debugging interface to an object

Parameters:	name (string) – The name of the logger object to get. If none is supplied, the full name of the class (including module) will be used.

debug_log(message, flag=None)¶

Log a message at the debug level.

Parameters:	message (string) – The message to log flag (bool) – Override the current debug flag with this value
Returns:	None

set_debug(debug)¶

Explicitly enable or disable debugging.

Returns:	bool - The new value of the debug flag

toggle_debug()¶

Turn debugging output on or off.

Returns:	bool - The new value of the debug flag

Plugin Exceptions¶

Exceptions for Bcfg2 Server Plugins.

exception Bcfg2.Server.Plugin.exceptions.MetadataConsistencyError[source]¶

Bases: exceptions.Exception

This error gets raised when metadata is internally inconsistent.

exception Bcfg2.Server.Plugin.exceptions.MetadataRuntimeError[source]¶

Bases: exceptions.Exception

This error is raised when the metadata engine is called prior to reading enough data, or for other Bcfg2.Server.Plugin.interfaces.Metadata errors.

exception Bcfg2.Server.Plugin.exceptions.PluginExecutionError[source]¶

Bases: exceptions.Exception

Error raised in case of Bcfg2.Server.Plugin.base.Plugin execution errors.

exception Bcfg2.Server.Plugin.exceptions.PluginInitError[source]¶

Bases: exceptions.Exception

Error raised in cases of Bcfg2.Server.Plugin.base.Plugin initialization errors.

exception Bcfg2.Server.Plugin.exceptions.SpecificityError[source]¶

Bases: exceptions.Exception

Thrown by Bcfg2.Server.Plugin.helpers.Specificity in case of filename parse failure.

exception Bcfg2.Server.Plugin.exceptions.ValidationError[source]¶

Bases: exceptions.Exception

Exception raised by Bcfg2.Server.Plugin.interfaces.StructureValidator and Bcfg2.Server.Plugin.interfaces.GoalValidator objects

Bcfg2 Plugin development¶

Bcfg2 Plugins¶

Server Plugin Types¶

Plugin¶

Interfaces¶

Exposing XML-RPC Functions¶

Invalidating Caches¶

Tracking Execution Time¶

Bcfg2.Server.Statistics¶

Plugin Helper Classes¶

Plugin Exceptions¶

See Also¶

Table Of Contents

Previous topic

Next topic

This Page

param core:	The Bcfg2.Server.Core initializing the plugin
type core:	Bcfg2.Server.Core
raises:	`OSError` if adding a file monitor failed; `Bcfg2.Server.Plugin.exceptions.PluginInitError` on other errors

Navigation

Bcfg2 Plugin development¶

Bcfg2 Plugins¶

Server Plugin Types¶

Plugin¶

Interfaces¶

Exposing XML-RPC Functions¶

Invalidating Caches¶

Tracking Execution Time¶

Bcfg2.Server.Statistics¶

Plugin Helper Classes¶

Plugin Exceptions¶

See Also¶

Table Of Contents

Previous topic

Next topic

This Page

Quick search

Navigation