Cfg Handler Development

The Cfg plugin offers multiple handlers to handle different entries in different ways. Writing a new Cfg handler is a relatively simple way to add significant new features to Cfg.

Each new Cfg handler must be contained in its own module in Bcfg2.Server.Plugins.Cfg, and the module and class name must be identical. The name should start with Cfg, and should clearly indicate which of the handler types it is. A handler class may implement more than one handler type.

Cfg Handler Types

There are several different types of Cfg handlers. A new handler must inherit either from one of these classes, or from an existing handler.

class Bcfg2.Server.Plugins.Cfg.CfgGenerator(name, specific)[source]

Bases: Bcfg2.Server.Plugins.Cfg.CfgBaseFileMatcher

CfgGenerators generate the initial content of a file. Every valid Bcfg2.Server.Plugins.Cfg.CfgEntrySet must have at least one file handled by a CfgGenerator. Moreover, each CfgEntrySet must have one unambiguously best handler for each client. See Bcfg2.Server.Plugin.helpers.EntrySet for more details on how the best handler is chosen.

Parameters:
get_data(entry, metadata)[source]

get_data() returns the initial data of a file.

Parameters:
Returns:

string - the contents of the entry
class Bcfg2.Server.Plugins.Cfg.CfgCreator(fname)[source]

Bases: Bcfg2.Server.Plugins.Cfg.CfgBaseFileMatcher

CfgCreator handlers create static entry data if no generator was found to generate any. A CfgCreator runs at most once per client, writes its data to disk as a static file, and is not called on subsequent runs by the same client.

Parameters:name (string) – The full path to the file
CfgInfo.__specific__ = False

Whether or not the files handled by this handler are permitted to have specificity indicators in their filenames – e.g., .H_client.example.com or .G10_foogroup. By default CfgInfo handlers do not allow specificities

create_data(entry, metadata)[source]

Create new data for the given entry and write it to disk using Bcfg2.Server.Plugins.Cfg.CfgCreator.write_data().

Parameters:
Returns:

string - The contents of the entry
Raises:

Bcfg2.Server.Plugins.Cfg.CfgCreationError
get_filename(host=None, group=None, prio=0, ext='')[source]

Get the filename where the new data will be written. If host is given, it will be host-specific. It will be group-specific if group and prio are given. If neither host nor group is given, the filename will be non-specific. In general, this will be called as:

self.get_filename(**self.get_specificity(metadata))
Parameters:
  • host (bool) – The file applies to the given host
  • group (string) – The file applies to the given group
  • prio (string) – The file has the given priority relative to other objects that also apply to the same group. group must also be specified.
  • ext – An extension to add after the specificity (e.g., ‘.crypt’, to signal that an encrypted file has been created)
Returns:

string - the filename
write_data(data, host=None, group=None, prio=0, ext='')[source]

Write the new data to disk. If host is given, it is written as a host-specific file, or as a group-specific file if group and prio are given. If neither host nor group is given, it will be written as a non-specific file. In general, this will be called as:

self.write_data(data, **self.get_specificity(metadata))
Parameters:
  • data (string) – The data to write
  • host (bool) – The data applies to the given host
  • group (string) – The data applies to the given group
  • prio (string) – The data has the given priority relative to other objects that also apply to the same group. group must also be specified.
  • ext – An extension to add after the specificity (e.g., ‘.crypt’, to signal that an encrypted file has been created)
Returns:

None
Raises:

Bcfg2.Server.Plugins.Cfg.CfgCreationError
class Bcfg2.Server.Plugins.Cfg.CfgFilter(name, specific)[source]

Bases: Bcfg2.Server.Plugins.Cfg.CfgBaseFileMatcher

CfgFilters modify the initial content of a file after it has been generated by a Bcfg2.Server.Plugins.Cfg.CfgGenerator.

Parameters:
modify_data(entry, metadata, data)[source]

Return new data for the entry, based on the initial data produced by the Bcfg2.Server.Plugins.Cfg.CfgGenerator.

