Changes between Version 5 and Version 6 of TracNav


Ignore:
Timestamp:
03/16/06 11:43:01 (16 years ago)
Author:
desai
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • TracNav

    v5 v6  
    33[[TracNav]] 
    44 
    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. 
     9 
     10== Bcfg2 Server == 
     11 
     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: 
     19 
     20{{{ 
     21[server] 
     22repository = /var/db/bcfg 
     23structures = Bundler,Base 
     24generators = SSHbase,Cfg,Pkgmgr,Svcmgr,TCheetah 
     25metadata = /var/db/bcfg/etc 
     26 
     27[statistics] 
     28sendmailpath = /usr/sbin/sendmail 
     29 
     30[communication] 
     31protocol = xmlrpc/ssl 
     32password = verysecret 
     33key = /usr/share/ssl/bcfg2/server-key.pem 
     34 
     35[components] 
     36bcfg2 = https://server:6789 
     37}}} 
     38 
     39This file should be owned by user and group root and readable only by 
     40user root, as it contains a shared secret password. 
     41 
     42== Bcfg2 Abstractions == 
     43 
     44=== Bcfg2 Elements === 
     45 
     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 
     49elements: 
     50Package 
     51A package for the given system (RPM. Deb, ebuild, etc) 
     52ConfigFile 
     53A config file 
     54Service 
     55A service to start or stop on boot (usually kept in /etc/init.d) 
     56Directory 
     57A directory that should be present 
     58SymLink 
     59A symbolic link that should be present 
     60 
     61=== Bcfg2 Bundles === 
     62 
     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: 
     66 
     67{{{ 
     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> 
     74</Bundle> 
     75}}} 
     76 
     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. 
     85 
     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. 
     91 
     92=== Bcfg2 Groups === 
     93 
     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: 
     97 
     98{{{ 
     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> 
     106}}} 
     107 
     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. 
     113 
     114=== Bcfg2 Profiles === 
     115 
     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: 
     122 
     123{{{ 
     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> 
     132}}} 
     133 
     134Here we can see that a mail-server is actually made up of a couple of 
     135Bundles and a few Groups as well. 
     136 
     137== Bcfg2 Plugins == 
     138 
     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? 
     170 
     171=== Bcfg2 Repository === 
     172 
     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- 
     176www.uchicago.edu but the package repository is kept on ci- 
     177nfs.uchicago.edu 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. 
     182 
     183==== Metadata/ Directory ==== 
     184 
     185The Metadata/ directory contains several configuration files that 
     186dictate how to start generating a configuration for a host. 
     187 
     188===== Metadata/groups.xml ===== 
     189 
     190The groups.xml contains Group and Profile definitions. Here's a very 
     191basic Metadata/groups.xml: 
     192 
     193{{{ 
     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  ... 
     205</Groups> 
     206}}} 
     207 
     208===== Metadata/clients.xml ===== 
     209 
     210The Metadata/clients.xml file contains the mappings of Profiles to 
     211clients. A sample from this file is: 
     212 
     213{{{ 
     214<Clients version="3.0"> 
     215  <Client profile="backup-server" pingable="Y" pingtime="0" name="ci-backup.uchicago.edu"/> 
     216  <Client profile="console-server" pingable="Y" pingtime="0" 
     217name="ci-con.uchicago.edu"/> 
     218  <Client profile="kerberos-master" pingable="Y" pingtime="0" 
     219name="ci-kdc.uchicago.edu"/> 
     220  <Client profile="mail-server" pingable="Y" pingtime="0" name="ci- 
     221mail.uchicago.edu"/> 
     222  ... 
     223</Clients> 
     224}}} 
     225 
     226==== Bundler/ Directory ==== 
     227 
     228The Bundler/ directory is where all the Bcfg2 bundle XML files are 
     229kept. These are the files described above. 
     230 
     231==== Pkgmgr/ Directory ==== 
     232 
     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: 
     236 
     237{{{ 
     238$ ls Pkgmgr/ 
     239ci-backup.uchicago.edu.xml 
     240linux-fedora-core-4-noarch-updates.xml 
     241linux-fedora-core-4-x86-updates.xml 
     242linux-fedora-core-4-x86.xml 
     243linux-rhel-client-ws-4-noarch-udpates.xml 
     244linux-rhel-client-ws-4-x86.xml 
     245linux-rhel-client-ws-4-x86-updates.xml 
     246linux-rhel-client-ws-4-x86_64.xml 
     247linux-rhel-client-ws-4-x86_64-updates.xml 
     248linux-rhel-server-as-4-noarch-updates.xml 
     249linux-rhel-server-as-4-x86-updates.xml 
     250linux-rhel-server-as-4-x86.xml 
     251linux-rhel-server-es-4-noarch-updates.xml 
     252linux-rhel-server-es-4-x86.xml 
     253linux-rhel-server-es-4-x86-updates.xml 
     254}}} 
     255 
     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: 
     260 
     261{{{ 
     262<PackageList uri='http://ci-www.uchicago.edu/media/rhel-server-as-4/x86/install/RedHat/RPMS' 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> 
     274</PackageList> 
     275}}} 
     276 
     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- 
     294backup.uchicago.edu.xml. 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. 
     297 
     298==== Svcmgr/ Directory ===== 
     299 
     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: 
     304 
     305{{{ 
     306<Services priority='0'> 
     307  <Service name="kudzu" status="off"/> 
     308  <Group name="mail-server"> 
     309    <Service name="postfix" status="on"/> 
     310  </Group> 
     311  ... 
     312</Services> 
     313}}} 
     314 
     315==== Base/ Directory ==== 
     316 
     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: 
     321 
     322{{{ 
     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> 
     335</Base> 
     336}}} 
     337 
     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: 
     341 
     342{{{ 
     343$ ls Base/ 
     344linux-fedora-core-4-x86.xml 
     345linux-rhel-client-ws-4-x86_64.xml 
     346linux-rhel-client-ws-4-x86.xml 
     347linux-rhel-server-as-4-x86.xml 
     348linux-rhel-server-es-4-x86.xml 
     349}}} 
     350 
     351==== Cfg/ Directory ==== 
     352 
     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. 
     361 
     362===== Specialized Configuration Files ===== 
     363 
     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 foo.example.com needed a special version your motd directory 
     369might look like: 
     370 
     371{{{ 
     372$ ls Cfg/etc/motd 
     373motd 
     374motd.H_foo.example.com 
     375}}} 
     376 
     377Now when you run Bcfg2 on foo.example.com 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: 
     383 
     384{{{ 
     385$ ls Cfg/etc/motd 
     386motd 
     387motd.G01_mail-server 
     388motd.H_foo.example.com 
     389}}} 
     390 
     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 
     393foo.example.com is also a membere of the mail-server Group? Bcfg2 
     394will use the highest priority, most specific file. So foo.example.com 
     395will always get motd.H_foo.example.com. If you have specialized 
     396versions for multiple groups, the priorities you assign come in to 
     397play. Let's say we have the following: 
     398 
     399{{{ 
     400$ ls Cfg/etc/motd 
     401motd 
     402motd.G01_mail-server 
     403motd.G02_web-server 
     404motd.H_foo.example.com 
     405}}} 
     406 
     407If you have a host, not foo.example.com, 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. 
     410 
     411=== Deltas === 
     412 
     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. 
     426 
     427==== Cat Files ==== 
     428 
     429Continuing our example for cat files, we would first create a file 
     430named motd.G01_file-server.cat. The .cat suffix designates that the 
     431file is a diff. We would then edit that file and add the following 
     432line: 
     433 
     434{{{ 
     435+This is a file server 
     436}}} 
     437 
     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: 
     447 
     448{{{ 
     449motd 
     450motd.G01_web-server 
     451motd.G01_mail-server.cat 
     452motd.G02_file-server.cat 
     453motd.H_foo.example.cat 
     454}}} 
     455 
     456If our machine isn't foo.example.com then here's what would happen: 
     457 
     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 motd.G01_mail-server.cat delta to the 
     461motd.G01_web-server base file. It is the least specific delta. 
     462Bcfg2 would then apply the motd.G02_file-server.cat delta to the 
     463result of the delta before it. 
     464If our machine is foo.example.com then here's what would happen: 
     465 
     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 motd.H_foo.example.com.cat delta to the 
     469motd.G01_web-server base file. 
     470The reason the other deltas aren't applied to foo.example.com is 
     471because a .H_ delta is more specific than a .G##_ delta. Bcfg2 
     472applies all the deltas at the most specific level. 
     473 
     474== Bcfg2 Reports == 
     475 
     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. 
     479 
     480=== Report Configuration === 
     481 
     482Report generation requires the etc/report-configuration.xml and looks 
     483something like: 
     484 
     485{{{ 
     486<Reports> 
     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> 
     497 
     498    <Machine name='.*'/> 
     499  </Report> 
     500</Reports> 
     501}}} 
     502 
     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 
     513reports. 
     514 
     515=== Report Scripts === 
     516 
     517Reports are generated by the /usr/sbin/StatReports script.  
     518!GenerateHostInfo 
     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. 
     524 
     525=== Report Interface === 
     526 
     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: 
     531 
     532{{{ 
     533<IfModule mod_alias.c> 
     534        Alias /bcfg2 /var/db/bcfg/www 
     535</IfModule> 
     536 
     537<Directory "/var/db/bcfg/www"> 
     538        Options Indexes FollowSymLinks 
     539        AllowOverride None 
     540        Order deny,allow 
     541        Allow from all 
     542</Directory> 
     543}}}