Bcfg2 Configuration

This page documents the configuration and maintenance of the bcfg2 configuration management system used in the Fedora ARM build farm.

Packages

The current version of bcfg2 in the Fedora 15 yum repository is 1.1.3, which is an out of date version. The current version 1.2.X has been built for later versions of Fedora. Verified and tested Fedora 15 RPMS are located here:

Client: http://bahamas.proximity.on.ca/bcfg2/bcfg2-1.2.1-2.fc15.noarch.rpm

Server: http://bahamas.proximity.on.ca/bcfg2/bcfg2-server-1.2.1-2.fc15.noarch.rpm

Server Side

The server is the element of bcfg2 that performs most of the heavy lifting. It is responsible for defining what is the appropriate configuration and hosts all of the necessary files. It can also handle package management across clients.

Server Install

To install the server component of bcfg2, run the command:

yum -y install bcfg2-server

Server Setup

The configuration file is generated by running the command:

bcfg2-server init

However, at the time of this writing, there is a bug where the program will not run unless given extra text at the end of the command. This bug manifests itself by outputting a line of text and then retuning to the prompt. To get around this, simply run:

 bcfg2-server init $HOSTNAME 

The output should prompt you for values, however the default values are sufficient, though when prompted for the OS type, select 1 for "Redhat/Fedora/RHEL/RHAS/Centos". It should look something like this:

[jordan@hongkong ~]$ sudo bcfg2-admin init
[sudo] password for jordan:
Store bcfg2 configuration in [/etc/bcfg2.conf]:
Location of bcfg2 repository [/var/lib/bcfg2]:
Directory /var/lib/bcfg2 exists. Overwrite? [y/N]:y
Input password used for communication verification (without echoing; leave blank for a random):
What is the server's hostname [hongkong.proximity.on.ca]:
Input the server location [https://hongkong.proximity.on.ca:6789]:
Input base Operating System for clients:
1: Redhat/Fedora/RHEL/RHAS/Centos
2: SUSE/SLES
3: Mandrake
4: Debian
5: Ubuntu
6: Gentoo
7: FreeBSD
: 1
Generating a 2048 bit RSA private key
..........................................................................................................+++
.........................................+++
writing new private key to '/etc/bcfg2.key'
-----
Signature ok
subject=/C=US/ST=Illinois/L=Argonne/CN=hongkong.proximity.on.ca
Getting Private key
Repository created successfuly in /var/lib/bcfg2

After this is done, a directory structure under /var/lib/bcfg2 should exist, as well as the files /etc/bcfg2.conf, /etc/bcfg2.cert and /etc/bcfg2.key.

Configuring Groups

The configuration for groups is in /var/lib/bcfg2/Metadata/groups.xml. A group's definition can include configuration elements and other groups nested within it. Clients associated with groups inherit elements from child groups associated with that group as well. For example, given a group called "FileServer" which has a nested group "Fedora", any client associated with the "FileServer' group would also inherit configuration options from "Fedora".

Groups can be assigned attributes in their declarations. There are several, but the the main ones this documentation is concerned with are name, public and default. The name attribute is self explanatory, declaring the name of the group and must be included in any group declaration. When public is set to true, clients can add themselves to groups without being declared in the clients.xml file. Default simply indicates a default group that clients who are unassociated to other groups automatically belong to.

The following illustrates the example above:

<Groups>
   <Group name="FileServer>
       <Group name="Fedora" />
   </Group>

   <Group name="Fedora" profile="true" default="true" />
</Groups>

Configuring Clients

Clients are defined in /var/lib/bcfg2/Metadata/clients.xml. For every client you wish to administer through bcfg2, you must have an entry in this file. Entries follow this format:

<Client profile='GROUP NAME' pingable='Y' pingtime='0' name='FULLY QUALIFIED DOMAIN NAME' />

The profile determines the primary group that this client is associated with and ultimately defines how it will be configured. The name indicates the fully qualified domain name. The FQDN must resolve to the IP address of the host and the IP must resolve to the FQDN. If the resolving is done through a hosts file, the name given to a client must match the first entry in the host file for that IP address. The pingable and pingtime entries should be left as default and are not covered in this documentation.

Bundles

Bundles are a means of defining configuration elements to be pushed out to clients. Bundles are defined in /var/lib/bcfg2/Bundler as XML files, the contents of which are the name of the file and where it located on the server. Bundle declarations for files must also contain a declaration of the file path. For example: if there is a bundle used named "hosts" which contains the file "/etc/hosts", there would need to be a file present in /var/lib/bcfg2/Bundler called "hosts.xml". The contents of such a file are as follows:

<Bundle name='BUNDLE NAME' version='2.0'>
  <Path name='/PATH/TO/FILE' />
</Bundle>

Bundles can also be used to define packages that must be installed. The use of this feature will be discussed later in this documentation.

Bundles are assigned in groups.xml file using the following entry placed within the group tags:

<bundle name="BUNDLE NAME" />

Client Side

The client in a bcfg2 instance is simply responsible for accessing the configuration details on the remote server and changing the host so that it conforms with those details.

Client Install

At the time of this document's creation, there is one missing dependency of bcfg2 in the Fedora ARM repository. The packages themselves have been built in Koji, but are waiting on signing and final release. The location of this dependency, python-lxml is:

• For ARMv5TEL/ARMv7l builders: http://arm.koji.fedoraproject.org/packages/python-lxml/2.3/1.fc15/armv5tel/python-lxml-2.3-1.fc15.armv5tel.rpm
• For ARMv7HL builders: http://arm.koji.fedoraproject.org/packages/python-lxml/2.3/1.fc15/armv7hl/python-lxml-2.3-1.fc15.armv7hl.rpm

After installing this dependency, clients can be installed by running

yum -y install bcfg2 

Client Configuration

Bcfg2 requires the use of a key generated by the initialization of the server to run.

The bcfg2 service can be initialized via command line arguments, but the preferred way of of handling this is to use a configuration file. A configuration file should be created at /etc/bcfg2.conf and contain the following entries:

[communication]
protocol = xmlrpc/ssl
password = XXXXXX  #This should be set as the password from the server
ca = /etc/bcfg2.crt #Copied from the server


[components]
bcfg2 = https://hongkong.proximity.on.ca:6789 # This should be the fqdn and port of the server component.

Client Update

To force an update from the server, use the command:

bcfg2 -vq 

To ensure that a client is up to date, use the command:

bcfg2 -vqn 

Sources

http://docs.bcfg2.org/server/plugins/grouping/metadata.html

http://docs.bcfg2.org/server/plugins/generators/cfg.html#cfg

http://docs.bcfg2.org/dev/server/plugins/generators/tcheetah.html

http://docs.bcfg2.org/server/plugins/generators/tgenshi/index.html