Parameters:
  • entry (lxml.etree._Element) – The entry to filter data for. entry should not be modified in-place.
  • metadata (Bcfg2.Server.Plugins.Metadata.ClientMetadata) – The client metadata to filter data for.
  • data (string) – The initial contents of the entry produced by the CfgGenerator
Returns:

string - the new contents of the entry
class Bcfg2.Server.Plugins.Cfg.CfgInfo(fname)[source]

Bases: Bcfg2.Server.Plugins.Cfg.CfgBaseFileMatcher

CfgInfo handlers provide metadata (owner, group, paranoid, etc.) for a file entry.

Parameters:name (string) – The full path to the file
__specific__ = False

Whether or not the files handled by this handler are permitted to have specificity indicators in their filenames – e.g., .H_client.example.com or .G10_foogroup. By default CfgInfo handlers do not allow specificities

bind_info_to_entry(entry, metadata)[source]

Assign the appropriate attributes to the entry, modifying it in place.

Parameters:
Returns:

None
class Bcfg2.Server.Plugins.Cfg.CfgVerifier(name, specific)[source]

Bases: Bcfg2.Server.Plugins.Cfg.CfgBaseFileMatcher

CfgVerifier handlers validate entry data once it has been generated, filtered, and info applied. Validation can be enabled or disabled in the configuration. Validation can apply to the contents of an entry, the attributes on it (e.g., owner, group, etc.), or both.

Parameters:
verify_entry(entry, metadata, data)[source]

Perform entry contents. validation.

Parameters:
  • entry (lxml.etree._Element) – The entry to validate data for. entry should not be modified in-place. Info attributes have been bound to the entry, but the text data has not been set.
  • metadata (Bcfg2.Server.Plugins.Metadata.ClientMetadata) – The client metadata to validate data for.
  • data (string) – The contents of the entry
Returns:

None
Raises:

Bcfg2.Server.Plugins.Cfg.CfgVerificationError

Cfg Handler Base Class

In addition to the interfaces defined above, all Cfg handlers inherit from CfgBaseFileMatcher.

class Bcfg2.Server.Plugins.Cfg.CfgBaseFileMatcher(name, specific)[source]

Bases: Bcfg2.Server.Plugin.helpers.SpecificData

CfgBaseFileMatcher is the parent class for all Cfg handler objects.

param name:The full path to the file
type name:string
param specific:A Bcfg2.Server.Plugin.helpers.Specificity object describing what clients this file applies to.
type specific:Bcfg2.Server.Plugin.helpers.Specificity
__basenames__ = []

The set of filenames handled by this handler. If __basenames__ is the empty list, then the basename of each CfgEntrySet is used – i.e., the name of the directory that contains the file is used for the basename.

__extensions__ = []

This handler only handles files with the listed extensions (which come after CfgBaseFileMatcher.__specific__ indicators).

__ignore__ = []

This handler ignores all files with the listed extensions. A file that is ignored by a handler will not be handled by any other handlers; that is, a file is ignored if any handler ignores it. Ignoring a file is not simply a means to defer handling of that file to another handler.

__specific__ = True

Whether or not the files handled by this handler are permitted to have specificity indicators in their filenames – e.g., .H_client.example.com or .G10_foogroup.

__priority__ = 0

Cfg handlers are checked in ascending order of priority to see if they handle a given event. If this explicit priority is not set, then CfgPlaintextGenerator.CfgPlaintextGenerator would match against nearly every other sort of generator file if it comes first. It’s not necessary to set __priority__ on handlers where CfgBaseFileMatcher.__specific__ is False, since they don’t have a potentially open-ended regex

deprecated = False

Flag to indicate a deprecated handler.

experimental = False

Flag to indicate an experimental handler.

classmethod get_regex(basenames)[source]

Get a compiled regular expression to match filenames (not full paths) that this handler handles.

Parameters:basename (string) – The base filename to use if CfgBaseFileMatcher.__basenames__ is not defined (i.e., the name of the directory that contains the files the regex will be applied to)
Returns:compiled regex
classmethod handles(event, basename=None)[source]

