Writing Bcfg2 Specification

Bcfg2 specifications are logically divided in to three areas:

• Metadata
• Abstract
• Literal

The metadata portion of the configuration assigns a client to its profile group and to its non-profile groups. The profile group is assigned in Metadata/clients.xml and the non profile group assignments are in Metadata/groups.xml.

The group memberships contained in the metadata are then used to constuct an abstract configuration for the client. An abstract configuration for a client identifies the configuration entities (packages, configuration files, service, etc) that a client requires, but it does not identify them explicitly. For instance an abstract configuration may identify that a client needs the Bcfg2 package with

<Package name="bcfg2"/>

but this does not explicitly identify that an RPM package version 0.9.2 should be loaded from http://rpm.repo.server/bcfg2-0.9.2-0.1.rpm. The abstract configuration is defined in the XML configuration files for the Bundler plugin.

A combination of a clients metadata (group memberships) and abstract configuration is then used to generate the clients literal configuration. For instance the above abstract configuration entry may generate a literal configuration of

<Package name='bcfg2' version='0.9.2-0.1' type='yum'/>

A clients literal configuration is generated by a number of plugins that handle the different configuration entities.

Dynamic Groups

Dynamic groups are likewise complex, and are covered on their own [wiki:DynamicGroups page]

Abstract Configuration (Structures)

A clients Abstract Configuration is the inventory of configuration entities that should be installed on a client. The Bundler plugin usually provides the abstract configuration.

The plugin Bundler builds descriptions of interrelated configuration entities. These are typically used for the representation of services, or other complex groups of entities.

Configuration Entity Types

Entities in the abstract configuration (and correspondingly in the literal configuration) can have one of several types. In the abstract configuration, each of these entities only has a tag and the name attribute set.

The types of Configuration Entities that maybe assigned to the abstract configuration can be seen at Configuration Entries.

An example of each entity type is below.

<Package name='bcfg2'/>
<Path name='/etc/bcfg2.conf'/>
<Service name='ntpd'/>
<Action name='action_name'/>

Writing Bundles

Bundles consist of a set of configuration entities. These entities are grouped together due to a configuration-time interdependency. Basic services tend to be the simplest example of these. They normally consist of

• some software package(s)
• some configuration files
• an indication that some service should be activated

If any of these pieces are installed or updated, all should be rechecked and any associated services should be restarted.

All files in the Bundles/ subdirectory of the repository are processed. Each bundle must be defined in its own file:

# ls Bundler
Glide3.xml
LPRng.xml
Tivoli-backup.xml
Tivoli.xml
a2ps.xml
abiword.xml
account.xml
adsm-client.xml
amihappy.xml
apache-basic.xml
apache.xml
apache2-basic.xml
apt-proxy.xml
at.xml
atftp-server.xml
atftp.xml
....

When packages in a bundle are verified by the client toolset, the Paths included in the same bundle are taken into consideration. That is, a package will not fail verification from a Bcfg2 perspective if the package verification only failed because of configuration files that are defined in the same bundle.

The following is an annotated copy of a bundle:

<Bundle>
  <Path glob='/etc/ssh/*'/>
  <Group name='rpm'>
    <Package name='openssh'/>
    <Package name='openssh-askpass'/>
    <Service name='sshd'/>
    <Group name='fedora' >
       <Group name='fc4' negate='true'>
         <Package name='openssh-clients'/>
       </Group>
       <Package name='openssh-server'/>
    </Group>
  </Group>
  <Group name='deb'>
    <Package name='ssh'/>
    <Service name='ssh'/>
  </Group>
</Bundle>

In this bundle, most of the entries are common to all systems. Clients in group “deb” get one extra package and service, while clients in group “rpm” get two extra packages and an extra service. In addition, clients in group “fedora” and group “rpm” get one extra package entries, unless they are not in the fc4 group, in which case, they get an extra package. Notice that this file doesn’t describe which versions of these entries that clients should get, only that they should get them. (Admittedly, this example is slightly contrived, but demonstrates how group entries can be used in bundles)

Group	Entry
all	/etc/ssh/*
rpm	Package openssh
rpm	Package openssh-askpass
rpm	Service sshd
rpm and fedora	Package openssh-server
rpm and fedora and not fc4	Package openssh-clients
deb	Package ssh
deb	Service ssh

Bundle Tag

complexType BundleType

Attributes:

Name	Description	Values	Required	Default
description	Freeform description of the bundle.	string	No	None
independent	If set to true, indicates that the bundle is a collection of independent entries, and that service restarts and modified actions should not be performed. See Bundle “Magic” for more.	true | false	No	None
lax_decryption	Override the global lax_decryption setting in bcfg2.conf.	true | false	No	None
name	Deprecated. The name of the bundle. If present, this must match the bundle filename, minus the extension. Specifying the name explicitly is deprecated.	string	No	None
origin	URL of master version (for common repo)	anyURI	No	None
revision	Master version control revision.	string	No	None
version	Bundle schema version.	string	No	None

Attribute groups:

• py:genshiAttrs

As mentioned above the Configuration Entity Tags may only have the name attribute in Bundle definitions.

Group and Client Tags

complexType BundlerGroupType

A BundlerGroupType is a tag used to provide logic. Child entries of a BundlerGroupType tag only apply to machines that match the condition specified – either membership in a group, or a matching client name. negate can be set to negate the sense of the match.

Attributes:

Name	Description	Values	Required	Default
name	The group name	string	Yes	None
negate	Negate the sense of this group or client; i.e., entries within this tag are only used on clients that are not members of the group, or that have hostnames that do not match.	string	No	None

Attribute groups:

• py:genshiAttrs

An abstract group may contain any of the Configuration Entity types and other groups.

Literal Configuration (Generators)

A Generator is a Bcfg2 piece of code that is run to generate the literal configuration for a host using a combination of the hosts metadata and abstract configuration.

A Generator can take care of a particular configuration element. Any time this element is requested by the client, the server dynamically generates it either by crunching data and creating new information or by reading a file off of disk and passes it down to the client for installation.