View source for Bcfg2 Configuration

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

==Fedora 15 RPMs==
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:

<pre>yum -y install bcfg2-server</pre>

===Server Configuration===

The configuration file is generated by running the command:

<pre>bcfg2-server init</pre>

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:

<pre> bcfg2-server init $HOSTNAME </pre>


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:

<pre>
[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
</pre>


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:
<pre>
<Groups>
   <Group name="FileServer>
       <Group name="Fedora" />
   </Group>

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

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

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

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
<pre>yum -y install bcfg2 </pre>

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

<pre>
[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.
</pre>

===Client Update===

To force an update from the server, use the command:
<pre>bcfg2 -vq </pre>

To ensure that a client is up to date, or to test a configuration without changing anything on the client use the command:
<pre>bcfg2 -vqn </pre>


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

* '''[[#Bundler|Bundler]]''' :This is the location that Bundles are defined.
* '''[[#Cfg|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]]''': 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]]''': TCheetah is a templating system which allows the dynamic generation of host files.
* '''[[#Packages|Packages]]''': The packages plugin has enhanced YUM support, so it will be used in lieu of the Pkgmgr plugin
* '''[[#Probes|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:
<pre>
<bundle name="BUNDLE NAME" />
</pre>

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

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

The file path provided is mapped to a folder in the Cfg folder structure.  This will be discussed further in the [[#Cfg|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:

<pre>
<Bundle name='BUNDLE NAME' version='2.0'>
  <Package name="<PACKAGE_NAME>" version="<VERSION_NUMBER>" />
</Bundle>
</pre>

Package bundles require additional configuration in the form of a sources.xml file and appropriate groups and probes.  This will be discussed in the [[#Packages|Packages]] section.

===Cfg===
The Cfg plugin is the primary means of pushing out configuration files to clients.  The Cfg directory follows a hierarchy similar to a standard root file system.  When a [[#File Bundles| file bundle]] is declared, a folder structure matching that path must exist under /var/lib/bcfg2/Cfg.  The configuration file itself.  For example, a bundle which pushes out an /etc/hosts file would require the directory /var/lib/bcfg2/Cfg/etc/hosts to be created and a file called hosts to be present under that folder.


This seems counter-intuitive, but the reasoning behind it is that multiple instances of that configuration file may exist.  Using the hosts example, there may be a specific host file needed for a File server and another one needed for a web server.  From a file system perspective, they both exist under /etc/hosts, but they have different content.  By having all possible /etc/hosts files existing under the directory /var/lib/bcfg2/etc/hosts/, we are able to more easily define which file goes to which group.  However, even in the case where only one such variation of the file exists, that file still needs to be placed in the appropriate directory.

An example of the said directory structure is as follows:

<pre>
/var/lib/bcfg2/Cfg
└── etc
    ├── hosts
    │   ├── hosts # The actual Hosts file
    └── init.d
        └── koji-config
            └── koji-config # The actual koji-config file
</pre>

The two ways of ensuring that files of the same name but of differing content are sent to the correct clients are G (Group) files and H (Host) files.

====G Files====
G files specify a file meant for a specific group.  G files are used by creating a file called <filename>.GXX_<groupname> in the directory where the file would normally reside.  The XX value should be replaced with a priority number between 1 and 99.  The priority indicates which file would take precedence if a specific host exists in multiple groups and is attempting to determine which file it should get.


====H Files====

H file specify a file meant for a specific host.   H files are used by creating a file called <filename>.H_<FQDN>.  H files should only be files who's content are totally unique to that file, such as certificates or keys.  If there are minor changes required, such as usernames, hostnames or the like the better option is to use a templating system such as [[#TCheetah|TCheetah]].  H files always take priority over G files.

====Info Files====
If you wish bcfg2 to push out executable scripts, or have specific permissions applied to files, the directory that contains the file must have a :info file.

Common entries for :info files include:
* Owner:  the file owner
** Syntax-> owner: apache
* Group: The group ownership for the file
** Syntax-> group: libvirt
* Perms: File permissions
** Syntax-> perms: 755

===Metadata===

Metadata is where the clients.xml and groups.xml files reside.  These have already been discussed previously in this documentation and this entry is here only for completeness' sake.

===Packages===

The default package management system for bcfg2 is PkgMgr, but the Packages plugin has enhanced yum support, so it will be used in it's stead.   To enable the Packages plugin, add the entry "Packages" to the plugins line in /etc/bcfg2.conf.  The folder "/var/lib/bcfg2/Packages" must also be present.

The Packages Plugin as implemented on the Armory Build farm has three prerequisites:
* A sources.xml file
* An architecture [[#Probes|probe]]
* [[#Package Bundles|Package Bundles]]


=====sources.xml=====
The sources.xml file must be located under "/var/lib/bcfg2/Packages" and is used to define the repositories that a certain group should query for their packages.  A sample of such a file is as follows:

<pre>
<Sources>
<Group name="fedora-15">
  <Source type="yum" rawurl="http://mirror.chpc.utah.edu/pub/fedora-secondary/releases/15/Everything/armhfp/os/Packages">
    <Arch>armhfp</Arch>
  </Source>
 
 
  <Source type="yum" rawurl="http://mirror.chpc.utah.edu/pub/fedora-secondary/releases/15/Everything/arm/os/Packages">
    <Arch>arm</Arch>
  </Source>
</Group>
</Sources>
</pre>

The Group tags indicate which group this repository declaration is for.  In order to use the repositories defined within this group, a client must be a member of said group.  

The  source tag has the declarations of type and rawurl.   Type can be defined as apt, yum, or any other number of package management systems, but as the Armory is comprised of only Fedora machines, yum is selected.   The "rawurl" attribute points to the URI of the the RPM files in a given repository.

The Arch tag indicates a specific repository for an architecture.  This tag is used in conjuction with "Magic Groups" in order to ensure client machines get packages specifically for their architecture.

====Magic Groups and Probes====

Bcfg2 uses the concept of Magic Groups, which "Magically" identify a client's operating system, architecture, and other attributes.  These groups are usually not declared in groups.xml, and are usually used by having [[#Probes|probes]] identify and associate a client with these groups.

====packages.conf====
This file is normally not needed, but in the case of the Armory build farm, it's presence grant's an administrative advantage.  As the Armory consists of machines of only one operating system, OS magic groups are not needed.   The contents of this file are:

<pre>
[global]
magic_groups=0
</pre>

===Probes===
The Probes plugin allows information to be collected from a client before bcfg2 generates a configuration for it.  This information can be used by [[#TCheetah|templating systems]] or by [[#Magic Groups and Probes| magic groups]] to customized configuration for a given client.  To make use of the Probes plugin, add the entry "Probes" to the Plugins section of "/etc/bcfg2.conf".


Probes should be placed under /var/lib/bcfg2/Probes and are nothing more than simple shell scripts.  An example probe which probes the architecture of an ARM machine is as follows:

<pre>
#!/bin/bash

barch=$(uname -a | sed 's/\./\n/g' | grep ^arm)

if echo $barch | grep h > /dev/null  ; then echo "group: armhfp" ; else echo "group: arm"; fi

</pre>

===TCheetah===
TCheetah is a python based templating system that can be used in bcfg2.   To enable TCheetah to be used in bcfg2, add the entry "Metadata,TCheetah" to the end of the plugins line in /etc/bcfg2.conf on the server.  This will enable the TCheetah plugin and the Metadata plugin, which allows TCheetah to access elements of the client's Metadata.

The main purpose of TCheetah is to enable dynamic file content to be generated based off of client details, say if a particular configuration file needs a hostname.   The /var/lib/bcfg2/TCheetah directory uses a similar structure to the [[#Cfg|Cfg]] plugin, and can use [[#G Files|G]] and [[#H Files|H]] files.  However, the template files must be named template.  TCheetah can also use [[#Info Files| info files]].

The contents of the files themselves are similar to configuration files, however there are a number of variables that can be used in the files themselves.   These variables all start with "$self.metadata" and are discussed in greater detail in the official documentation.  The more commonly used ones are:

* Hostname: the client's hostname
* profile: shows the primary group this client is associated with
* groups: shows all groups the client is associated with

The templating system reads anything starting with a $ as a variable and anything starting with a # as a comment.  A standard escape (\) will allow TCheetah to process any script variables or comments as plaintext.

=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



[[Category:Fedora ARM Secondary Architecture]] [[Category:SOP]]