Return True if this handler handles the file described by event. This is faster than just applying CfgBaseFileMatcher.get_regex() because it tries to do non-regex matching first.

Parameters:
Returns:

bool - True if this handler handles the file listed in the event, False otherwise.
classmethod ignore(event, basename=None)[source]

Return True if this handler ignores the file described by event. See CfgBaseFileMatcher.__ignore__ for more information on how ignoring files works.

Parameters:
Returns:

bool - True if this handler handles the file listed in the event, False otherwise.

Cfg Exceptions

Cfg handlers may produce the following exceptions:

exception Bcfg2.Server.Plugins.Cfg.CfgVerificationError[source]

Bases: exceptions.Exception

Raised by Bcfg2.Server.Plugins.Cfg.CfgVerifier.verify_entry() when an entry fails verification

exception Bcfg2.Server.Plugins.Cfg.CfgCreationError[source]

Bases: exceptions.Exception

Raised by Bcfg2.Server.Plugins.Cfg.CfgCreator.create_data() when data creation fails

In addition, Cfg handlers may produce the following base plugin exceptions:

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.

Existing Cfg Handlers

Generators

class Bcfg2.Server.Plugins.Cfg.CfgPlaintextGenerator.CfgPlaintextGenerator(name, specific)[source]

Bases: Bcfg2.Server.Plugins.Cfg.CfgGenerator

CfgPlaintextGenerator is a Bcfg2.Server.Plugins.Cfg.CfgGenerator that handles plain text (i.e., non-templated) Cfg files. The base Generator class already implements this functionality, so CfgPlaintextGenerator doesn’t need to do anything itself.

Parameters:
class Bcfg2.Server.Plugins.Cfg.CfgGenshiGenerator.CfgGenshiGenerator(fname, spec)[source]

Bases: Bcfg2.Server.Plugins.Cfg.CfgGenerator

The CfgGenshiGenerator allows you to use the Genshi templating system to generate Cfg files.

Parameters:
get_data(entry, metadata)[source]

get_data() returns the initial data of a file.

Parameters:
Returns:

string - the contents of the entry
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
pyerror_re = <_sre.SRE_Pattern object>

Error-handling in Genshi is pretty obtuse. This regex is used to extract the first line of the code block that raised an exception in a Genshi template so we can provide a decent error message that actually tells the end user where an error occurred.

class Bcfg2.Server.Plugins.Cfg.CfgCheetahGenerator.CfgCheetahGenerator(fname, spec)[source]

Bases: Bcfg2.Server.Plugins.Cfg.CfgGenerator

The CfgCheetahGenerator allows you to use the Cheetah templating system to generate Cfg files.

Parameters:
get_data(entry, metadata)[source]

get_data() returns the initial data of a file.

Parameters:
Returns:

string - the contents of the entry
settings = {'useStackFrames': False}

Cheetah.Template.Template compiler settings

class Bcfg2.Server.Plugins.Cfg.CfgJinja2Generator.CfgJinja2Generator(fname, spec)[source]

Bases: Bcfg2.Server.Plugins.Cfg.CfgGenerator

The CfgJinja2Generator allows you to use the Jinja2 templating system to generate Cfg files.

Parameters:
get_data(entry, metadata)[source]

get_data() returns the initial data of a file.

Parameters:
Returns:

string - the contents of the entry
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
class Bcfg2.Server.Plugins.Cfg.CfgEncryptedGenerator.CfgEncryptedGenerator(fname, spec)[source]

Bases: Bcfg2.Server.Plugins.Cfg.CfgGenerator

CfgEncryptedGenerator lets you encrypt your plaintext Cfg files on the server.

get_data(entry, metadata)[source]

get_data() returns the initial data of a file.

Parameters:
Returns:

string - the contents of the entry
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
class Bcfg2.Server.Plugins.Cfg.CfgEncryptedGenshiGenerator.CfgEncryptedGenshiGenerator(fname, spec)[source]

