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.

set_debug(debug)[source]

Explicitly enable or disable debugging.

Returns:bool - The new value of the debug flag
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:
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:
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:

  1. 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.
  2. 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:
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:
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:
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:
Returns:

None
merge_additional_groups(imd, groups)[source]

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

Parameters:
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:
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:
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:
Returns:

None
process_statistics(metadata, data)[source]

Process the given XML statistics data for the specified client.

Parameters:
Returns:

None
run()[source]

Method representing the thread’s activity.

You may override this method in a subclass. The standard run() method invokes the callable object passed to the object’s constructor as the target argument, if any, with sequential and keyword arguments taken from the args and kwargs arguments, respectively.

start_threads()[source]

Start this plugin’s threads after daemonization.

Returns:None
Raises:Bcfg2.Server.Plugin.exceptions.PluginInitError
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>

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

Whether or not the backend database must acquire a thread lock before writing, because it does not allow multiple threads to write.

_use_db

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
set_debug(debug)

Explicitly enable or disable debugging.

Returns:bool - The new value of the debug flag
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.

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(_, 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.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>

Only track and include files whose names (not paths) match this compiled regex.

set_debug(debug)[source]

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.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:

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:
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:
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>

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
set_debug(debug)[source]

Explicitly enable or disable debugging.

Returns:bool - The new value of the debug flag
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:
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:
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

alias of __builtin__.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
set_debug(debug)[source]

Explicitly enable or disable debugging.

Returns:bool - The new value of the debug flag
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:
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:
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:
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:
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
set_debug(debug)

Explicitly enable or disable debugging.

Returns:bool - The new value of the debug flag
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:
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>

Only track and include files whose names (not paths) match this compiled regex.

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.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:
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>)[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>)[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)[source]

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)[source]

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)[source]

Explicitly enable or disable debugging.

Returns:bool - The new value of the debug flag
toggle_debug()[source]

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