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.
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, or to test a configuration without changing anything on the client use the command:
bcfg2 -vqn
The BCFG2 Configuration Management System
Overview
The BCFG2 configuration management system uses a folder hierarchy to define configuration elements. At the end of the server setup process, the root of "/var/lib/bcfg2" contains a number of folders, which are associated with a plugin defined in /etc/bcfg2.conf.
- Template:'''Bundler''' :This is the location that Bundles are defined.
- Cfg: This is where actual configuration files are located. The Cfg folder hierarchy is a standard that defines the folder layouts for any other plugin that create or provide configuration files.
- Metadata: Metadata is where the definitions for clients(clients.xml) and groups (groups.xml) are located.
- Pkgmgr: This folder is used for the Pkgmgr plugin. The Packages plugin is used in this configuration so this folder is not used.
- Rules: This folder is not used.
- SSHbase: This folder is not used.
In addition, this documentation covers additional plugins that are used for the Build farm:
- TCheetah: TCheetah is a templating system which allows the dynamic generation of host files.
- Packages: The packages plugin has enhanced YUM support, so it will be used in lieu of the Pkgmgr plugin
- Probes: This is used in conjunction with the packages plugin to identify architeccture.
Bundler
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 define the name of the bundle and what it configures.
Bundles are assigned to groups in the groups.xml file using the following entry placed within the group tags:
<bundle name="BUNDLE NAME" />
File Bundles
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>
The file path provided is mapped to a folder in the Cfg folder structure. This will be discussed further in the Cfg section of this documentation.
Package Bundles
Bundles can also be used to define packages that must be installed. This requires additional configuration which will be discussed in the Packages section. The format for that is as follows:
<Bundle name='BUNDLE NAME' version='2.0'> <Package name="<PACKAGE_NAME>" version="<VERSION_NUMBER>" /> </Bundle>