Changes between Version 5 and Version 6 of TracNav

03/16/06 11:43:01 (17 years ago)



  • TracNav

    v5 v6  
    5 * Foo 
     5Configuration management is a necessary piece of maintaining many 
     6machines and diverse architectures. The ultimate goal of 
     7configuration management is to make machines as consistent, easily 
     8manageable, and up to date as possible. This document describes a typical installation of bcfg2. 
     10== Bcfg2 Server == 
     12Each deployment will have a central bcfg2 server. 
     13This machine runs 
     14the Bcfg2 server daemon as well as keeps the Bcfg2 configuration 
     15repository as well as serving package data when needed. The server uses XML-RPC 
     16for its communications and this channel is encrypted using SSL. The 
     17Bcfg2 server and client get the connection information from the /etc/ 
     18bcfg2.conf configuration file. An example /etc/bcfg2.conf looks like: 
     22repository = /var/db/bcfg 
     23structures = Bundler,Base 
     24generators = SSHbase,Cfg,Pkgmgr,Svcmgr,TCheetah 
     25metadata = /var/db/bcfg/etc 
     28sendmailpath = /usr/sbin/sendmail 
     31protocol = xmlrpc/ssl 
     32password = verysecret 
     33key = /usr/share/ssl/bcfg2/server-key.pem 
     36bcfg2 = https://server:6789 
     39This file should be owned by user and group root and readable only by 
     40user root, as it contains a shared secret password. 
     42== Bcfg2 Abstractions == 
     44=== Bcfg2 Elements === 
     46Creating a specification for a host is a modular process. A 
     47specification is built of several pieces and at the base are 
     48configuration elements. The following are all valid configuration 
     51A package for the given system (RPM. Deb, ebuild, etc) 
     53A config file 
     55A service to start or stop on boot (usually kept in /etc/init.d) 
     57A directory that should be present 
     59A symbolic link that should be present 
     61=== Bcfg2 Bundles === 
     63Bundles are the simplest reusable configuration blocks. A Bcfg2 
     64Bundle is a collection of Elements that are tightly related. Bundles 
     65are written in XML. An example Bundle might be one for syslog: 
     68<Bundle name="syslog" version="2.0"> 
     69  <Group name="rhel"> 
     70    <ConfigFile name="/etc/syslog.conf"/> 
     71    <Package name="sysklogd"/> 
     72    <Service name="syslog"/> 
     73  </Group> 
     77Here we can see that for the Group rhel, the syslog Bundle contains a 
     78ConfigFile element /etc/syslog.conf, a Package element sysklogd, and 
     79a Service element syslog. This defines a relationship between all 
     80these elements, so that if one of these changes, examination of all 
     81the elements should be taken more closely. For example, say you 
     82update the /etc/syslog.conf file. Once it's been updated the syslog 
     83service should be restarted. Bcfg2 takes care of this automatically 
     84for you. 
     86Bundles should be fairly discrete and simple and their relationship 
     87should be tight. We wouldn't want to put the sshd service in the 
     88syslog Bundle even though sshd does use syslog. Restarting sshd when / 
     89etc/syslog.conf changes or when a new sysklogd package comes out 
     90doesn't make sense. 
     92=== Bcfg2 Groups === 
     94Groups are the next abstraction up from Bundles. Groups can contain 
     95Bundles, other Groups, or simply nothing at all. An example Group 
     96might be for a mail-server: 
     99  <Group profile='false' name='server'> 
     100    <Bundle name='kerberos-client'/> 
     101    <Group name='backup-client'/> 
     102    <Group name='base'/> 
     103    <Group name='ldap-client'/> 
     104    <Group name='serial-console'/> 
     105  </Group> 
     108Here we see that the server Group is actually made up of a Bundle and 
     109several other Groups. Groups are used throughout Bcfg2. They can be 
     110used in Bundles to help distinguish which elements a host gets 
     111depending on its group membership. They are also used in the Pkgmgr 
     112plugin, the Svcmgr plugin, and the Cfg plugin. 
     114=== Bcfg2 Profiles === 
     116The highest level of abstraction is that of Profiles. A Profile is a 
     117special Group and is then mapped to a host. A host can have one and 
     118only one profile mapped to it. Note that a Profile can also contain 
     119other Profiles, but these Profiles aren't mapped to the host, they 
     120are simple associated with the host as a Group. A mail-server Profile 
     121might look like: 
     124  <Group profile='true' public='false' name='mail-server'> 
     125    <Bundle name='mail-server'/> 
     126    <Bundle name='mailman-server'/> 
     127    <Group name='apache-server'/> 
     128    <Group name='linux-rhel-server-as-4-x86'/> 
     129    <Group name='nfs-client'/> 
     130    <Group name='server'/> 
     131  </Group> 
     134Here we can see that a mail-server is actually made up of a couple of 
     135Bundles and a few Groups as well. 
     137== Bcfg2 Plugins == 
     139Generators are a special case for Bcfg2. A Generator is a piece of 
     140code that is run to generate Bcfg2 Elements automatically for a host. 
     141To explain this the best way it's best to look at an example. 
     142If you run SSH, one of the most tedious processes is keeping track of 
     143SSH host keys. If you have to rebuild an existing machine you want to 
     144keep its existing keys so that user's don't get warnings that the key 
     145has changed. When you build a brand new machine, host keys are 
     146automatically created for a machine. And you probably also want to 
     147manage the global known_hosts file to contain all the host keys for 
     148your machines. This can all be done by hand or even by copying each 
     149host's key into the Cfg repository and hand updating the known_hosts 
     150file, but it could easily be automated. Enter Generators. 
     151With a Generator you can have it so the it takes care of the 
     152management of the particular ConfigFile elements such as /etc/ssh/ 
     153known_hosts and the host keys. What would happen is when a client 
     154contacts the Bcfg2 server and requests those ConfigFile elements 
     155handled by the Generator, the Generator will take care of auto- 
     156generation of new host keys for a host or giving a host the host key 
     157that it had before. On top of that, if a new host key is created and 
     158added to the repository, the Generator will automatically update the 
     159known_hosts file with the new key and make it available for all the 
     160hosts to install so that they automatically have the proper key for 
     161the new host. And here's the kicker. Let's say a machine is 
     162compromised. You have to rebuild the machine, but in this case you 
     163don't want it to get the same host key and you have to remove the 
     164host key out of all the other machine's known_hosts file. All you 
     165have to do is remove the compromised key out of the repository and 
     166rebuild the machine. When the machine runs Bcfg2 again, a new key 
     167will be generated for the host and the known_hosts file will be 
     168updated to have the new key and remove the old compromised key. 
     169Pretty slick huh? 
     171=== Bcfg2 Repository === 
     173The Bcfg2 repository is just a collection of directories and files 
     174that direct the Bcfg2 server how to build configurations for hosts. 
     175The majority of the repository is kept in /var/db/bcfg on ci- but the package repository is kept on ci- and NFS exported. The package repository is 
     178automounted at /autonfs/media, for the original installation media, 
     179and /autonfs/updates, for updated packages. Within the central Bcfg2 
     180repository there are several directories that contain configuration 
     181parameters for establishing a paprticular configuration for a host. 
     183==== Metadata/ Directory ==== 
     185The Metadata/ directory contains several configuration files that 
     186dictate how to start generating a configuration for a host. 
     188===== Metadata/groups.xml ===== 
     190The groups.xml contains Group and Profile definitions. Here's a very 
     191basic Metadata/groups.xml: 
     194<Groups version='3.0'> 
     195  ... 
     196  <Group profile='true' public='false' name='mail-server'> 
     197    <Bundle name='mail-server'/> 
     198    <Bundle name='mailman-server'/> 
     199    <Group name='apache-server'/> 
     200    <Group name='linux-rhel-server-as-4-x86'/> 
     201    <Group name='nfs-client'/> 
     202    <Group name='server'/> 
     203  </Group> 
     204  ... 
     208===== Metadata/clients.xml ===== 
     210The Metadata/clients.xml file contains the mappings of Profiles to 
     211clients. A sample from this file is: 
     214<Clients version="3.0"> 
     215  <Client profile="backup-server" pingable="Y" pingtime="0" name=""/> 
     216  <Client profile="console-server" pingable="Y" pingtime="0" 
     218  <Client profile="kerberos-master" pingable="Y" pingtime="0" 
     220  <Client profile="mail-server" pingable="Y" pingtime="0" name="ci-"/> 
     222  ... 
     226==== Bundler/ Directory ==== 
     228The Bundler/ directory is where all the Bcfg2 bundle XML files are 
     229kept. These are the files described above. 
     231==== Pkgmgr/ Directory ==== 
     233The Pkgmgr/ directory keeps the XML files that define what packages 
     234are available for a host or image and where to find those packages. 
     235Here's an example of the files: 
     238$ ls Pkgmgr/ 
     256Here we can see a pattern of files. Looking at the names of these 
     257files you can make a pretty good guess as to what they contain. 
     258Let's take a look at what the contents of one of these files, linux- 
     259rhel-server-as-4-x86.xml, might look like: 
     262<PackageList uri='' type='rpm' priority='0'> 
     263  <Group name='linux-rhel-server-as-4-x86'> 
     264    <Package file='4Suite-1.0-3.i386.rpm'/> 
     265    <Package file='Canna-3.7p3-7.EL4.i386.rpm'/> 
     266    <Package file='Canna-devel-3.7p3-7.EL4.i386.rpm'/> 
     267    <Package file='Canna-libs-3.7p3-7.EL4.i386.rpm'/> 
     268    <Package file='ElectricFence-2.2.2-19.i386.rpm'/> 
     269    <Package file='FreeWnn-1.10pl020-5.i386.rpm'/> 
     270    <Package file='FreeWnn-devel-1.10pl020-5.i386.rpm'/> 
     271    <Package file='FreeWnn-libs-1.10pl020-5.i386.rpm'/> 
     272    ... 
     273  </Group> 
     277Here you can see that the data is encapsulated in a PackageList which 
     278describes the URI of the files described, the type of package, and a 
     279priority of the files. The priority is used to decide which specific 
     280file to use when there are multiple files that could be used for a 
     281particular host. The highest priority file is the one that is used. 
     282Using this system, you can have a file that contains all the Packages 
     283from the original installation, linux-rhel-server-as-x86.xml in our 
     284case, and then create a new file that contains updates that are made 
     285available afterwards, linux-rhel-server-as-x86-updates.xml and linux- 
     286rhel-server-as-noarch-updates.xml in our case. You simply make the 
     287priority of the update Packages higher and they will be used instead 
     288of the original installation Packages. 
     289The names of the XML files have no special meaning to Bcfg2; they are 
     290simply named so it's easy for the admin to know what the contents 
     291hold. All Packages could be kept in a single file if you so desired. 
     292Bcfg2 simply uses the Groups in the files and priorities to determine 
     293how to assign Packages to a host. You may notice the file ci- Its Packages have a higher priority than the 
     295update Packages. This is because that particular host requires 
     296special Packages that are older than the ones available in the updates. 
     298==== Svcmgr/ Directory ===== 
     300The Svcmgr directory is responsible for defining the state of 
     301Services. Like the Pkgmgr directory, the Svcmgr directory can contain 
     302multiple files to allow the administrator to divide the definitions 
     303of services up. Here's a simple example: 
     306<Services priority='0'> 
     307  <Service name="kudzu" status="off"/> 
     308  <Group name="mail-server"> 
     309    <Service name="postfix" status="on"/> 
     310  </Group> 
     311  ... 
     315==== Base/ Directory ==== 
     317The Base directory is responsible for defining the base config for 
     318all hosts of a given Group. The majority of the elements are 
     319Packages, but you can have Services, ConfigFiles, Directories, and 
     320SymLinks as well. Here's an example: 
     323<Base > 
     324  <Group name='linux-rhel-server-as-4-x86'> 
     325    <ConfigFile name='/etc/group'/> 
     326    <ConfigFile name='/etc/inittab'/> 
     327    <ConfigFile name='/etc/passwd'/> 
     328    <ConfigFile name='/etc/securetty'/> 
     329    <ConfigFile name='/etc/shadow'/> 
     330    <ConfigFile name='/etc/updatedb.conf'/> 
     331    <ConfigFile name='/usr/bin/bu'/> 
     332    <Package name='4Suite'/> 
     333    ... 
     334  </Group> 
     338Like the Pkgmgr directory and the Svcmgr directory, the Base 
     339directory can contain multiple files and the appropriate file is 
     340chosen based on the Group membership: 
     343$ ls Base/ 
     351==== Cfg/ Directory ==== 
     353The Cfg is where all the actual ConfigFiles are kept. If you have a 
     354ConfigFile element listed in a Bundle you need to provide Bcfg with 
     355the actual configuration file to give to the host. The directory 
     356structure under the Cfg/ directory defines where the configuration 
     357file should be placed on the host machine relative to the / 
     358directory. For example, if you want to manage /etc/motd you would 
     359create the directory Cfg/etc/motd/ and then place the /etc/motd file 
     360in that directory. 
     362===== Specialized Configuration Files ===== 
     364Some hosts or Groups might need a different version of /etc/motd or 
     365might just need to add or remove lines from it. You can create 
     366specialized versions for a particular host by appending .H_ to the 
     367configuration file where <hostname is the fully qualified hostname. 
     368So if needed a special version your motd directory 
     369might look like: 
     372$ ls Cfg/etc/motd 
     377Now when you run Bcfg2 on it will get the specialized 
     378version and all other hosts will get the generic version. 
     379If you want specialized versions for a Group you would append .G##_ 
     380to the file where ## is a two digit number specifying priority and is 
     381the name of the Group. Continuing our example if we wanted to have a 
     382special motd for the mail-server Group we would have the following: 
     385$ ls Cfg/etc/motd 
     391Now if a host is a member of the mail-server Group it will get the 
     392specialized Group version of motd. Now what happens if is also a membere of the mail-server Group? Bcfg2 
     394will use the highest priority, most specific file. So 
     395will always get If you have specialized 
     396versions for multiple groups, the priorities you assign come in to 
     397play. Let's say we have the following: 
     400$ ls Cfg/etc/motd 
     407If you have a host, not, that is a member of both the 
     408mail-server and the web-server Groups, it will get the web-server 
     409version because it has a higher priority, 02 instead of 01. 
     411=== Deltas === 
     413Bcfg2 has finer grained control over how to deliver configuration 
     414files to a host. Let's say we have a Group named file-server. Members 
     415of this group need the exact same /etc/motd as all other hosts except 
     416they need one line added. We could copy motd to motd.G01_file-server, 
     417add the one line to the Group specific version and be done with it, 
     418but we're duplicating data in both files. What happens if we need to 
     419update the motd? We'll need to remember to update both files then. 
     420Here's where deltas come in. A delta is a small change to the base 
     421file. There are two types of deltas: cats and diffs. The cat delta 
     422simply adds or removes lines from the base file. The diff delta is 
     423more powerful since it can take a unified diff and apply it to the 
     424base configuration file to create the specialized file. Diff deltas 
     425should be used very sparingly. 
     427==== Cat Files ==== 
     429Continuing our example for cat files, we would first create a file 
     430named The .cat suffix designates that the 
     431file is a diff. We would then edit that file and add the following 
     435+This is a file server 
     438The + at the beggining of the file tells Bcfg2 that the line should 
     439be appended to end of the file. You can also start a line with - to 
     440tell Bcfg2 to remove that exact line wherever it might be in the file. 
     441How do we know what base file Bcfg2 will choose to use to apply a 
     442delta? The same rules apply as before: Bcfg2 will choose the highest 
     443priority, most specific file as the base and then apply deltas in the 
     444order of most specific and then increasing in priority. What does 
     445this mean in real life. Let's say our machine is a web server, mail 
     446server, and file server and we have the following configuration files: 
     456If our machine isn't then here's what would happen: 
     458Bcfg2 would choose motd.G01_web-server as the base file. It is the 
     459most specific base file for this host. 
     460Bcfg2 would apply the delta to the 
     461motd.G01_web-server base file. It is the least specific delta. 
     462Bcfg2 would then apply the delta to the 
     463result of the delta before it. 
     464If our machine is then here's what would happen: 
     466Bcfg2 would choose motd.G01_web-server as the base file. It is the 
     467most specific base file for this host. 
     468Bcfg2 would apply the delta to the 
     469motd.G01_web-server base file. 
     470The reason the other deltas aren't applied to is 
     471because a .H_ delta is more specific than a .G##_ delta. Bcfg2 
     472applies all the deltas at the most specific level. 
     474== Bcfg2 Reports == 
     476Bcfg2 has the ability to generate reports to make it easier to see at 
     477a glance the state of your environment. It can report via three 
     478methods: HTML web page, RSS feed, email. 
     480=== Report Configuration === 
     482Report generation requires the etc/report-configuration.xml and looks 
     483something like: 
     487  <Report name='Computation Institute' good='Y' modified='Y'> 
     488    <Delivery mechanism='www' type='nodes-digest'> 
     489      <Destination address='/var/db/bcfg/www/stats.html'/> 
     490    </Delivery> 
     491    <Delivery mechanism='rss' type='nodes-individual'> 
     492      <Destination address='/var/db/bcfg/www/stats.rss'/> 
     493    </Delivery> 
     494    <Delivery mechanism='mail' type='nodes-digest'> 
     495      <Destination address='[email protected]'/> 
     496    </Delivery> 
     498    <Machine name='.*'/> 
     499  </Report> 
     503This is a good example showcasing several of the report generation 
     504features. In this example we define a report names Computation 
     505Institute which includes good as well as bad nodes and those nodes 
     506that were modified in the last run. For this report there are three 
     507delivery mechanisms: www, rss, mail. Thee www mechanism is the HTML 
     508generation. The other two are pretty self explanatory. The last 
     509parameter is which machines to include in this report. This report 
     510includes all the machines that Bcfg2 knows about. here you can give a 
     511regular expression to narrow down which machines are reported for. 
     512Refer to the Bcfg2 documentation for more detail on the configuring 
     515=== Report Scripts === 
     517Reports are generated by the /usr/sbin/StatReports script.  
     519gathers the data about the given hosts and writes out etc/hostinfo.xml.  
     520!StatReports reads the etc/hostinfo.xml and generates 
     521the reports based on etc/report-configuration.xml. !StatReports will  
     522automatically run !GenerateHostInfo if it has not run within 24 hours.  
     523!StatReports is usually run nightly from cron. 
     525=== Report Interface === 
     527For the www and rss mechanisms, you need to define a way to get to 
     528the reports generated. The CI reports are stored in /var/db/bcfg/www 
     529and we need to define an Apache Alias to access it. /etc/httpd/conf.d/ 
     530bcfg2.conf defines the Apache configuration: 
     533<IfModule mod_alias.c> 
     534        Alias /bcfg2 /var/db/bcfg/www 
     537<Directory "/var/db/bcfg/www"> 
     538        Options Indexes FollowSymLinks 
     539        AllowOverride None 
     540        Order deny,allow 
     541        Allow from all