Bases: Bcfg2.Server.Plugins.Cfg.CfgGenshiGenerator.CfgGenshiGenerator

CfgEncryptedGenshiGenerator lets you encrypt your Genshi Cfg files on the server

class Bcfg2.Server.Plugins.Cfg.CfgEncryptedCheetahGenerator.CfgEncryptedCheetahGenerator(fname, spec)[source]

Bases: Bcfg2.Server.Plugins.Cfg.CfgCheetahGenerator.CfgCheetahGenerator, Bcfg2.Server.Plugins.Cfg.CfgEncryptedGenerator.CfgEncryptedGenerator

CfgEncryptedCheetahGenerator lets you encrypt your Cheetah Cfg files on the server

Parameters:
get_data(entry, metadata)[source]

get_data() returns the initial data of a file.

Parameters:
Returns:

string - the contents of the entry
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
class Bcfg2.Server.Plugins.Cfg.CfgEncryptedJinja2Generator.CfgEncryptedJinja2Generator(fname, spec)[source]

Bases: Bcfg2.Server.Plugins.Cfg.CfgJinja2Generator.CfgJinja2Generator, Bcfg2.Server.Plugins.Cfg.CfgEncryptedGenerator.CfgEncryptedGenerator

CfgEncryptedJinja2Generator lets you encrypt your Jinja2 Cfg files on the server

Parameters:
get_data(entry, metadata)[source]

get_data() returns the initial data of a file.

Parameters:
Returns:

string - the contents of the entry
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
class Bcfg2.Server.Plugins.Cfg.CfgAuthorizedKeysGenerator.CfgAuthorizedKeysGenerator(fname)[source]

Bases: Bcfg2.Server.Plugins.Cfg.CfgGenerator, Bcfg2.Server.Plugin.helpers.StructFile

The CfgAuthorizedKeysGenerator generates authorized_keys files based on an XML specification of which SSH keypairs should granted access.

Parameters:
get_data(entry, metadata)[source]

get_data() returns the initial data of a file.

Parameters:
Returns:

string - the contents of the entry
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

Creators

class Bcfg2.Server.Plugins.Cfg.CfgPrivateKeyCreator.CfgPrivateKeyCreator(fname)[source]

Bases: Bcfg2.Server.Plugins.Cfg.XMLCfgCreator

The CfgPrivateKeyCreator creates SSH keys on the fly.

create_data(entry, metadata)[source]

Create data for the given entry on the given client

Parameters:
Returns:

string - The private key data
class Bcfg2.Server.Plugins.Cfg.CfgPublicKeyCreator.CfgPublicKeyCreator(fname)[source]

Bases: Bcfg2.Server.Plugins.Cfg.CfgCreator, Bcfg2.Server.Plugin.helpers.StructFile

The CfgPublicKeyCreator creates SSH public keys on the fly. It is invoked by CfgPrivateKeyCreator.CfgPrivateKeyCreator to handle the creation of the public key, and can also call CfgPrivateKeyCreator.CfgPrivateKeyCreator to trigger the creation of a keypair when a public key is created.

create_data(entry, metadata)[source]

Create new data for the given entry and write it to disk using Bcfg2.Server.Plugins.Cfg.CfgCreator.write_data().

Parameters:
Returns:

string - The contents of the entry
Raises:

Bcfg2.Server.Plugins.Cfg.CfgCreationError
encryption = False

No text content on any tags, so encryption support disabled

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

Info Handlers

class Bcfg2.Server.Plugins.Cfg.CfgDefaultInfo[source]

Bases: Bcfg2.Server.Plugins.Cfg.CfgInfo

Bcfg2.Server.Plugins.Cfg.Cfg handler that supplies a default set of file metadata

Parameters:name (string) – The full path to the file
bind_info_to_entry(entry, _)[source]

Assign the appropriate attributes to the entry, modifying it in place.

Parameters:
Returns:

None
class Bcfg2.Server.Plugins.Cfg.CfgInfoXML.CfgInfoXML(path)[source]

Bases: Bcfg2.Server.Plugins.Cfg.CfgInfo

CfgInfoXML handles info.xml files for Cfg

Parameters:name (string) – The full path to the file
CfgInfo.__specific__ = False

Whether or not the files handled by this handler are permitted to have specificity indicators in their filenames – e.g., .H_client.example.com or .G10_foogroup. By default CfgInfo handlers do not allow specificities

bind_info_to_entry(entry, metadata)[source]

Assign the appropriate attributes to the entry, modifying it in place.

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

Verifiers

class Bcfg2.Server.Plugins.Cfg.CfgExternalCommandVerifier.CfgExternalCommandVerifier(name, specific)[source]

Bases: Bcfg2.Server.Plugins.Cfg.CfgVerifier

Invoke an external script to verify Cfg file contents

Parameters:
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
verify_entry(entry, metadata, data)[source]

Perform entry contents. validation.

Parameters:
  • entry (lxml.etree._Element) – The entry to validate data for. entry should not be modified in-place. Info attributes have been bound to the entry, but the text data has not been set.
  • metadata (Bcfg2.Server.Plugins.Metadata.ClientMetadata) – The client metadata to validate data for.
  • data (string) – The contents of the entry
Returns:

None
Raises:

Bcfg2.Server.Plugins.Cfg.CfgVerificationError

Other Cfg Objects

These other objects comprise the remainder of the Cfg plugin, and are included for completeness.

class Bcfg2.Server.Plugins.Cfg.CfgEntrySet(basename, path, entry_type)[source]

Bases: Bcfg2.Server.Plugin.helpers.EntrySet

Handle a collection of host- and group-specific Cfg files with multiple different Cfg handlers in a single directory.

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.

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 entry metadata to the entry with the best CfgInfo handler

Parameters:
Returns:

None
build_filename(specific)[source]

Create a filename for pulled file data

entry_init(event, hdlr)[source]

Handle the creation of a file on the filesystem and the creation of a Cfg handler object in this CfgEntrySet to track it.

Parameters:
  • event (Bcfg2.Server.FileMonitor.Event) – An event that applies to a file handled by this CfgEntrySet
  • hdlr (class) – The Cfg handler class to be used to create an object for the file described by event
Returns:

None
Raises:

Bcfg2.Server.Plugin.exceptions.SpecificityError
get_handlers(metadata, handler_type)[source]

Get all handlers of the given type for the given metadata.

Parameters:
Returns:

list of Cfg handler classes
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 entry_init() or the appropriate child handler object.

Parameters:event (Bcfg2.Server.FileMonitor.Event) – An event that applies to a file handled by this CfgEntrySet
Returns:None
list_accept_choices(entry, metadata)[source]

return a list of candidate pull locations

set_debug(debug)[source]

Explicitly enable or disable debugging.

Returns:bool - The new value of the debug flag
write_update(specific, new_entry, log)[source]

Write pulled data to the filesystem

class Bcfg2.Server.Plugins.Cfg.Cfg(core)[source]

Bases: Bcfg2.Server.Plugin.helpers.GroupSpool, Bcfg2.Server.Plugin.interfaces.PullTarget

The Cfg plugin provides a repository to describe configuration file contents for clients. In its simplest form, the Cfg repository is just a directory tree modeled off of the directory tree on your client machines.

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

es_child_cls

alias of Bcfg2.Server.Plugin.helpers.SpecificData

es_cls

alias of CfgEntrySet

has_generator(entry, metadata)[source]

Return True if the given entry can be generated for the given metadata; False otherwise

Parameters:
Returns:

bool
Cfg.get_cfg()

Get the Bcfg2.Server.Plugins.Cfg.Cfg plugin object created by the Bcfg2 core. This is provided so that the handler objects can access it as necessary, since the existing Bcfg2.Server.Plugin.helpers.GroupSpool and Bcfg2.Server.Plugin.helpers.EntrySet classes have no facility for passing it otherwise.