[Top] [Contents] [Index] [ ? ]

GNU cfengine

Copyright © 1995/96/97/98/99/2000 Mark Burgess

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the author instead of in the original English.

This manual corresponds to CFENGINE Edition for version as last updated .


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1. AUTOMATED SYSTEM ADMINISTRATION

2. Overview  
3. Getting started  
4. More advanced concepts  
5. Designing a global system configuration  
6. Using cfengine as a front end for cron  
7. Cfengine and network services  
8. Security and cfengine  
Variable Index  
Concept Index  
FAQ Index  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2. Overview

In this manual the word "host" is used to refer to a single computer system -- i.e. a single machine which has a name termed its "hostname".

2.1 What is cfengine and who can use it?  
2.2 Site configuration  the problem
2.3 Key Concepts  the solution
2.4 Functionality  an advertisement


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.1 What is cfengine and who can use it?

Cfengine is a tool for setting up and maintaining BSD and System-5-like operating system optionally attached to a TCP/IP network. You can think of cfengine as a very high level language--much higher level than Perl or shell: a single statement can result in many hundreds of operations being performed on multiple hosts. Cfengine is good at performing a lot of common system administration tasks, and allows you to build on its strengths with your own scripts. You can also use it as a netwide front-end for cron. Once you have set up cfengine, you'll be free to use your time being like a human being, instead of playing R2-D2 with the system.

The main purpose of cfengine is to allow you to create a single, central system configuration which will define how every host on your network should be configured in an intuitive way. An interpreter runs on every host on your network and parses the master file (or file-set); the configuration of each host is checked against this file and then, if you request it, any deviations from the defined configuration are fixed automatically. You do not have to mention every host specifically by name in order to configure them: instead you can refer to the properties which distinguish hosts from one another. Cfengine uses a flexible system of "classes" which helps you to single out a specific group of hosts with a single statement.

Originally cfengine was conceived of as a tool only for the superuser, but during the course of its development it has become clear that it can also be used as a scripting language by ordinary users. It is a handy tool for tidying your old junk files and for making `watchdog' scripts to manage the access rights and permissions on your files when collaborating with other users. As a bonus it contains a text editing language which can be used to perform controlled edits of line-based text files.

Cfengine grew out of the need to control the accumulation of complex shell scripts used in the automation of key system maintenance at Oslo. There were very many scripts, written in shell and in perl, performing tasks such as file tidying, find-database updates, process checking and several other tasks. In a heterogeneous environment, shell-scripts work very poorly: shell commands have differing syntax across different operating systems, the locations and names of key files differ. In fact, the non-uniformity of unix was a major headache. Scripts were filled with tests to determine what kind of operating system they were being run on, to the point where they became so complicated an unreadable that no-one was quite sure what they did anymore. Other scripts were placed only on the systems where they were relevant, out of sight and out of mind. It quickly became clear that our dream solution would be to replace this proliferation of scripts by a single file containing everything to be checked on every host on the network. By defining a new language, this file could hide all of the tests by using classes (a generalized `switch/case' syntax) to label operations and improve the readability greatly. The gradual refinement of this idea resulted in the present day cfengine.

The remainder of this manual assumes that you know a little about BSD/System-5 systems and have everyday experience in using either the C-shell or the Bourne shell, or their derivatives. If you are experienced in system administration, you might like to skip the earlier chapters and turn straight to the example in the section Example configuration file of the Reference manual. This is the probably quickest way to learn cfengine for the initiated. If you are not so familiar with system administration and would like a more gentle introduction, then we begin here...


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.2 Site configuration

To the system administrator of a small network, with just a few workstations or perhaps even a single mainframe system, it might seem superfluous to create a big fuss about the administration of the system. After all, it's easy to `fix' things manually should any problems arise, making a link here, writing a script there and so on -- and its probably not even worth writing down what you did because you know that it will always be easy to fix next time around too... But networks have a tendency to expand and--before you know it--you have five different types of operating system and each type of system has to be configured in a special way, you have to make patches to each system and you can't remember whether you fixed that host on the other side of the building... Also, you discover fairly quickly that what you thought of as BSD or System 5 is not as standard as you thought and that none of your simple scripts that worked on one system work on the others without a considerable amount of hacking and testing. You try writing a script to help you automate the task, but end up with an enormous number of `if..then..else..' tests which make it hard to see what is really going on.

To manage a network with many different flavours of operating system, in a systematic way, what is needed is a more disciplined way of making changes which is robust against re-installation. After all, it would be tragic to spend many hours setting up a system by hand only to lose everything in an unfortunate disk-crash a week or even a year later when you have forgotten what you had to do. Upgrades of the operating system software might delete your carefully worked out configuration. What is needed is a separate record of all of the patches required on all of the systems on the network; a record which can be compared to the state of each host at any time and which a suitable engine can use to fix any deviations from that reference standard.

The idea behind cfengine is to focus upon a few key areas of basic system administration and provide a language in which the transparency of a configuration program is optimal. It eliminates the need for lots of tests by allowing you to organize your network according to "classes". From a single configuration file (or set of files) you can specify how your network should be configured -- and cfengine will then parse your file and carry out the instructions, warning or fixing errors as it goes.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.3 Key Concepts

Some of the important issues in system administration which cfengine can help with.

2.3.1 Control files  textfiles which configure
2.3.2 Network interface  ethernet parameters
2.3.3 Network File System (NFS) or distribution?  sharing resources
2.3.4 Name servers (DNS)  setting up a name service
2.3.5 Monitoring important files  permission and ownership
2.3.6 Making links  aliases


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.3.1 Control files

One of the endearing characteristics of BSD and system 5 systems is that they are configured through human-readable text files. To add a new user to the system you edit `/etc/passwd', to add a new disk you must edit `/etc/fstab' etc. Many applications are also configured with the help of text files. When installing a new system for the first time, or when changing updating the setup of an old system you are faced with having to edit lots of files. In some cases you will have to add precisely the same line to the same file on every system in your network as a change is made, so it is handy to have a way of automating this procedure so that you don't have to load every file into an editor by hand and make the changes yourself. This is one of the tasks which cfengine will automate for you.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.3.2 Network interface

Each host which you connect to an ethernet-based network running TCP/IP protocols must have a so-called `net interface'. This network interface must be configured before it will work. Normally one does this with the help of the ifconfig command. This can also be checked and configured automatically by cfengine.

Network configuration involves telling the interface hardware what the internet (IP) address of your system is, so that it knows which incoming `packets' of data to pay attention to. It involves telling the interface how to interpret the addresses it receives by setting the `netmask' for your network (see below). Finally you must tell it which dummy address is to be used for messages which are broadcast to all hosts on your network simultaneously (see the reference manual).

Cfengine's features are mainly meant for hosts which use static IP addresses, if you are using DHCP clients then you will not need the net configuration features.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.3.3 Network File System (NFS) or distribution?

Probably the first thing you are interested in doing with a network (after you've had your fill of the world wide web) is to make your files available to some or all hosts on the network, no matter where in your corporate empire (or university dungeon) you might be sitting. In other words, if you have a disk which is physically connected to host A, you would like to make the contents of that disk available to hosts B, C, D... etc. NFS (the network filesystem) does this for you. The process works by `filesystems'.

A filesystem is one partition of a disk drive -- or one unit of disk space which can be accessed by a single `logical device' `/dev/something'. To make a filesystem available to other hosts you have to do three things.

Only after all three of these have been done will a filesystem become available across the network. Cfengine will help you with the last two in a very transparent way. You could also use the text-editing facility in cfengine to edit the exports file, but there are other ways update the exports file using netgroups which we shall not go into here. If you are in doubt, look up the manual page on exports.

Some sites prefer to minimize the use of NFS filesystems, to avoid one machine being dependent on another. They prefer to make a local copy of the files on a remote machine instead. Traditionally programs like rdist have been used for this purpose. You may also use cfengine to copy files in this way, See section 7.2.1 Remote file distribution.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.3.4 Name servers (DNS)

There are two ways to specify addresses on the internet (called IP addresses). One is to use the textual address like `ftp.uu.net' and the other is to use the numerical form `192.48.96.9'. Alas, there is no one-to-one correspondence between the numerical addresses and the textual ones, thus a service is required to map one to the other.

The service is performed by one or more special hosts on the network called nameservers. Each host must know how to contact a nameserver or it will probably hang the first time you give it an IP address. You tell it how to contact a nameserver by editing the text-file `/etc/resolv.conf'. This file must contain the domain name for your domain and a list of possible nameservers which can be contacted, in order of priority. Because this is a special file which every host must have, you don't have to use the editing facilities in cfengine explicitly. You can just define the nameservers for each host in the cfengine file and cfengine will do the editing automatically. If you want to change the priority of nameservers later, or even change the list then a simple change of one or two lines in the configuration file will enable you to reconfigure every host on your network automatically without having to do any editing yourself!


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.3.5 Monitoring important files

Security is an important issue on any system. In the busy life of a system administrator it is not always easy to remember to set the correct access rights on every file and this can result in either a security breach or problems in accessing files.

A common scenario is that you, as administrator, fetch a new package using ftp, compile it and install it without thinking too carefully. Since the owner and permissions of the files in an ftp archive remains those of the program author, it often happens that the software is left lying around with the owner and permissions as set by the author of the program rather than any user-name on your system. The user-id of the author might be anybody on your system -- or perhaps nobody at all! The files should clearly be owned by root and made readable and unwritable to normal users.

Simple accidents and careless actions under stress could result in, say, the password file being writable to ordinary users. If this were the case, the security of the entire system would be compromised. Cfengine therefore allows you to monitor the permissions, ownership and general existence of files and directories and, if you wish, correct them or warn about them automatically.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.3.6 Making links

One of the difficulties with having so many different variations on the theme of BSD and system 5 based operating systems is that similar files are not always where you expect to find them. They have different names or lie in different directories. The usual solution to the problem is to make an alias for these files, or a pointer from one filename to another. The name for such an alias is a symbolic link.

It is often very convenient to make symbolic links. For example, you might want the sendmail configuration file `/etc/sendmail.cf' to be a link to a global configuration file, say,
 
`/usr/local/mail/etc/sendmail.cf'

on every single host on your network so that there is only one file to edit. If you had to make all of these links yourself, it would take a lifetime. Cfengine will make such a link automatically and check it each time it is run. You can also ask it to tidy up old links which have been left around and no longer point to existing files. If you reinstall your operating system later it doesn't matter because all your links are defined in your cfengine configuration file, recorded for all time. Cfengine won't forget it, and you won't forget it because the setup is defined in one central place.

Cfengine will also allow you to make hard links to regular files, but not other kinds of file. A hard link to a symbolic link, is the same as a hard link to the file the symbolic link points to.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.4 Functionality

The notes above give you a rough idea of what cfengine can be used for. Here is a summary of cfengine's capabilities.

How do you run cfengine? You can run it as a cron job, or you can run it manually. You may run cfengine scripts/programs as often as you like. Each time you run a script, the engine determines whether anything needs to be done -- if nothing needs to be done, nothing is done! If you use it to monitor and configure your entire network from a central file-base, then the natural thing is to run cfengine daily with the help of cron. (see the reference manual).


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3. Getting started

3.1 What you must have in a cfengine program  a skeleton cfengine program
3.2 Program structure  an overview
3.3 Optional features in cfengine  spices and conveniences
3.4 Invoking cfengine  from the command line
3.5 CFINPUTS environment variable  the cfengine search path
3.6 What to aim for  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.1 What you must have in a cfengine program

A cfengine configuration file for a large network can become long and complex so, before we get down to details, let's try to strip away the complexity and look only to the essentials.

Each cfengine program or configuration file is a list of declarations of items to be checked and perhaps fixed. You begin by creating a file called `cfengine.conf'. The simplest meaningful file you can create is something like this:

 
# Comment...
 
control:

  actionsequence = ( links )

links:

  /bin -> /usr/bin

The example above checks and makes (if necessary) a link from `/bin' to `/usr/bin'. Let's examine this example more closely. In a cfengine program:

In simple example above has three of the four types of object described above. The control: section of any program tells cfengine how to behave. In this example it adds the action links to the actionsequence. For links you could replace some other action. The essential point is that, if you don't have an action sequence, your cfengine program will do absolutely nothing! The action sequence is a list which tells cfengine what do to and in which order.

The links: section of the file tells cfengine that what follows is a number of links to be made. If you write this part of the file, but forget to add links to the actionsequence, then nothing will be done! You can add any number of links in this part of the file and they will all be dealt with in order when--and only when--you write links in the action sequence.

To summarize, you must have:

Now let's think a bit about how useful this short example program is. On a SunOS system, where the directory `/bin' is in fact supposed to be a link, such a check could be useful, but on some other system where `/bin' is a not a link but a separate directory, this would result in an error message from cfengine, telling you that `/bin' exists and is not a link. The lesson is that, if we want to use cfengine to make one single program which can be run on any host of any type, then we need some way of restricting the above link so that it only gets checked on SunOS systems. We can write the following:

 
# Comment...
 
control:

  actionsequence = ( links  )

links:

  sun4:: 

       /bin -> /usr/bin
       # other links

   osf::

       # other links

The names which have double colons after them are called classes and they are used to restrict a particular action so that it only gets performed if the host running the program is a member of that class. If you are familiar with C++, this syntax should make you think of classes definitions in C++. Classes works like this: the names above sun4, sun3, osf etc. are all internally defined by cfengine. If a host running, say, the OSF operating system executes the file it automatically becomes a member of the class osf. Since it cannot be a member more than one of the above, this distinguishes between different types of operating system and creates a hidden if..then...else test.

This is the way in which cfengine makes decisions. The key idea is that actions are only carried out if they are in the same class as the host running the program. Classes are dealt with in detail in the next chapter.

Now let's see how to add another kind of action to the action sequence.

 
# Comment...
 
control:

  actionsequence = ( tidy links )

links:

  /bin -> /usr/bin

tidy:

   /tmp  pattern=* age=7 recurse=inf

We have now added a new kind of declaration called tidy: which deletes files. In the example above, we are looking at files in the directory `/tmp' which match the pattern `*' and have not been accessed for more than seven days. The search for these files descends recursively down any number of subdirectories.

To make any of this happen we must add the word tidy to the action sequence. If we don't, the declaration will be ignored. Notice also that, regardless of the fact that links: comes before tidy:, the order in the action sequence tells us that all tidy actions will be performed before links:.

The above structure can be repeated to build up a configuration file or script.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2 Program structure

To summarize the previous section, here is a sketch of a typical cfengine configuration program showing a sensible structure. The various sections are listed in a sensible order which you would probably use in the action sequence.

An individual section-declaration in the program looks something like this:

 
action-type:

   class1::

       list of things to do...

   class2::

       list of things to do...

action-type is one of the following reserved words:

 
   groups, control, homeservers, binservers, mailserver, mountables,
   import, broadcast, resolve, defaultroute, directories, miscmounts,
   files, ignore, tidy, required, links, disable, shellcommands, 
   editfiles, processes

The order in which declarations occur is not important to cfengine from a syntactical point of view, but some of the above actions define information which you will want to refer to later. All variables, classes, groups etc. must be defined before they are used. That means that it is smart to follow the order above for the sections in the first line of the above list.

The order in which items are declared is not to be confused with the order in which they are executed. This is determined by the actionsequence, (see the reference manual). Probably you will want to coordinate the two so that they match as far as possible.

For completeness, here is a complete summary of the structure of a very general cfengine configuration program. The format is free and use of space is unrestricted, though it is always a good idea to put a space in front before and after parentheses when defining variables.

 
######################################################################
# 
# Example of structure
#
######################################################################

groups:
 
   group1 = ( host host ...  )
   group2 = ( host host ...  ) 
   ...

######################################################################

control: 

   class::

   site      =  ( mysite )
   domain    =  ( mydomain )
   ...

    actionsequence = 
      (
      action name
      ....
      )

   mountpattern = ( mountpoint )
   homepattern = ( wildcards matching home directories ) 

   addinstallable = ( foo bar )
   addclasses     = ( foo bar )

######################################################################

homeservers:

   class::  
           home servers

binservers:

   class::
           binary servers

mailserver:

   class::
           mail server

mountables:

   class::

           list of resources


######################################################################

import: 

   class::    include file

   class::    include file


######################################################################

broadcast:

  class::  ones   # or zeros / zeroes

defaultroute:

   class::  my-gw


######################################################################

resolve:

   any::

       list of nameservers


   ...


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.3 Optional features in cfengine

Cfengine doesn't do anything unless you ask it to. When you run a cfengine program it generates no output unless it finds something it believes to be wrong. It does not carry out any actions unless they are declared in the action sequence.

If you like, though, you can make cfengine positively chatty. Cfengine can be run with a number of command line options (see the reference manual). If you run the program with the `-v' or `--verbose' options, it will supply you cheerily with a resume of what it is doing. Certain warning messages also get printed in verbose mode, so it is a useful debugging tool.

You can ask cfengine to check lots of things -- the timezone for instance, or the domain name. In order for it to check these things, it needs some information from you. All of the switches and options which change the way in which cfengine behaves get specified either on the command line or in the control: section of the control file. Some special control variables are used for this purpose. Here is a short example:

 
control:

  domain   = ( mydomain.no )
  netmask  = ( 255.255.255.0 )
  timezone = ( MET CET )

  mountpattern = ( /mydomain/mountpoint )

  actionsequence = 
     (
     checktimezone     # check time zone
     netconfig         # includes check netmask
     resolve           # includes domain
     mountinfo         # look for mounted disks under mountpattern
     )

To get verbose output you must run cfengine with the appropriate command line option `--verbose' or `-v'.

Notice that setting values has a special kind of syntax: a variable name, an equals sign and a value in parentheses. This tells you that the quantity of the left hand side assumes the value on the right hand side. There are lots of questions you might ask at this point. The answers to these will be covered as we go along and in the next chapter.

Before leaving this brief advertisement for control parameters, it is worth noting the definition of mountpattern above. This declares a directory in which cfengine expects to find mounted disks. It will be explained in detail later, for now notice that this definition looks rather stupid and inflexible. It would be much better if we could use some kind of variables to define where to look for mounted filesystems. And of course you can...

Having briefly scraped the surface of what cfengine can do, turn to the example and take a look at what a complete program can look like, (see the reference manual). If you understand it, you might like to skip through the rest of the manual until you find what you are looking for. If it looks mysterious, then the next chapter should answer some questions in more depth.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.4 Invoking cfengine

Cfengine may be invoked in a number of ways. Here are some examples:
 
host% cfengine

host% cfengine --file myfile

host% cfengine -f myfile -v -n

host% cfengine --help

The first of these (the default command, with no arguments) causes cfengine to look for a file called `cfengine.conf' in the current directory and execute it silently. The second command reads the file `myfile' and works silently. The third works in verbose mode and the -n option means that no actions should actually be carried out, only warnings should be printed. The final example causes cfengine to print out a list of its command line options.

The complete list of options is listed in the summary at the beginning of this manual, or you can see it by giving the -h option, (see the reference manual).

In addition to running cfengine with a filename, you can also treat cfengine files as scripts by starting your cfengine program with the standard shell line:
 
#!/local/gnu/bin/cfengine -f
#
# My config script
#
Here we assume that you have installed cfengine under the directory `/local/gnu/bin'. By adding a header like this to the first line of your program and making the file executable with the chmod shell command, you can execute the program just by typing its name--i.e. without mentioning cfengine explicitly at all.

As a novice to cfengine, it is advisable to check all programs with the -n option before trusting them to your system, at least until you are familiar with the behaviour of cfengine. This `safe' option allows you to see what cfengine wants to do, without actually committing yourself to doing it.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.5 CFINPUTS environment variable

Whenever cfengine looks for a file it asks a question: is the filename an absolute name (that is a name which begins from `/' like /usr/file), is it a file in the directory in which you invoke cfengine or is it a file which should be searched for in a special place?

If you use an absolute filename either on the command line using -f or in the import section of your program (a name which begins with a slash '/'), then cfengine trusts the name of the file you have given and treats it literally. If you specify the name of the file as simple `.' or `-' then cfengine reads its input from the standard input.

If you run cfengine without arguments (so that the default filename is `cfengine.conf') or you specify a file without a leading slash in the import section, then the value of the environment variable CFINPUTS is prepended to the start of the file name. This allows you to keep your configuration in a standard place, pointed to by CFINPUTS. For example:

 
host# setenv CFINPUTS /usr/local/gnu/lib/cfengine/inputs

host# cfengine -f myfile

In this example, cfengine tries to open

`/usr/local/gnu/lib/cfengine/inputs/myfile'.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.6 What to aim for

If you are a beginner to cfengine, you might not be certain exactly how you want to use it. Here are some hints from Dr. Daystrom about how to get things working quickly.

When you have set up these components, you can sit back and edit the configuration files and watch things being done.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4. More advanced concepts

4.1 Classes  
4.2 Variable substitution  
4.3 Undefined variables  
4.4 Defining classes and making exceptions  making decisions
4.5 The generic class any  a wildcard
4.6 Debugging tips  nullifying classes
4.7 Access control  specifying user access to programs
4.8 Wildcards in directory names  multiple searches
4.9 Recursive file sweeps/directory traversals  
4.10 Log files written by cfengine  
4.11 Quoted strings  
4.12 Regular expressions  
4.13 Iterating over lists  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.1 Classes

The idea of classes is central to the operation of cfengine. Saying that cfengine is `class orientated' means that it doesn't make decisions using if...then...else constructions the way other languages do, but only carries out an action if the host running the program is in the same class as the action itself. To understand what this means, imagine sorting through a list of all the hosts at your site. Imagine also that you are looking for the class of hosts which belong to the computing department, which run GNU/Linux operating system and which have yellow spots! To figure out whether a particular host satisfies all of these criteria you first delete all of the hosts which are not GNU/Linux, then you delete all of the remaining ones which don't belong to the computing department, then you delete all the remaining ones which don't have yellow spots. If you are on the remaining list, then you are in the class of all computer-science-Linux-yellow-spotted hosts and you can carry out the action.

Cfengine works in this way, narrowing things down by asking if a host is in several classes at the same time. Although some information (like the kind of operating system you are running) can be obtained directly, clearly, to make this work we need to have lists of which hosts belong to the computer department and which ones have yellow spots.

So how does this work in a cfengine program? A program or configuration script consists of a set of declarations for what we refer to as actions which are to be carried out only for certain classes of host. Any host can execute a particular program, but only certain action are extracted -- namely those which refer to that particular host. This happens automatically because cfengine builds up a list of the classes to which it belongs as it goes along, so it avoids having to make many decisions over and over again.

By defining classes which classify the hosts on your network in some easy to understand way, you can make a single action apply to many hosts in one go -- i.e. just the hosts you need. You can make generic rules for specific type of operating system, you can group together clusters of workstations according to who will be using them and you can paint yellow spots on them -- what ever works for you.

A cfengine action looks like this:

 
action-type:

   compound-class::
     
       declaration

A single class can be one of several things:

A compound class is a sequence of simple classes connected by dots or `pipe' symbols (vertical bars). For example:

 
myclass.sun4.Monday::

sun4|ultrix|osf::

A compound class evaluates to `true' if all of the individual classes are separately true, thus in the above example the actions which follow compound_class:: are only carried out if the host concerned is in myclass, is of type sun4 and the day is Monday! In the second example, the host parsing the file must be either of type sun4 or ultrix or osf. In other words, compound classes support two operators: AND and OR, written `.' and `|' respectively. Cfengine doesn't care how many of these operators you use (since it skips over blank class names), so you could write either

 
solaris|irix::

or

 
solaris||irix::

depending on your taste. On the other hand, the order in which cfengine evaluates AND and OR operations does matter, and the rule is that AND takes priority over OR, so that `.' binds classes together tightly and all AND operations are evaluated before ORing the final results together. This is the usual behaviour in programming languages. You can use round parentheses in cfengine classes to override these preferences.

Cfengine allows you to define switch on and off dummy classes so that you can use them to select certain subsets of action. In particular, note that by defining your own classes, using them to make compound rules of this type, and then switching them on and off, you can also switch on and off the corresponding actions in a controlled way. The command line options -D and -N can be used for this purpose. See also addclasses in the Reference manual.

A logical NOT operator has been added to allow you to exclude certain specific hosts in a more flexible way. The logical NOT operator is (as in C and C++) `!'. For instance, the following example would allow all hosts except for myhost:

 
   action:

    !myhost::

        command

and similarly, so allow all hosts in a user-defined group mygroup, except for myhost, you would write

 
   action:

    mygroup.!myhost::

        command

which reads `mygroup AND NOT myhost'. The NOT operator can also be combined with OR. For instance

 
   class1|!class2

would select hosts which were either in class 1, or those which were not in class 2.

Finally, there is a number of reserved classes. The following are hard classes for various operating system architectures. They do not need to be defined because each host knows what operating system it is running. Thus the appropriate one of these will always be defined on each host. Similarly the day of the week is clearly not open to definition, unless you are running cfengine from outer space. The reserved classes are:

 
ultrix, sun4, sun3, hpux, hpux10, aix, solaris, osf, irix4, irix, irix64
   sco, freebsd, netbsd, openbsd, bsd4_3, newsos, solarisx86, aos,
          nextstep, bsdos, linux, debian, cray, unix_sv, GnU, NT

If these classes are not sufficient to distinguish the hosts on your network, cfengine provides more specific classes which contain the name and release of the operating system. To find out what these look like for your systems you can run cfengine in `parse-only-verbose' mode:

 
  cfengine -p -v

and these will be displayed. For example, solaris 2.4 systems generate the additional classes sunos_5_4 and sunos_sun4m, sunos_sun4m_5_4.

Cfengine uses both the unqualified and fully host names as classes. Some sites and operating systems use fully qualified names for their hosts. i.e. uname -n returns to full domain qualified hostname. This spoils the class matching algorithms for cfengine, so cfengine automatically truncates names which contain a dot `.' at the first `.' it encounters. If your hostnames contain dots (which do not refer to a domain name, then cfengine will be confused. The moral is: don't have dots in your host names! NOTE: in order to ensure that the fully qualified name of the host becomes a class you must define the domain variable. The dots in this string will be replaced by underscores.

In summary, the operator ordering in cfengine classes is as follows:

`()'
Parentheses override everything.

`!'
The NOT operator binds tightest.

`.'
The AND operator binds more tightly than OR.

`|'
OR is the weakest operator.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2 Variable substitution

When you are building up a configuration file it is very useful to be able to use variables. If you can define your configuration in terms of some key variables, it can be changed more easily later, it is more transparent to the reader of the program and you can also choose to define the variables differently on different types of system. Another way of saying this is that cfengine variables also belong to classes. Cfengine makes use of variables in three ways.

Environment variables are fetched directly from the shell on whatever system is running the program. An example of a special variable is the domain variable from the previous section. Straightforward macro substitution allows you to define a symbol name to be replaced by an arbitrary text string. All these definitions (apart from shell environment variables, of course) are made in the control part of the cfengine program:

 
control:

  myvar = ( /usr/local/mydir/lib/very/long/path )   # define macro

...

links:

  $(myvar) -> /another/directory

Here we define a macro called myvar, which is later used to define the creation of a link. As promised we can also define class-dependent variables:

 
control:

  sun4:: myvar = ( sun )
  hpux:: myvar = ( HP )

Cfengine gives you access to the shell environment variables and allows you to define variables of your own. It also keeps a few special variables which affect the way in which cfengine works. When cfengine expands a variable it looks first at the name in its list of special variables, then in the list of user-defined macros and finally in the shell environment for a match. If none of these are found it expands to the empty string. If you nest macros,
 
control:

  myvar = ( "$(othervar)" )

then you must quote the right hand side and ensure that the value is already defined.

You can also import values from the execution of a shell command by prefixing a command with the word exec.

 
  control:

   listing = ( "exec /bin/ls" )

This sets the variable `listing' to the output of the command in the quotes.

Variables are referred to in either of two different ways, depending on your taste. You can use the forms $(variable) or ${variable}. The variable in braces or parentheses can be the name of any user defined macro, environment variable or one of the following special internal variables.

AllClasses
A long string in the form `CFALLCLASSES=class1:class2...'. This variable is a summary of all the defined classes at any given time. It is always kept up to date so that scripts can make use of cfengine's class data.

arch
The current detailed architecture string--an amalgamation of the information from uname. Non-definable.

binserver
The default server for binary data. See section 5.6 Cfengine's model for NFS-mounted filesystems. Non definable.

class
The currently defined system hard-class (e.g. sun4, hpux). Non-definable.

date
The current date string. Note that if you use this in a shell command it might be interpreted as a list variable, since it contains the default separator `:'.

domain
The currently defined domain.

faculty
The faculty or site as defined in control (see site).

fqhost
The fully qualified (DNS/BIND) hostname of the system, which includes the domain name as well.

host
The hostname of the machine running the program.

ipaddress
The numerical form of the internet address of the host currently running cfengine.

MaxCfengines
The maximum number of cfengines which should be allowed to co-exist concurrently on the system. This can prevent excessive load due to unintentional spamming in situations where several cfengines are started independently. The default value is unlimited.

ostype
A short for of $(arch).

OutputPrefix
This quoted string can be used to change the default `cfengine:' prefix on output lines to something else. You might wish to shorten the string, or have a different prefix for different hosts. The value in this variable is appended with the name of the host. The default is equivalent to,
 
  OutputPrefix = ( "cfengine:$(host):")

RepChar
The character value of the string used by the file repository in constructing unique filenames from path names. This is the character which replaces `/' (see the reference manual).

site
This variable is identical to $(faculty) and may be used interchangeably.

split
The character on which list variables are split (see the reference manual).

sysadm
The name or mail address of the system administrator.

timezone
The current timezone as defined in control.

UnderscoreClasses
If this is set to `on' cfengine uses hard-classes which begin with an underscore, so as to avoid name collisions. See also Runtime Options in the Reference manual.

year
The current year.

These variables are kept special because they play a special role in setting up a system configuration. See section 5. Designing a global system configuration. You are encouraged to use them to define fully generalized rules in your programs. Variables can be used to advantage in defining filenames, directory names and in passing arguments to shell commands. The judicious use of variables can reduce many definitions to a single one if you plan carefully.

NOTE: the above control variables are not case sensitive, unlike user macros, so you should not define your own macros with these names.

The following variables are also reserved and may be used to produce troublesome special characters in strings.

cr
Expands to the carriage-return character.

dblquote
Expands to a double quote "

dollar
Expands to `$'.

lf
Expands to a line-feed character (unix end of line).

n
Expands to a newline character.

quote
Expands to a single quote '.

spc
Expands simply to a single space. This can be used to place spaces in filenames etc.

tab
Expands to a single tab character.

You can use variables in the following places:

 
links:

  osf::
      /$(site)/${host}/directory -> somefile

 
shellcommands:

  any::

   "/bin/echo $(timezone) | /bin/mail $(sysadm)"
   '/bin/echo "double quotes!"'

The latter possibility enables cfengine's variables to be passed on to user-defined scripts.

Variables can be defined differently under different classes by preceding the definition with a class name. For example:

 
control:

   sun4::  my_macro = ( User_string_1 )
   irix::  my_macro = ( User_string_2 )

Here the value assigned to $(my_macro) depends on which of the classes evaluates to true. This feature can be used to good effect to define the mail address of a suitable system administrator for different groups of host.
 
control:

 physics::   sysadm = ( mark,fred )
 chemistry:: sysadm = ( localsys@domain )

Note, incidentally, that the `-a' option can be used to print out the mail address of the system administrator for any wrapper scripts.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.3 Undefined variables

Note that macro-variables which are undefined are not expanded as of version 1.6 of cfengine. In earlier versions, undefined variables would be replaced by an empty string, as in Perl. In versions 1.6.x and later, the variable string remains un-substituted, if the varaiable does not exist. For instance,
 
control:

  actionsequence = ( shellcommands )

  myvar = ( "test string " )

shellcommands:

 "/bin/echo $(myvar) $(myvar2)"

results in:
 
cfengine:host: Executing script /bin/echo test string  $(myvar2)
cfengine:host:/bin/echo test : sh: syntax error at line 1: `(' unexpected
cfengine:host: Finished script /bin/echo test string  $(myvar2)     

This allows variables to be defined on-the-fly by modules.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.4 Defining classes and making exceptions

Cfengine communicates with itself by passing messages in the form of classes. When a class becomes switched on or off, cfengine's program effectively becomes modified. There are several ways in which you can switch on and off classes. Learning these fully will take some time, and only then will you harness the full power of cfengine.

Because cfengine works at a very high level, doing very many things for very few lines of code it might seem that some flexibility is lost. When we restrict certain actions to special classes it is occasionally useful to be able to switch off classes temporarily so as to cancel the special actions.

4.4.1 Command line classes  
4.4.2 actionsequence classes  
4.4.3 shellcommand classes  
4.4.4 Feedback classes  
4.4.5 Writing plugin modules  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.4.1 Command line classes

You can define classes of your own which can be switched on and off, either on the command line or from the action sequence. For example, suppose we define a class include. We use addclasses to do this.

 
addclasses = ( include othersymbols )

The purpose of this would be to allow certain `excludable actions' to be defined. Actions defined by

 
any.include::
               actions

will normally be carried out, because we have defined include to be true using addclasses. But if cfengine is run in a restricted mode, in which include is set to false, we can exclude these actions.

So, by defining the symbol include to be false, you can exclude all of the actions which have include as a member. There are two ways in which this can be done, one is to negate a class globally using

 
cfengine -N include 

This undefines the class include for the entire duration of the program.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.4.2 actionsequence classes

Another way to specify actions is to use a class to select only a subset of all the actions defined in the actionsequence. You do this by adding a class name to one on the actions in action sequence by using a dot `.' to separate the words. In this case the symbol only evaluates to `true' for the duration of the action to which it attached. Here is an example:
 
  links.onlysome
  shellcommands.othersymbols.onlysome

In the first case onlysome is defined to be true while this instance of links is executed. That means that only actions labelled with the class onlysome will be executed as a result of that statement. In the latter case, both onlysome and othersymbols are defined to be true for the duration of shellcommands.

This syntax would normally be used to omit certain time-consuming actions, such as tidying all home directories. Or perhaps to synchronize certain actions which have to happen in a certain order.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.4.3 shellcommand classes

For more advanced uses of cfengine you might want to be able to define a class on the basis of the success or failure of a user-program, a shell command or user script. Consider the following example

 
groups:

   have_cc = ( "/bin/test -f /usr/ucb/cc" 
               "/bin/test -f /local/gnu/cc"  )

Note that as of version 1.4.0 of cfengine, you may use the word classes as an alias for groups. Whenever cfengine meets an object in a class list or variable, which is surrounded by either single, double quotes or reversed quotes, it attempts to execute the string as a command passed to the Bourne shell. If the resulting command has return code zero (proper exit) then the class on the left hand side of the assignment (in this case `have_cc') will be true. If the command returns any other value (an error number) the result is false. Since groups are the logical OR of their members (it is sufficient that one of the members matches the current system), the class `have_cc' will be defined above if either `/usr/ucb/cc' or `/local/gnu/cc' exist, or both.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.4.4 Feedback classes

Classes may be defined as the result of actions being carried out by cfengine. For example, if a file gets copied, needs to be edited or if diskspace falls under a certain threshhold, cfengine can be made to respond by activating classes at runtime. This allows you to create dynamically responsive programs which react to the changing environment. These classes are defined as part of other statements with clauses of the form

 
  define=classlist

Classes like these should generally be declared at the start of a program unless the define statements always precede the actions which use the defined classes, with addinstallable.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.4.5 Writing plugin modules

If the regular mechanisms for setting classes do not produce the results you require for your configuration, you can write your own routines to concoct the classes of your dreams. Plugin modules are added to cfengine programs from within the actionsequence, (see Reference manual). They allow you to write special code for answering questions which are too complex to answer using the other mechanisms above. This allows you to control classes which will be switched on and the moment at which your module attempts to evaluate the condition of the system.

Modules must lie in a special directory defined by the variable moduledirectory. They must have a name of the form `module:mymodule' and they must follow a simple protocol. Cfengine will only execute a module which is owned either by root or the user who is running cfengine, if it lies in the special directory and has the special name. A plug-in module may be written in any language, it can return any output you like, but lines which begin with a `+' sign are treated as classes to be defined (like `-D'), while lines which begin with a `-' sign are treated as classes to be undefined (like `-N'). Lines starting with `=' are variables/macros to be defined. Any other lines of output are cited by cfengine, so you should normally make your module completely silent. Here is an example module written in perl. First we define the module in the cfengine program:

 
 control:

   moduledirectory = ( /local/cfengine/modules )
 
   actionsequence = ( 
                    files 
                    module:myplugin.specialclass 
                    "module:argplugin.specialclass arg1 arg2"
                    copy 
                    )
 ...

Note that the class definitions for the module can also be defined in as AddInstallables, if this is more convenient. NOTE: you must declare the classes before using them in the cfengine configuration, or else those actions will be ignored. Next we write the plugin itself.
 
#!/usr/bin/perl
#
# module:myplugin
#

  # lots of computation....

if (special-condition)
   {
   print "+specialclass";
   }

Modules inherit the environment variables from cfengine and accept arguments, just as a regular shellcommand does.
 
#!/bin/sh
#
# module:myplugin
#

/bin/echo $*

Cfengine defines the classes as an environment variable so that programs have access to these. E.g. try the following module:

 
#!/usr/bin/perl

print "Decoding $ENV{CFALLCLASSES}\n";

@allclasses = split (":","$ENV{CFALLCLASSES}");

while ($c=shift(@allclasses))
  {
  $classes{$c} = 1;
  print "$c is set\n";
  }

Modules can define macros in cfengine by outputting strings of the form
 
=variablename=value


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.5 The generic class any

The generic wildcard any may be used to stand for any class. Thus instead of assigning actions for the class sun4 only you might define actions for any architecture by specifying:
 
  any::
        actions

If you don't specify any class at all then cfengine assumes a default value of any for the class.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.6 Debugging tips

A useful trick when debugging is to eliminate unwanted actions by changing their class name. Since cfengine assumes that any class it does not understand is the name of some host, it will simply ignore entries it does not recognize. For example:

 
   myclass::

can be changed to

 
   Xmyclass::

Since Xmyclass no longer matches any defined classes, and is not the name of any host it will simply be ignored. The -N option can also be used to the same effect. (see Reference manual).


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.7 Access control

It is sometimes convenient to be able to restrict the access of a program to a handful of users. This can be done by adding an access list to the control: section of your program. For example,

 
control:
    ...
    access = ( mark root )

would cause cfengine to refuse to run the program for any other users except mark and root. Such a restriction would be useful, for instance, if you intended to make set-user-id scripts but only wished certain users to be able to run them. If the access list is absent, all users can execute the program.

Note: if you are running cfengine via the cfrun program then cfengine is always started with the same user identity as the cfservd process on the remote host. Normally this is the root user identity. This means that the access keyword will have no effect on the use of the command cfrun.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.8 Wildcards in directory names

In the two actions files and tidy you define directory names at which file checking or tidying searches should start. One economical feature is that you can define a whole group of directories at which identical searches should start in one fell swoop by making use of wildcards. For example, the directory names

 
     /usr/*/*
     /bla/*/ab?/bla
represent all of the directories (and only directories) which match the above wildcard strings. Cfengine opens each matching directory and iterates the action over all directories which match.

The symbol `?' matches any single character, whereas `*' matches any number of characters, in accordance with shell file-substitution wildcards.

When this notation is used in directory names, it always defines the starting point for a search. It does not tell the command how to search, only where to begin. The pattern directive in tidy can be used to specify patterns when tidying files and under files all files are considered, (see Reference manual),


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.9 Recursive file sweeps/directory traversals

File sweeps are searches through a directory tree in which many files are examined and considered for processing in some way. There are many instances where one uses cfengine to perform a file sweep.

The problem with file sweeps is that they can be too sweeping! Often you are not interested in examining every single file in a file tree. You might wish to perform a search

The tidy action is slightly different in this respect, since it already always expects to match a specific pattern. One is generally not interested in a search which deletes everything except for a named pattern: this would be too dangerous. For this reason, the syntax of tidy does not allow ignore,include and exclude. It is documented in the section on tidying, (see Reference manual).

Items declared under the global ignore section affect files, copy, links and tidy. For file sweeps within files, copy and links, you may provide private ignore lists using ignore=. The difference between exclude and ignore is that ignore can deal with absolute directories. It prunes directories, while exclude only looks at the files within directories.

For file sweeps within files and copy you can specify specific search parameters using the keywords include= and exclude= and as of version 1.6.x filter=. For example,
 
files:

   /usr/local/bin m=0755 exclude=*.ps action=fixall

In this example cfengine searches the entire file tree (omitting any directories listed in the ignore-list and omitting any files ending in the extension `.ps'), (see Reference manual).

Specifying the include= keyword is slightly different since it automatically restricts the search to only named patterns (using * and ? wildcards), whenever you have one or more instances of it. If you include patterns in this way, cfengine ignores any files which do not match the given patterns. It also ignores any patterns which you have specified in the global ignore-list as well as patterns excluded with exclude=pattern. In other words, exclusions always override inclusions.

If you exclude a pattern or a directory and wish to treat it in some special way, you need to code an explicit check for that pattern as a separate entity. For example, to handle the exluded `.ps' files above, you would need to code something like this:
 
files:

   /usr/local/bin m=0644 include=*.ps action=fixall

Note: don't be tempted to enclose your wildcards in quotes. The quotes will be treated literally and the pattern might not match the way you would expect.

For editfiles the syntax is somewhat different. Here one needs to add lines to the edit stanza:

 
editfiles:

 { /tmp/testdir

 Include .*
 Exclude bla.*
 Ignore "."
 Ignore ".."
 Recurse 6

 ReplaceAll "search" With "replace"
 }


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.10 Log files written by cfengine

Cfengine keeps two kinds of log-file privately and it allows you to log its activity to syslog. Syslog logging may be switched on with the Syslog variable, (see Reference manual).

The first log cfengine keeps is for every user (every subdirectory of a home directory filesystem). A file ~/.cfengine.rm keeps a list of all the files which were deleted during the last pass of the tidy function. This is useful for users who want to know files have been removed without their blessing. This helps to identify what is happening on the system in case of accidents.

Another file is built when cfengine searches through file trees in the files action. This is a list of all programs which are setuid root, or setgid root. Since such files are a potential security risk, cfengine always prints a warning when it encounters a new one (one which is not already in its list). This allows the system administrator to keep a watchful eye over new programs which appear and give users root access. The cfengine log is called /etc/cfengine/cfengine.log. The file is not readable for general users.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.11 Quoted strings

In several cfengine commands, you use quoted strings to define a quantity of text which may contain spaces. For example

 
control:

  macro = ( "mycommand" )

editfiles:

  { $(HOME)/myfile

   AppendIfNoSuchLine 'This text contains space'
  }

In each case you may use any one of the three types of quote marks in order to delimit strings,

 
  ' or " or `

If you choose, say ", then you may not use this symbol within the string itself. The same goes for the other types of string delimiters. Unlike the shell, cfengine treats these three delimiters in precisely the same way. There is no difference between them. If you need to quote a quoted string, then you should choose a delimiter which does not conflict with the substring.

Note that you can use special variables for certain symbols in a string See section 4.2 Variable substitution.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.12 Regular expressions

Regular expressions can be used in cfengine in connection with editfiles and processes to search for lines matching certain expressions. A regular expression is a generalized wildcard. In cfengine wildcards, you can use the characters '*' and '?' to match any character or number of characters. Regular expressions are more complicated than wildcards, but have far more flexibility.

NOTE: the special characters `*' and `?' used in wildcards do not have the same meanings as regular expressions!.

Some regular expressions match only a single string. For example, every string which contains no special characters is a regular expression which matches only a string identical to itself. Thus the regular expression `cfengine' would match only the string "cfengine", not "Cfengine" or "cfengin" etc. Other regular expressions could match more general strings. For instance, the regular expression `c*' matches any number of c's (including none). Thus this expression would match the empty string, "c", "cccc", "ccccccccc", but not "cccx".

Here is a list of regular expression special characters and operators.

`\'
The backslash character normally has a special purpose: either to introduce a special command, or to tell the expression interpreter that the next character is not to be treated as a special character. The backslash character stands for itself only when protected by square brackets [\] or quoted with a backslash itself `\\'.

`\b'
Matches word boundary operator.

`\B'
Match within a word (operator).

`\<'
Match beginning of word.

`\>'
Match end of word.

`\w'
Match a character which can be part of a word.

`\W'
Match a character which cannot be part of a word.

`any character'
Matches itself.

`.'
Matches any character

`*'
Match zero or more instances of the previous object. e.g. `c*'. If no object precedes it, it represents a literal asterisk.

`+'
Match one or more instances of the preceding object.

`?'
Match zero or one instance of the preceding object.

`{ }'
Number of matches operator. `{5}' would match exactly 5 instances of the previous object. `{6,}' would match at least 6 instances of the previous object. `{7,12}' would match at least 7 instances of, but no more than 12 instances of the preceding object. Clearly the first number must be less than the second to make a valid search expression.

`|'
The logical OR operator, OR's any two regular expressions.

`[list]'
Defines a list of characters which are to be considered as a single object (ORed). e.g. `[a-z]' matches any character in the range a to z, `abcd' matches either a, b, c or d. Most characters are ordinary inside a list, but there are some exceptions: `]' ends the list unless it is the first item, `\' quotes the next character, `[:' and `:]' define a character class operator (see below), and `-' represents a range of characters unless it is the first or last character in the list.

`[^list]'
Defines a list of characters which are NOT to be matched. i.e. match any character except those in the list.

``[:class:]''
Defines a class of characters, using the ctype-library.
alnum
Alpha numeric character

alpha
An alphabetic character

blank
A space or a TAB

cntrl
A control character.

digit
0-9

graph
same as print, without space

lower
a lower case letter

print
printable characters (non control characters)

punct
neither control nor alphanumeric symbols

space
space, carriage return, line-feed, vertical tab and form-feed.

upper
upper case letter

xdigit
a hexadecimal digit 0-9, a-f

``( )''
Groups together any number of operators.

`\digit'
Back-reference operator (refer to the GNU regex documentation).

`^'
Match start of a line.

`$'
Match the end of a line.

Here is a few examples. Remember that some commands look for a regular expression match of part of a string, while others require a match of the entire string (see Reference manual).

 
^#        match string beginning with the # symbol
^[^#]      match string not beginning with the # symbol
^[A-Z].+  match a string beginning with an uppercase letter
          followed by at least one other character  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.13 Iterating over lists

Shell list variables are normally defined by joining together a list of directories using a concatenation character such as `:'. A typical example of this is the PATH variable:

 
PATH=/usr/bin:/usr/local/bin:/usr/sbin

It is convenient to be able to use such variables to force cfengine to iterative over a list. This gives us a compact way of writing repeated operations and it allows a simple method of communication with the shell environment. For security reasons, iteration is supported only in the following contexts:

This typically allows communication with PATH-like environment variables in the shell.

In these contexts, any variable which has the form of a list joined together by colons will be iterated over at compilation time. Note that you can change the value of the list separator using the split variable in the control section of the program (see Reference manual).

For example, to link all of the binary files in the PATH environment variable to a single directory, tidying dead links in the process, you would write

 
control:

  actionsequence = ( links tidy )

links:

  /allbin +> $(PATH)

tidy:

  # Hopefully no-match matches nothing

  /allbin pattern=no-match age=0 links=tidy

no-match is not a reserved word in cfengine, this is just a string you do not expect to match any file.

Alternatively, you might want to define an internal list using a space as a separator:

 
control:

   split = ( " " )

   mylist = ( "mark ricky bad-dude" )

tidy:

   /mnt/home1/$(mylist) pattern=*.cfsaved age=1

This example iterates the tidy action over the directories `/mnt/home1/mark', `/mnt/home1/ricky' and `/mnt/home1/bad-dude'.

The number of list variables in any path or filename should normally be restricted to one or two, since the haphazard combination of two lists will seldom lead to any meaningful pattern. The only obvious exception is perhaps to iterate over a common set of child-directories like `bin', `lib' etc in several different package directories.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5. Designing a global system configuration

This chapter is about building strategies for putting together a site configuration for your entire network.

5.1 General considerations  
5.2 Using netgroups  a common database for classes
5.3 Files and links  
5.4 Copying files  
5.5 Managing processes  
5.6 Cfengine's model for NFS-mounted filesystems  the cfengine model
5.7 Using the automounter  
5.8 Editing Files  
5.9 Disabling and the file repository  
5.10 Running user scripts  
5.11 Compressing old log files  
5.12 Managing ACLs  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.1 General considerations

In order to use any system administration tool successfully, you have to make peace with your system by deciding exactly what you expect and what you are willing to do to achieve the results. You need to decide what you will consider to be acceptable and what is to be considered completely untenable. You need to make these decisions because otherwise you will only be confused later when things don't go the way you expected.

Experience shows that the most successful policies for automation involve keeping everything as simple as possible. The more uniform or alike your machines are, the easier they are to run and the happier users are. Sometimes people claim that they need such great flexibility that all their machines should be different. This belief tends to be inversely proportional to the number of machines they run and generally only applies to very special development environments! Usually you will only need one or to machines to be special and most can be made very similar.

Site configuration is about sharing and controlling resources. The resources include disks (filespace), files, data, programs, passwords and physical machines. Before planning your sitewide configuration you should spend some time deciding how you would like things to work.

In the remaining parts of this chapter, you will find some hints and tips about how to proceed, but remember that when push comes to shove, you must make your own choices.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.2 Using netgroups

If you use the network information service (NIS) on your local network then you may already have defined netgroups consisting of lists of hosts which belong to specific owners at your site. If you have, then you can use these groups within cfengine. This means that you can use the same groups in the /etc/exports file as you use to define the mount groups and classes.

A netgroup is a list of hostnames or user names which are registered in the network information service (NIS) database under a specific name. In our case we shall only be interested in lists of hostnames.

To make a netgroup you need to define a list in the file /etc/netgroup on your NIS server. If you are not the NIS administrator, you will have to ask to have a netgroup installed. The form of a netgroup list of hosts is:

 
mylist-name      (host1,,) (host2,,) (host3,,) (host4,,)

norway-sun4-host (saga,,) (tor,,) (odin,,)
foes-linux-hosts (borg,,)

Each list item has three entries, but only the first is relevant for a host list. See the manual pages on netgroups for a full explanation of the meaning of these fields.

The usefulness of netgroups is that they can be used to stand for a list of hostnames in system files like `/etc/exports'. This compresses the amount of text in this file from a long list to a single name. It also means that if you use the same list of hosts from a netgroup inside cfengine when defining groups and classes, you can be sure that you are always using the same list. In particular it means that you don't have to update multiple copies of a list of hosts.

The netgroups can now be used in cfengine programs by using the + or @+ symbols in the groups section. (see Reference manual).


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.3 Files and links

File and link management takes several forms. Actions are divided into three categories called files, tidy and links. The first of these is used to check the existence of, the ownership and permissions of files. The second concerns the systematic deletion of garbage files. The third is a link manager which tests, makes and destroys links. The monitoring of file access bits and ownership can be set up for individual files and for directory trees, with controlled recursion. Files which do not meet the specified criteria can be `fixed' --i.e. automatically set to the correct permissions, or can simply be brought to the attention of the system administrator by a warning. The syntax of such a command is as follows:

 
files:

  class::

    /path mode=mode owner=owner group=group

         recurse=no-of-levels action=action

The directory or file name is the point at which cfengine begins looking for files. From this point the search for files proceeds recursively into subdirectories with a maximum limit set by the recurse directive, and various options for dealing with symbolic links and device boundaries. The mode-string defines the allowed file-mode (by analogy with `chmod') and the owner and group may specify lists of acceptable user-ids and group-ids. The action taken in response to a file which does not meet acceptable criteria is specified in the action directive. It includes warning about or directly fixing all files, or plain files or directories only. Safe defaults exist for these directives so that in practice they may be treated as options.

For example,
 
files:

  any::
       /usr/*/bin mode=a+rx,o-w own=root r=inf act=fixall

which (in abbreviated form) would check recursively all files and directories starting from directories matching the wildcard (e.g. `/usr/local/bin', `/usr/ucb/bin'). By default, fixall causes the permissions and ownership of the files to be fixed without further warning.

One problem with symbolic links is that the files they point to can get deleted leaving a `hanging pointer'. Since cfengine can make many hundreds of links without any effort, there is the danger that, in time, the system could become full of links which don't point anywhere. To combat this problem, you can set the option links=tidy in the files section. If this is set, cfengine will remove any symbolic links which do not point to existing files (see Reference manual).

The creation of symbolic links is illustrated in figure 1 and the checking algorithm was discussed in section 2. In addition to the creation of single links, one may also specify the creation of multiple links with a single command. The command

 
links:

   binaryhost::

      /local/elm/bin +> /local/bin

links all of the files in `/local/elm/bin' to corresponding files in `/local/bin'. This provides, amongst other things, one simple way of installing software packages in regular `bin' directories without controlling users' PATH variable. A further facility makes use of cfengine's knowledge of available (mounted) binary resources to search for matches to specific links. Readers are referred to the full documentation concerning this feature.

The need to tidy junk files has become increasingly evident during the history of cfengine. Files build up quickly in areas like `/tmp', `/var/tmp'. Many users use these areas for receiving large ftp-files so that their disk usage will not be noticed! To give another example, just in the last few months the arrival of netscape World Wide Web client, with its caching facilities, has flooded hard-disks at Oslo with hundreds of megabytes of WWW files. In addition the regular appearance of `core' files(1) and compilation by-products (`.o' files and `.log' files etc.) fills disks with large files which many users do not understand. The problem is easily remedied by a few lines in the cfengine configuration. Files can be deleted if they have not been accessed for n-days. Recursive searches are both possible and highly practical here. In following example:

 
tidy:

   AllHomeServers::

      home                 pattern=core       r=inf age=0
      home/.wastebasket    pattern=*          r=inf age=14
      home/.netscape-cache pattern=cache????* r=inf age=2
      home/.MCOM-cache     pattern=cache????* r=inf age=2
      home/.netscape       pattern=cache????*  r=inf age=2

all hosts in the group `AllHomeServers' are instructed to iterate over all users' home directories (using the wildcard home) and look for files matching special patterns. Cfengine tests the access time of files and deletes only files older than the specified limits. Hence all core files, in this example, are deleted immediately, whereas files in the subdirectory `.wastebasket' are deleted only after they have lain there untouched for 14 days, and so on.

As a system administrator you should, of course, exercise great caution when making rules which can delete users' files. A single slip of the hand can result in a rule which will irretrievably delete files.

When making a `tidy' strategy you should probably coordinate with your backup policy. You should not delete files until after you have taken a backup, so that -- if the worst should happen -- you are covered against possible accidents.

Cfengine helps to some extent to keep track of what files it deletes. When tidying users' home directories it creates a log file of all files which were deleted on the last tidy operation. This log is called ~/.cfengine.rm.

You might consider tidying certain files only once a week, in which case a command such as

 
tidy:

   AllHomeServers.Sunday::

       files to tidy

could be useful. Nonsense files, such as `core' files could be tidied every night.

NOTE! Be careful when telling cfengine to delete core files. If you write a wildcard like core*, then you could risk deleting important system files such as core.h.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4 Copying files

The administration of a system often requires the copying of files. The reason for this is usually that we would like to distribute a copy of a particular file, from some master location and ensure that all of the copies are up to date. Another use for this is to install software from one directory (perhaps on a CD ROM) to another.

Cfengine helps this process by allowing you to copy a single file or a file tree, from one directory to another, perhaps checking the permissions and owners of a file to adjust the copies in some special way. The files are checked by cfengine using one of two methods.

Cfengine allows you to do the following

You can find out more about copying in the reference section.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.5 Managing processes

Cfengine allows you to check for the existence of processes on your system, send those processes signals (such as kill) and perhaps restart those processes. Typical applications for this are sending `cron' and `inetd' the HUP signal, after editing their configuration files, or killing unwanted processes (such as user programs which hog the system at peak usage times).

You can read more about this in the reference section .


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.6 Cfengine's model for NFS-mounted filesystems

Most of the filesystems that you will want to make available across the network are going to fall into one of two categories. In cfengine parlance these are called home directories and binary directories. A home directory is a place where users' login directories are kept. This is traditionally a directory called `/home' or `/users' or some subdirectory of these. A binary directory is a place where compiled software is kept. Such files (which do not belong to the pure operating system release) are often placed in a directory called `/usr/local' or simply `/local'.

In this chapter we shall consider a scheme for using cfengine to make NFS filesystem management quite painless.

5.6.1 NFS filesystem resources  a conceptual introduction
5.6.2 Unique filesystem mountpoints  avoiding collisions
5.6.3 How does it work?  
5.6.4 Special variables  binserver etc.
5.6.5 Example programs for mounting resources  example program


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.6.1 NFS filesystem resources

Using the Network File System (NFS) in a large workstation environment requires a bit of planning. The idea of NFS is to share files on one host with other hosts. In most cases, filesystems to be shared across the network fall into two categories: binary filesystems (those which contain compiled software) and user or home filesystems (which contain users' login areas).

The most simple minded way to share resources would be to mount every resource (each available NFS filesystem) onto every host. To avoid collisions, each filesystem would have to have a unique name. This is one possibility, but not a very intelligent one. As experienced users will realize, cross-mounting too many NFS filesystems is a recipe for all kinds of trouble.

Cfengine offers a simple model which can help you pick out only the resources you need from the list of NFS filesystems. It will then mount them automatically and edit the appropriate filesystem tables. It does this by defining classes of hosts. For instance -- you really don't need to mount a binary filesystem for an ultrix system onto an HPUX system. There would be no point -- binary resources are architecture or hard-class dependent. But home directories are architecture independent.

Cfengine lets you to define a list of allowed servers for various hosts so that only filesystems from the servers will be considered for mounting!


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.6.2 Unique filesystem mountpoints

The first step towards treating NFS filesystems as network resources is to invent a naming scheme so that every filesystem has a unique name on which it can be mounted. If we don't sort this out now, we could find two or more hosts with a filesystem called /usr/local, both of which we might like to mount since they contain different software.

A simple but extremely useful naming scheme is the following. (2) If you don't like this scheme you can invent your own, but the remainder of the text will encourage you to use this one. If you follow this scheme, exactly as described here, you will never have any problems with mount points. We shall describe the scheme in detail below. Here are some points to digest:

Each filesystem is given a directory name composed of three parts:

 
/site/host/contents

The first directory (which only exists to create a suitable mountpoint) is the name of your local site. If you are a physics department at a university (with a separate setup) you could call this `physics'. It could be your company name or whatever. The second piece is the name of the host to which the disk space is physically attached. The final piece is the name of the filesystem. Here are some typical examples:

 
/physics/einstein/local    # /usr/local for einstein@physics
/physics/newton/u1         # user partition 1 for newton@physics
On the machines which are home to the `local' partition, it is better to make a link to /usr/local than call the filesystem /usr/local directly. This is because it makes the procedure of organizing the entire network much clearer.

It is worth noting that, when you ask cfengine to mount such a resource, it will automatically make the mount directory and can easily be asked to make a link to /usr/local, so this small amount of extra work is really no work at all.

The whole naming convention is compactly summarized by defining a mount point variable, mountpattern. With the present scheme, this can be defined as

 
mountpattern = ( /$(site)/$(host) )
so that it evaluates to the name of the host executing the file regardless of who that may be. This variable is used together with the homepattern pattern variable, which is used to distinguish between home directories and binary resources. (See homepattern in the reference section). You can think of this as being part of the naming convention. In this text, we use the convention u1 u2 u3... for home disks. You could equally well use home1 home2... etc. As long as the name is unique, it doesn't matter.

The full list of named resources should now be listed in the mountables list, which is simply a list of all the resources available for mounting on the network.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.6.3 How does it work?

Once you have defined your unique names, how does cfengine know what to mount? The idea is now to define a list of servers for each class of hosts.

Suppose we make a binserver declaration:

 
binservers:

  mygroup.sun4::

     einstein
     newton

This would tell cfengine that it should mount all binary resources from hosts einstein or newton onto any host of type sun4 in the group mygroup. Every filesystem which is listed in mountables and is not a home directory will be mounted.

Home directories and binary resources are kept separate automatically by cfengine, because a home directory is one whose contents-name matches the homepattern pattern variable. See section 5.6.2 Unique filesystem mountpoints.

A homeserver declaration:

 
homeservers:

  mygroup::
   
     einstein
     newton
     schwinger
     feynman
 

would correspondingly mean mount all the home directory resources on the hosts in the list on all hosts in the group mygroup. Clearly it is unnecessary to distinguish between the architecture platform types of the actual servers for user directories.

In each case, cfengine will mount filesystems, make the appropriate directories for the mount point and edit the filesystem table.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.6.4 Special variables

Once you have mounted a resource on a unique directory, you have access to all of the relevant filesystems on your network -- but you really wanted the `local' filesystem to be mounted on /usr/local. All you need do now is to make a link:

 
links:

  any::

      /usr/local  -> /$(site)/$(binserver)/local

The meaning of this is that, on any host, the directory /usr/local should be a link to the `nearest' binary server's `local' resource. The $(binserver) variable can in principle expand to any binary server in the list. In practice, cfengine goes through the list in order and picks the first filesystem resource which matches.

Could this lead to a collision? Suppose we are on the host `einstein' and we execute the above command. The host `einstein' has a filesystem /physics/einstein/local on its local disk -- it is in fact the binary server for the network, so it certainly doesn't need to mount any NFS filesystems. But this is no problem because cfengine automatically treats $(host) as the highest priority binary server for any host. That means that if you have a local filesystem, it will always have priority.

In contrast, if the host `schwinger' ran the command above, it would find no local filesystem called /physics/schwinger/local, so it would go along the list of defined binary servers, find `einstein' and try again. It will succeed in finding `einstein' provided all the binary servers were mounted before the link command is executed. This means that you should structure the actionsequence so that all filesystems are mounted before any links are made.

With a little practice, the cfengine model can lead to an enormous simplification of the issue of NFS-mountable resources.

NOTE: cfengine does not try to export filesystems, only mount already exported filesystems. If you want to automate this procedure also, you can use the editfiles facility to add entries to `/etc/exports' (see editfiles in the Reference manual). In practice this is very difficult to do and perhaps not desirable.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.6.5 Example programs for mounting resources

Let's write a very simple configuration for a network with only one server called hal, where all the hosts are of the same operating system type. In such an example we can avoid using classes altogether.

 
control:

  site   = ( univ )
  domain = ( univ.edu )

  actionsequence =
     (
     mountall
     mountinfo
     addmounts
     mountall
     links
     )

binservers:

   hal

homeservers:

   hal

mailserver:

   hal:/var/spool/mail

mountables:

   hal:/univ/home1
   hal:/univ/home2
   hal:/univ/local

links:

   /usr/local -> /univ/local

In this example, we have only one type of host so the configuration is the same for each of them: no class references are required. If we look through the action sequence we see that the program first mounts all the filesystems which are already defined on each host. It does this to be sure that everything which is already set up to be mounted is mounted. Let's assume that there are no problems with this.

The next thing that happens is that mountinfo builds a list of the filesystems which each host has successfully mounted. Then by calling addmounts we ask cfengine to check whether the host is missing any filesystems. What happens is that cfengine first looks to see what servers are defined for each host. In this case all hosts on the network have only one server: hal. Hal is defined as a server for both binary data and `home' data -- i.e. users' home directories. The list mountables tells cfengine what filesystems are available over the network for the server hal. There are three filesystems which can be mounted, called `/univ/home1', `/univ/home2' and `/univ/local'. Cfengine checks to see whether each of these filesystems is mounted and, if not, it builds the necessary directories, edits the necessary files and mounts the filesystems.

Finally we come to links in the action sequence. This tells cfengine to look at the defined links. There is one link defined: a link from `/usr/local' to the mounted filesystem `/univ/local'. Cfengine checks and tries to make the link if necessary. If all goes well, each host on the network should now have at least three filesystems mounted and a link from `/usr/local' to `/univ/local'.

Here is another simple example program for checking and automatically mounting an NFS based /usr/local and all home directories onto all hosts on a small network. Here we have several servers and must therefore use some classes.

 
#
#  Mounts
#


control: 

   site      = ( mysite )
   domain    = ( mysite.country ) 
   sysadm    = ( mark ) 
   netmask   = ( 255.255.255.0 )

   actionsequence = 
      (
      mountall
      mountinfo
      addmounts
      mountall
      links
      )

   mountpattern = ( /$(site)/$(host) )
   homepattern   = ( u? )                # u1 u2 u3 etc..

groups:

   MyGroup =
      (
      host1
      host2
      binserver1
      binserver2
      )

######################################################################

homeservers:

   MyGroup:: host1


binservers:

   MyGroup.sun4::   server1
   MyGroup.ultrix:: server2

mailserver:

   host1:/usr/spool/mail

mountables:

   host1:/mysite/host1/u1
   host1:/mysite/host1/u2
   server1:/mysite/server1/local
   server2:/mysite/server2/local


##########################################################################

links:

      /usr/local  -> /${site}/${binserver}/local

Let's suppose we run this program on host2 which is an ultrix machine. This host belongs to the class mygroup and the hard-class ultrix. This tells us that its homeserver is host1, its binary server is server2 and its mailserver is host1. Moreover, since the homepattern matches any filesystem ending in u-something, it recognizes the two home directories in the mountables list -- and therefore the two binary directories also.

The action sequence starts by mounting all of the filesystems currently in the filesystem table `/etc/fstab'. It then scans the list of mounted filesystems to find out what is actually mounted. Since the homeserver is host1, we know that our host has to mount all home-filesystems from this server, so it checks for `host1:/mysite/host1/u1' and `host1:/mysite/host1/u2'. If they are not present they are added to `/etc/fstab'(3). Next, we know that the binary server is server1, so we should check for `server1:/mysite/server1/local'. The mail server is also checked for and added if necessary. Cfengine then tries to mount all filesystems once again, so that the new filesystems should be added.

Note that, in the process of adding the filesystems to `/etc/fstab', cfengine creates the directories up to and including the point at which the filesystems should be mounted. If something prevents this -- if we try to mount on top of a plain file for instance --- then this will result in an error.

Finally, we reach the link section and we try to expand the variables. $(site) expands to `mysite'. $(binserver) expands first to the hostname (host2), but `/mysite/host2/local' does not exist, so it then goes to the binserver list, which substitutes server1 for the value of $(binserver). Since `/mysite/server1/local' does exist and is now mounted, cfengine makes a link to this directory from `/usr/local'. The script is then completed.

If the script is run again, everything should now be in place so nothing happens. If for some reason it failed the first time, it will fail again. At any rate it will either do the job once and for all or signal an error which must be corrected by human intervention(4).


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.7 Using the automounter

The automounter is a daemon based service which replaces static mounting of NFS filesystems with a dynamical model. When the automounter is running, filesystems are mounted only when a user tries to access a file which resides on one of those filesystem. After a given period (usually five minutes) any filesystem which has not been accessed is unmounted. The advantage of this scenario is that hanging servers do not affect the behaviour of hosts which mount their filesystems, unless a specific file is being accessed. In both cases, filesystems must be exported in order to be mountable.

It is not the purpose of this section to explain the use of the automounter in detail, only to offer hints as to how cfengine can be used to simplify and rationalize automount configuration for the already initiated. Let us begin by comparing the behaviour of the automounter with the cfengine model for mounted filesystems.

The automounter is designed to be used together with a global configuration file, distributed by NIS (the network information service). As such, all hosts read the same configuration file. This makes it appear as though all hosts end up mounting every filesystem in the automount configuration database, but this is not so in practice because filesystems are only mounted if required. Thus a system which does not require a filesystem will not attempt to mount it. Moreover, the existence of a global configuration file does not affect which hosts have the right to mount certain filesystems (which is specified by exports or share on the relevant server), thus a request to mount a non-exported filesystem will result in an access denial. The automounter is configured locally on each host in files named `/etc/auto_master', `auto_direct' etc.

In the cfengine static mounting scheme, you define a list of binary and home servers. The filesystem table is modified on the basis of these decisions, and filesystems are only added if cfengine deems it appropriate to mount them on a given host. The idea here is to minimize the number of filesystems mounted to those which are known to be required. Again the issue of access permissions must be arranged separately. These filesystems are placed directly in `/etc/fstab', or the equivalent for your system.

>From cfengine, you can use the automounter instead of the static mount model by

The automounter was created to solve certain problems which cfengine now solves (in the author's opinion) better. For example, the use of the `hosts' map in the automounter mounts filesystems like `/usr/local' on different (uniquely named) mountpoints for each host in order to avoid name space collisions. Using cfengine and a unique naming scheme, you can achieve the same thing more cleanly, without all of the gratuitous linking and unlinking which the automounter performs by itself. Moreover, the idea of a unique name-space is better practice and more in keeping with new global filesystem ideas such as AFS and DFS. The only advantage of the automounter is that one avoids the annoying error messages from hung servers about "NFS server not responding". In that respect, it seems sensible to use only direct mounts and a unique name space.

Some systems advocate grouping all users' login (home) directories under a common directory called `/home' or `users'. The automounter goes through all manner of contortions to achieve this task. If you use a unique naming scheme like the one advocated here, this is a trivial task. You simply arrange to mount or automount all user directories, such as

 
   /site/host/home1
   /site/host/home2
   ...

and then link them as follows:

 
   /home +> /site/host/home1
   /home +> /site/host/home2
   ...

Finally, you should be aware that the automounter does not like to be mixed with static mount and unmount operations. Automounted filesystems take priority over statically mounted filesystems, but the automounter can be confused by manually mounting or unmounting filesystems while it is running.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.8 Editing Files

A very convenient characteristic of BSD/System 5 systems is that they are configured primarily by human-readable textfiles. This makes it easy for humans to configure the system and it also simplifies the automation of the procedure. Most configuration files are line-based text files, a fact which explains the popularity of, for example, the Perl programming language. Cfengine does not attempt to compete with Perl or its peers. Its internal editing functions operate at a higher level which are designed for transparency rather than flexibility. Fortunately most editing operations involve appending a few lines to a file, commenting out certain lines or deleting lines.

For example, some administrators consider the finger service to be a threat to security and want to disable it. This could be done as follows.

 
editfiles:

      { /etc/inetd.conf

      HashCommentLinesContaining "finger"
      }

Commands containing the word `Comment' are used to `comment out' certain lines from a text-file--i.e. render a line impotent without actually deleting it. Three types of comment were supported originally: shell style (hash) `#', `%' as used in TeX and on AIX systems, and C++-style `//'.

A more flexible way of commenting is also possible, using directives which first define strings which signify the start of a comment and the end of a comment. A single command can then be used to render a comment. The default values of the comment-start string is `# ' and the default comment-end string is the empty string. For instance, to define C style comments you could write:

 
  { file

  SetCommentStart "/* "
  SetCommentEnd   " */"

  # Comment out all lines containing printf!

  CommentLinesMatching ".*printf.*"
  }

Other applications for these editing commands include monitoring and controlling root-access to hosts by editing files such as `.rhosts' and setting up standard environment variables in global shell resource files-- for example, to set the timezone. You can use the editing feature to update and distribute the message of the day file, or to configure sendmail, (see FAQS and Tips in the Reference manual).

An extremely powerful feature of cfengine is the ability to edit a similar file belonging to every user in the system. For example, as a system administrator, you sometimes need to ensure that users have a sensible login environment. Changes in the system might require all users to define a new environment variable, for instance. This is achieved with the home pseudo-wildcard. If one writes

 
  { home/.cshrc

  AppendIfNoSuchLine "# Sys admin/cfengine: put next line here"
  AppendIfNoSuchLine "setenv PRINTER newprinter"
  }

then the users' files are checked one-by-one for the given lines of text, and edited if necessary.

Files are loaded into cfengine and edited in memory. They are only saved again if modifications to the file are carried out, in which case the old file is preserved by adding a suffix to the filename. When files are edited, cfengine generates a warning for the administrator's inspection so that the reason for the change can be investigated.

The behaviour of cfengine should not be confused with that of sed or perl. Some functionality is reproduced for convenience, but the specific functions have been chosen on the basis of (i) their readability and (ii) the fact that they are `frequently-required-functions'. A typical file editing session involves the following points:

Equivalent one-line sed operations involve editing the same file perhaps many times to achieve the same results--without the safety checks in addition.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.9 Disabling and the file repository

The existence of certain files can compromise the integrity of your system and you may wish to ensure that they do not exist. For example, some manufacturers sell their workstations with a `+' symbol in the file `/etc/hosts.equiv'. This means that anyone in your NIS domain has password free access to the system!! Since this is probably not a good idea, you will want to disable this file by renaming it, or simply deleting it.

 
  disable:

     /etc/hosts.equiv

Other files compromise the system because they grow so large that they fill an entire disk partition. This is typically true of log files such as the system 5 files `/var/adm/wtmpx' and `/var/lp/logs/lpsched'. Other files like /var/adm/messages get "rotated" by the system so that they do not grow so large as to fill the disk. You can make cfengine rotate these files too, by writing

 
disable:

    Sunday::

    /var/lp/logs/lpsched  rotate=3

Now, when cfengine is run, it renamed the file `lpsched' to a file called `lpsched.1'. It also renames `lpsched.1' as `lpsched.2' and so on, until a maximum of 3 files are kept. After passing 3, the files `fall off the end' and are deleted permanently. This procedure prevents any log files from growing too large. If you are not interested in keeping back-logs, then you may write rotate=empty and cfengine will simply empty the log file.

When ever cfengine disables a file (disable or links with the `!' operator), or saves a new file on top of an old one (copy or editfiles), it makes a backup of the original. Usually disabled files are renamed by appending the string `.cfdisabled' the filename; copied files are saved by appending the string `.cfsaved'. It is possible to switch off backup file generation in the copy feature by setting the variable backup=false, but a better way of managing disabled and backed-up files is to use a directory in which you collect all such files for the whole system. This directory is called the file repository and is set in the control part of the program, as follows:

 
  control:

     repository = ( directory-name )

If this variable is defined, cfengine collects all backup and disabled files (except for rotated files) in this directory, using a unique pathname. You can then inspect these files in the repository and arrange to tidy the repository for old files which are no longer interesting.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.10 Running user scripts

Above all, the aim of cfengine is to present a simple interface to system administrators. The actions which are built into the engine are aimed at solving the most pressing problems, not at solving every problem. In many cases administrators will still need to write scripts to carry out more specific tasks. These scripts can still be profitably run from cfengine. Variables and macros defined in cfengine can be passed to scripts so that scripts can make maximal advantage of the class based decisions. Also note that, since the days of the week are also classes in cfengine, it is straightforward to run weekly scripts from the cfengine environment (assuming that the configuration program is executed daily). An obvious use for this is to update databases, like the fast-find database one day of the week, or to run quota checks on disks.

 
shellcommands:

   myhost.Sunday::

      "/usr/bin/find/updatedb"

Cfengine scripts can be passed variables using normal variable substitution:

 
control:

   cfbin     = ( /local/gnu/lib/cfengine/bin )
   backupdir = ( /iu/dax/backup )   

shellcommands:
  
  "$(cfbin)/cfbackup -p -f $(backupdir) -s /iu/nexus/u1"

If you need to write a particularly complex script to expand cfengine's capabilities, it might be useful to have full access to the defined classes. You can do this in one of two ways:


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.11 Compressing old log files

In the previous two sections we have looked at how to rotate old log files and how to execute shell commands. If you keep a lot of old log files around on your system, you might want to compress them so that they don't take up so much space. You can do this with a shell command. The example below looks for files matching a shell wildcard. Names of the form `file.1', `file.2'...`file.10' will match this wildcard and the compression program sees that they get compressed. The output is dumped to avoid spurious messages.

 
shellcommands:

  "$(gnu)/gzip /var/log/*.[0-9] /var/log/*.[0-9][0-9]  > /dev/null 2>&1"

Cfengine will also recognize rotated files if they have been compressed, with suffixes `.Z', `.gz', `.rbz' or `.rbz'.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.12 Managing ACLs

Access control lists are extended file permissions. They allow you to open or close a file to a named list of users (without having to create a special group for those users). They also allow you to open or close a file for a named list of groups. Several unix-like operating systems have had access control lists for some time; but they do not seem to have caught on.

There is a number of reasons for this dawdling in the past. The tools for setting ACLs are generally interactive and awkward to use. Because a named list of users would lead to excessive verbosity in an ls -l listing, one does not normally see them. There is therefore the danger that the hidden information would lead to undetected blunders in opening files to the wrong users. ACLs are also different on every vendor's filesystems and they don't work over intersystem NFS. In spite of these reservations, ACLs are a great idea. Here at Oslo College, it seems that users are continually asking how they can open a file just for the one or two persons they wish to collaborate with. They have grown used to Novell/PC networks which embraced the technology from Apollo/NCS much earlier. Previously the Unix answer to users has always been: go ask the system administrator to make a special group for you. Then do the `chmod' thing. And then they would say: so what's so great about this Unix then?

Addressing this lack of standardization has been the job of a POSIX draft committee. Some vendors have made their implementations in the image of this draft. Solaris 2.6 has a good implementation. In spite of this, even these systems have only awkard tools for manipulating ACLs. Not the kind of thing you want to be around much, if you have better things to do. But the incompatibility argument applies only to multiple vendor headbutting. Some institutions who share data on a global basis opt for advanced solutions to network filesystems, such as AFS and DFS. Filesystems such as DCE's DFS make extensive use of file ACLs, and they are not operating system specific. Even so, DFS provides only interactive tools for examining and setting file permissions, and this is of little use to system administrators who would rather relegate that sort of thing to a script.

The need for this kind of thing is clear. Systems which make use of ACLs for security can be brought to their knees by changing a few ACLs. Take the Apollo/Domain OS as an example. All one needs to do to kill the system is to change a few ACLs and forget what they were supposed to be. Suddenly the system is crippled, nothing works. The only solution, if you don't have a backup, is to remove all of the security. Unix has a simpler security philosophy when it comes to the operating system files, but ACLs would be a valuable addition to the security of our data.

A cfengine bare-bones file-checking program looks like this:

 
#
# Free format cfengine program
#

 control:

   ActionSequence - ( files )

 files:

   classes::

     /directory/file  mode=644 
                      owner=mark,ds
                      group=users,adm
                      acl=zap 
                      action=fixplain

  # ... more below

This program simply checks the permissions and ownership of the named file. The regular file mode, owner and group are specified straightforwardly. The new feature here is the acl directive. It is a deceptively simply looking animal, but it hides a wealth of complexity. The zap is, of course, not an access control list. Rather, cfengine uses a system of aliases to refer to ACLs, so that the clutter of the complex ACL definitions does not impair the clarity of a file command. An ACL alias is defined in a separate part of the program which looks like this:

 
 # ...contd


 acl:

   { zap

   method:append
   fstype:solaris
   user:rmz:rwx
   user:len:r
   }

As you can see, an ACL is a compound object--a bundle of information which specifies which users have which permissions. Because ACLs are lists the alias objects must also know whether the items are to be appended to an existing list or whether they are to replace an existing list. Also, since the permission bits, general options and programming interfaces are all different for each type of filesystem, we have to tell cfengine what the filesystem type is.

It is possible to associate several ACL aliases with a file. When cfengine checks a files with ACLs, it reads the existing ACL and compares it to the new one. Files are only modified if they do not conform to the specification in the cfengine program. Let's look at a complete example:

 
 files:

   $(HOME)/myfile acl=acl_alias1 action=fixall

 acl:

   { acl_alias1

   method:append
   fstype:solaris
   user:len:rwx
   }

ACLs are viewed in Solaris with the command `getfacl'. Suppose that, before running this program, our test-file had permissions

 
   user:*:rwx
   user:mark:rwx           #effective:r-x
   group:*:r-x              #effective:r-x
   mask:r-x
   other:r-x
   default_user:rw-
   default_group:r--
   default_mask:-w-
   default_other:rwx

After the cfengine run, the ACL would become:

 
   user:*:rwx
   user:mark:rwx           #effective:r-x
   user:len:rwx            #effective:r-x
   group:*:r-x              #effective:r-x
   mask:r-x
   other:r-x
   default_user:rw-
   default_group:r--
   default_mask:-w-
   default_other:rwx

Suppose we wanted to to remove 'w' bit for user `jacobs', or make sure that it was never there.

 
	{ acl_alias1

	method:append
	fstype:solaris
	user:jacobs:-w
	}

Note that the method used here is append. That means that, whatever other access permissions we might have granted on this file, the user `jacobs' (a known cracker) will have no write permissions on the file. Had we used the method overwrite above, we would have eliminated all other access permissions for every user and added the above. If we really wanted to burn `jacobs', we could remove all rights to the file like this

 
  user:jacobs:noaccess

The keyword noaccess removes all bits. Note that this is not necessarily the same as doing a -rwx, since some filesystems, like DFS, have more bits than this. Then, if we want to forgive and forget, the ACLs may be removed for jacobs with the syntax

 
  user:jacobs:default

In Solaris, files inherit default ACLs from the directory they lie in; these are modified by the umask setting to generate their own default mask.

DFS ACLs look a little different. They are examined with the `acl_edit' command or with

 
dcecp -c acl show <filename>

In order to effect changes to the DFS, you have to perform a DCE login to obtain authentication cookies. The user `cell_admin' is a special user account for administrating a local DFS cell. Suppose we have a file with the following DCE ACL:

 
  mask_obj:r-x---
  user_obj:rwxcid
  user:cell_admin:r--c-- #effective:r-----
  group_obj:r-x--d       #effective:r-x---
  other_obj:r-x---

Now we want to add `wx' permissions for user `cell_admin', and add new entries with `rx' permissons for group acct-admin and user `root'. This is done with the following ACL alias:

 
   { acl_alias2

   method:append
   fstype:dfs
   user:/.../iu.hioslo.no/cell_admin:wx
   group:/.../iu.hioslo.no/acct-admin:rx
   user:/.../iu.hioslo.no/root:rx
   user:*:-x
   }

The local cell name `/.../iu.hioslo.no' is required here. Cfengine can not presently change ACLs in other cells remotely, but if your cfengine program covers all of the cell servers, then this is no limitation, since you can still centralize all your ACLs in one place. It is just that the execution and checking takes place at distributed locations. This is the beauty of cfengine. After running cfengine, with the above program snippet, the ACL then becomes:

 
  mask_obj:r-x---
  user_obj:rwcid
  user:cell_admin:rwxc-- #effective:r-x---
  user:root:r-x---       #effective:r-x---
  group_obj:r-x--d       #effective:r-x---
  group:acct-admin:r-x---
  other_bj:r-x---

For the sake of simplicity we have only used standard Unix bits `rwx' here, but more complicated examples may be found in DFS. For example,

 
 user:mark:+rwx,-cid

which sets the read, write, execute flags, but removes the control, insert and delete flags. In the DFS, files inherit the inital object ACL of their parent directory, while new directories inherit the initial container object.

The objects referred to in DFS as user_obj, group_obj and so forth refer to the owner of a file. i.e. they are equivalent to the same commands acting on the user who owns the file concerned. To make the cfengine user-interface less cryptic and more in tune with the POSIX form, we have dropped the `_obj' suffices. A user field of `*' is a simple abbreviation for the owner of the file.

A problem with any system of lists is that one can generate a sequence which does one thing, and then undoes it and redoes something else, all in the same contradictory list. To avoid this kind of accidental interaction, cfengine insists that each user has only one ACE (access control entry), i.e. that all the permissions for a given user be in one entry.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6. Using cfengine as a front end for cron

One of cfengine's strengths is its use of classes to identify systems from a single file or set of files. Many administrators think that it would be nice if the cron daemon also worked in this way. One possible way of setting up cron from a global configuration would be to use the cfengine editfiles facility to edit each cron file separately. A much better way is to use cfengine's time classes to work like a user interface for cron. This allows you to have a single, central cfengine file which contains all the cron jobs on your system without losing any of the fine control which cron affords you. All of the usual advantages apply:

The central idea behind this scheme is to set up a regular cron job on every system which executes cfengine at frequent intervals. Each time cfengine is started, it evaluates time classes and executes the shell commands defined in its configuration file. In this way we use cfengine as a wrapper for the cron scripts, so that we can use cfengine's classes to control jobs for mulitple hosts. Cfengine's time classes are at least as powerful as cron's time specification possibilities, so this does not restrict you in any way, See section 6.3 Building flexible time classes. The only price is the overhead of parsing the cfengine configuration file.

To be more concrete, imagine installing the following `crontab' file onto every host on your network:

 
#
# Global Cron file
#
0,15,30,45 * * * * /usr/local/cfengine/inputs/run-cfengine

This file contains just a single cron job, namely a script which calls cfengine. Here we are assuming that you will not want to execute any cron script more often than every fifteen minutes. If this is too restrictive, the above can be changed. We refer to the time interval between runs of the script `run-cfengine' as the `scheduling interval' and discuss its implications in more detail below.

The script `run-cfengine' would replace any `cfdaily' or `cfhourly' scripts which you might have, and can as simple as this

 
#!/bin/sh
#
# Script run-cfengine

export CFINPUTS=/usr/local/cfengine/inputs

/usr/local/gnu/bin/cfengine

#
# Should we pipe mail to a special user?
#

or it could be more fancy. You could also use the `cfwrap' script, if you have perl on all your systems, to pipe mail to the mail address described in the cfengine file. (See also the variable sysadm in the Reference manual).

 
#
# Global Cron file
#
0,15,30,45 * * * * path/cfwrap path/run-cfengine

You might not want to run your entire system configuration `cfengine.conf' every time cron fires up cfengine. An alternative would be to keep a separate fil for cron jobs called, say, `cf.cron'. You would then replace the `run-cfengine' file by

 
#!/bin/sh
#
# Script run-cfengine

export CFINPUTS=/usr/local/cfengine/inputs

/usr/local/gnu/bin/cfengine -f cf.cron

#
# Should we pipe mail to a special user?
#

There is no particular advantage to doing this unless you are running cfengine on some very slow hardware. A better way to approach the problem is to think of the `cf.cron' file as a module which can be imported into the main configuration file. This gives you the maximum amount of flexibilty, since it allows you to decide exactly what you want to happen any any given time from the central file.

6.1 Structuring `cfengine.conf'  
6.2 Splaying host times  
6.3 Building flexible time classes  
6.4 Choosing a scheduling interval  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.1 Structuring `cfengine.conf'

The structure of `cfengine.conf' needs to reflect your policy for running jobs on the system. You need to switch on relevant tasks and switch off unwanted tasks depending on the time of day. This can be done in three ways:

The last of these is the most efficient of the three, since cfengine does not even have to spend time parsing the files for actions which you know you will not want.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.2 Splaying host times

The trouble with starting every cfengine at the same time using a global cron file is that it might lead to contention or inefficiency. For instance, if a hundred cfengines all suddenly wanted to copy a file from a master source simultaneously this would lead to a big load on the server. We can prevent this from happening by introducing a time delay which is unique for each host and not longer than some given interval. Cfengine uses a hashing algorithm to generate a number between zero and a maximum value in minutes which you define, like this:

 
 control:
 
    SplayTime = ( 60 ) # minutes

If this number is non-zero, cfengine goes to sleep after parsing its configuration file and reading the clock. Every machine will go to sleep for a different length of time, which is no longer than the time you specify in minutes. A hashing algorithm, based on the fully qualified name of the host, is used to compute a unique time for hosts. The shorter the interval, the more clustered the hosts will be. The longer the interval, the lighter the load on your servers. This `splaying' of the run times will lighten the load on servers, even if they come from domains not under your control but have a similar cron policy.

Splaying can be switched off temporarily with the `-q' or `--no-splay' options.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.3 Building flexible time classes

Each time cfengine is run, it reads the system clock and defines the following classes based on the time and date:

Yrxx::
The current year, e.g. `Yr1997', `Yr2001'. This class is probably not useful very often, but it might help you to turn on the new-year lights, or shine up your systems for the new millenium!

Month::
The current month can be used for defining very long term variations in the system configuration, e.g. `January', `February'. These classes could be used to determine when students have their summer vacation, for instance, in order to perform extra tidying, or to specially maintain some administrative policy for the duration of a conference.

Day::
The day of the week may be used as a class, e.g. `Monday', `Sunday'.

Dayxx::
A day in the month (date) may be used to single out by date, e.g. the first day of each month defines `Day1', the 21st `Day21' etc.

Hrxx::
An hour of the day, in 24-hour clock notation: `Hr00'...`Hr23'.

Minxx::
The precise minute at which cfengine was started: `Min0' ... `Min59'. This is probably not useful alone, but these values may be combined to define arbitrary intervals of time.

Minxx_xx::
The five-minute interval in the hour at which cfengine was executed, in the form `Min0_5', `Min5_10' .. `Min55_0'.

Time classes based on the precise minute at which cfengine started are unlikely to be useful, since it is improbable that you will want to ask cron to run cfengine every single minute of every day: there would be no time for anything to complete before it was started again. Moreover, many things could conspire to delay the precise time at which cfengine were started. The real purpose in being able to detect the precise start time is to define composite classes which refer to arbitrary intervals of time. To do this, we use the group or classes action to create an alias for a group of time values. Here are some creative examples:

 
classes:  # synonym groups:

  LunchAndTeaBreaks = ( Hr12 Hr10 Hr15 )

  NightShift        = ( Hr22 Hr23 Hr00 Hr01 Hr02 Hr03 Hr04 Hr05 Hr06 )

  ConferenceDays    = ( Day26 Day27 Day29 Day30 )

  QuarterHours      = ( Min00 Min15 Min30 Min45 )

  TimeSlices        = ( Min01 Min02 Min03 Min33 Min34 Min35)

In these examples, the left hand sides of the assignments are effectively the ORed result of the right hand side. This if any classes in the parentheses are defined, the left hand side class will become defined. This provides a flexible and readable way of specifying intervals of time within a program, without having to use `|' and `.' operators everywhere.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.4 Choosing a scheduling interval

How often should you call your global cron script? There are several things to think about:

Cfengine has an intelligent locking and timeout policy which should be sufficient to handle hanging shell commands from previous crons so that no overlap can take place, See section 7.2.4 Spamming and security.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7. Cfengine and network services

This chapter describes how you can set up a cfengine network service to handle remote file distribution and remote execution of cfengine without having to open your hosts to possible attack using the rsh protocols.

7.1 Cfengine network services  
7.2 How it works  
7.3 Configuring cfservd  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.1 Cfengine network services

By starting the daemon called cfservd, you can set up a line of communication between hosts, allowing them to exchange files across the network or execute cfengine remotely on another system. Cfengine network services are built around the following components:

cfengine
The configuration engine, whose only contact with the network is via remote copy requests. This component does the hard work of configuring the system based on rules specified in the file `cfengine.conf'. It does not and cannot grant any access to a system from the network.

cfservd
A daemon which acts as both a file server and a remote-cfengine executor. This daemon authenticates requests from the network and processes them according to rules specified in `cfservd.conf'. It works as a file server and as a mechanism for starting cfengine on a local host and piping its output back to the network connection.

cfrun
This is a simple initiation program which can be used to run cfengine on a number of remote hosts. It cannot be used to tell cfengine what to do, it can only ask cfengine on the remote host to run the configuration file it already has. Anyone could be allowed to run this program, it does not require any special user privileges. A locking mechanism in cfengine prevents its abuse by spamming.

cfwatch
This program (which is not a part of the distribution: it is left for others to implement) should provide a graphical user interface for watching over the configuration of hosts running cfengine and logging their output.

With these components you can emulate programs like rdist whose job it is to check and maintain copies of files on client machines. You may also decide who has permission to run cfengine and how often it may be run, without giving away any special user privileges.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.2 How it works

7.2.1 Remote file distribution  
7.2.2 Remote execution of cfengine  
7.2.3 cfrun  
7.2.4 Spamming and security  
7.2.5 Some points on the cfservd protocol  
7.2.6 Deadlocks and runaway loops  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.2.1 Remote file distribution

This section describes how you can set up cfservd as a remote file server which can result in the distrubution of files to client hosts in a more democratic way than with programs like rdist.

An important difference between cfengine and other systems has to do with the way files are distributed. Cfengine uses a `pull' rather than a `push' model for distributing network files. The rdist command, for instance, works by forcing an image of the files on one server machine onto all clients. Files get changed when the server wishes it and the clients have no choice but to live with the consequences. Cfengine cannot force its will onto other hosts in this way, it can only signal them and ask them to collect files if they want to. In other words, cfengine simulates a `push' model by polling each client and running the local cfengine configuration script giving the host the chance to `pull' any updated files from the remote server, but leaving it up to the client machine to decide whether or not it wants to update.

Also, in contrast to programs like rdist which distribute files over many hosts, cfengine does not require any general root access to a system using the `.rhosts' file or the `/etc/hosts.equiv' file. It is sufficient to run the daemon as root. You can not run it by adding it to the `/etc/inetd.conf' file on your system however. The restricted functionality of the daemon protects your system from attempts to execute general commands as the root user using rsh.

To remotely access files on a server, you add the keywork server=host to a copy command. Consider the following example which illustrates how you might distribute a password file from a masterhost to some clients.

 
copy:

  PasswdClients::

    /etc/passwd  dest=/etc/passwd owner=root group=0 server=server-host

Given that the cfservd daemon is running on server-host, cfengine will make contact with the daemon and attempt to obtain information about the file. During this process, cfengine verifies that the system clocks of the two hosts are reasonably synchronized. If they are not, it will not permit remote copying. If cfengine determines that a file needs to be updated from a remote server it begins copying the remote file to a new file on the same filesystem as the destination-file. This file has the suffix `.cfnew'. Only when the file has been successfully collected will cfengine make a copy of the old file, (see repository in the Reference manual), and rename the new file into place. This behaviour is designed to avoid race-conditions which can occur during network connections and indeed any operations which take some time. If files were simply copied directly to their new destinations it is conceivable that a network error could interrupt the transfer leaving a corrupted file in place.

Cfengine places a timeout of a few seconds on network connections to avoid hanging processes.

Normally the daemon sleeps, waiting for connections from the network. Such a connection may be initiated by a request for remote files from a running cfengine program on another host, or it might be initiated by the program cfrun which simply asks the host running the daemon to run the cfengine program locally.

Make sure that you are running cfengine from a shell which has sensible limits set. The error `too many open files' can occur in long recursions if you only have a small number of valid descriptors per shell. It is probably a good idea to set the number of descriptors to 1024.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.2.2 Remote execution of cfengine

It is a good idea to execute cfengine by getting cron to run it regularly. This ensures that cfengine will be run even if you are unable to log onto a host to run it yourself. Sometimes however you will want to run cfengine immediately in order to implement a change in configuration as quickly as possible. It would then be inconvenient to have to log onto every host in order to do this manually. A better way would be to issue a simple command which contacted a remote host and ran cfengine, printing the output on your own screen:

 
myhost% cfrun remote-host -v

 output....

A simple user interface is provided to accomplish this. cfrun makes a connection to a remote cfservd-daemon and executes cfengine on that system with the privileges of the cfservd-daemon (usually root). This has a two advantages:

A potential disadvantage with such a system is that malicious users might be able to run cfengine on remote hosts. The fact that non-root users can execute cfengine is not a problem in itself, after all the most malicious thing they would be able to do would be to check the system configuration and repair any problems. No one can tell cfengine what to do using the cfrun program, it is only possible to run an existing configuration. But a more serious concern is that malicious users might try to run cfengine repeatedly (so-called `spamming') so that a system became burdened with running cfengine constantly, See section 7.2.4 Spamming and security.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.2.3 cfrun

The syntax of the cfrun command is

 
  cfrun -option --longoption class1 class2 ...

With the exception of the `-d' and `-S' options, all options are passed on to the remote hosts and are ignored locally. The `-q' option is always assumed when executing cfengine remotely, so that SplayTime is effectively zero when polling hosts serially. If an option includes a name such as `-Dnewclass', there should not be a space between the option letter and the name string. The remaining options are treated as classes to be sent to all the hosts on the network.

Each host evaluates the classes sent by cfrun and decides whether cfengine should be invoked. Only hosts which belong to the classes defined on the cfrun command line are executed. This allows you to single out groups of hosts which should execute cfengine, based on the very classes which you have defined for your configuration. If no classes are sent on the command line, then all hosts are run.

cfrun uses a configuration file which is located under the CFINPUTS directory in order to determine which hosts and in which order it should try to connect. Because cfengine always uses a reliable TCP protocol for connections, it verifies each connection rather than simply broadcasting openly. Using this file you can even simulate broadcasting to hosts outside your subnet.

This file should contain every host name you ever want to configure remotely, because you can still select subsets of the file by specifying classes which the remote host will understand. If the remote host is not in one of the classes you specify when you run cfrun, then it will simply ignore the request. Conversely, if you do not place a host in this file, it will never be contacted when you use the cfrun command. The format of the file is as follows

 
 #
 # Comment ..
 #
 domain=my.domain
 access=user1,user2

 hostname1 options
 hostname2 options
 ...

It is important to add the domain-name to this file. The options you specifiy in this file, per host, are added to those you might specify on the command line when invoking cfengine remotely. For instance, you might know of a bug on one host and decide not to perform interface configuration on that one machine. You would write a line like this:

 
  funny.domain -i  # problem host

You could use cfrun inside one of your cfengine configuration files in order to remotely execute cfengine on all of the other network machines, by setting up a host list. Be careful not to include the name of the master host in the list. The locks should prevent cfengine from being run on the masterhost, avoiding an infinite loop. This way you do not have to rely on cron running on every system. The disadvantage however is that cfengine has to poll the systems on the network, which means that cfengine cannot be working in parallel on all hosts. This could be inefficient in the long run.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.2.4 Spamming and security

The term `spamming' refers to the senseless repetition of something in a malicious way intended to drive someone crazy(5). In the computer world some malicious users, a bit like `flashers' in the park(6) like to run around the net a reveal themselves ad nauseum by sending multiple mail messages or making network connections repeatedly to try to overload systems and people(7).

Whenever we open a system to the network, this problem becomes a concern. Cfengine is a tool for making peace with networked systems, not a tool to be manipulated into acts of senseless aggression. The cfengine daemon does make it possible for anyone to connect and run a cfengine process however, so clearly some protection is required from such attacks.

Cfengine's solution to this problem is a locking mechanism. Rather than providing user-based control, cfengine uses a time based locking mechanism which prevents actions from being executed unless a certain minimum time has elapsed since the last time they were executed. By using a lock which is not based on user identity, we protect several interests in one go:

Cfengine is controlled by a series of locks which prevent it from being run too often, and which prevent it from spending too long trying to do its job. The locks work in such a way that you can start several cfengine processes simultaneously without them crashing into each other. Coexisting cfengine processes are also prevented from trying to do the same thing at the same time (we call this `spamming'). You can control two things about each kind of action in the action sequence:

You can set these values either globally (for all actions) or for each action separately. If you set global and local values, the local values override the global ones. All times are written in units of minutes.

 
   actionsequence
     (
     action.IfElapsedtime-in-mins
     action.ExpireAftertime-in-mins
     )

or globally,

 
  control:

     IfElapsed   = ( time-in-mins )

     ExpireAfter = ( time-in-mins )

For example:

 
 control:

   actionsequence = 
     (
     files.IfElapsed240.ExpireAfter180
     copy
     tidy
     )

   IfElapsed = ( 30 )

In this example, we treat the files action differently to the others. For all the other actions, cfengine will only execute the files part of the program if 30 minutes have elapsed since it was last run. Since no value is set, the expiry time for actions is 60 minutes, which means that any cfengine process which is still trying to finish up after 60 minutes will be killed automatically by the next cfengine which gets started.

As for the files action: this will only be run if 240 minutes (4 hours) have elapsed since the last run. Similarly, it will not be killed while processing `files' until after 180 minutes (3 hours) have passed.

These locks do not prevent the whole of cfengine from running, only so-called `atoms'. Several different atoms can be run concurrently by different cfengines. Assuming that the time conditions set above allow you to start cfengine, the locks ensure that atoms will never be started by two cfengines at the same time, causing contention and wasting CPU cycles. Atoms are defined to maximize the security of your system and to be efficient. If cfengine were to lock each file it looked at seperately, it would use a large amount of time processing the locks, so it doesn't do that. Instead, it groups things together like this:

copy, editfiles, shellcommands
Each separate command has its own lock. This means that several such actions can be processed concurrently by several cfengine processes. Multiple or recursive copies and edits are treated as a single object.

netconfig, resolve, umount, mailcheck, addmounts, disable, processes
All commands of this action-type are locked simultaneously, since they can lead to contention.

mountall, mountinfo, required, checktimezone
These are not locked at all.

Cfengine creates a directory `~/.cfengine' for writing lock files for ordinary users.

The option `-K' or `--no-lock' can be used to switch off the locking checks, but note that when running cfengine remotely via cfservd, this is not possible.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.2.5 Some points on the cfservd protocol

Cfservd uses a form for host-based authorization. Each atomic operation, such as statting, getting files, reading directories etc, requires a new connection and each connection is verified by a double reverse lookup in the server's DNS records. Single stat structures are cached during the processing of a file.

MD5 checksums are transferred from client to server to avoid loading the server. Even if a user could corrupt the MD5 checksum, he or she would have to get past access control with TCP wrappers and the worst that could happen would be to get the right version of the file. Again this is in keeping with the idea that users can only harm themselves and not others with cfengine.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.2.6 Deadlocks and runaway loops

Whenever we allow concurrent processes to share a resource, we open ourselves up the possibilty of deadlock. This is a situation where two or more processes are locked in a vicious stalemate from which none can escape. Another problem is that it might be possible to start an infinite loop: cfengine starts itself.

Cfengine protects you from such loops to a large degree. It should not be possible to make such a loop by accident. The reason for this is the locking mechanism which prevents tasks being repeated too often. If you start a cfengine process which contains a shell-command to start cfengine again, this shell command will be locked, so it will not be possible to run it a second time. So while you might be able to start a second cfengine process, further processes will not be started and you will simply have wasted a little CPU time. When the first cfengine returns, the tasks which the second cfengine completed will not be repeated unless you have set the IfElapsed time or the ExpireAfter time to zero. In general, if you wish to avoid problems like this, you should not disable the locking mechanism by setting these two times to zero.

The possibility of deadlock arises in network connection. Cfengine will not attempt to use the network to copy a file which can be copied internally from some machine to itself. It will always replace the server= directive in a copy with `localhost' to avoid unnecessary network connections. This prevents one kind of deadlock which could occur: namely cfrun executes cfengine on host A (cfservd on host A is then blocked until this completes), but the host A configuration file contains a remote copy from itself to itself. This remote copy would then have to wait for cfservd to unblock, but this would be impossible since cfservd cannot unblock until it has the file. By avoiding remote copies to localhost, this possibility is avoided.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.3 Configuring cfservd

7.3.1 Installation of cfservd  
7.3.2 Configuration file `cfservd.conf'  
7.3.3 TCP wrappers  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.3.1 Installation of cfservd

To install the cfengine daemon component, you will need to register a port for cfengine by adding the following line to the system file `/etc/services file'
 
   cfengine        5308/tcp

You could do this for all hosts by adding the following to your cfengine configuration
 
editfiles:

  { /etc/services

   AppendIfNoSuchLine "cfengine        5308/tcp"
  }

To start cfengine at boot time, you need to place a line of the following type in your system startup files:

 
# Start cfengine server
cfservd

Note that cfservd will reread its configuration file whenever it detects that it has been changed, so you should not have to restart the daemon, not send it the HUP signal as with other daemons.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.3.2 Configuration file `cfservd.conf'

The server daemon is controlled by a file called `cfservd.conf'. The syntax of this configuration file is deliberately modelled on cfengine's own configuration file, but despite the similarities, you cannot mix the contents of the two files.

Though they are not compatible, `cfengine.conf' and `cfservd.conf' are similar in several ways:

Note that the classes in the `cfservd.conf' file do not tell you the classes of host which have access to files and directories, but rather which classes of host pay attention to the access and deny commands when the file is parsed.

Host name authentication is not by class or group but by hostname, like the `/etc/exports' file on most unix systems. The syntax for the file is as follows:

 
 control:

   classes::

       domain = ( DNS-domain-name )

       cfrunCommand = ( "script/filename" )  # Quoted

       AutoExecCommand = ( "cfengine-start-script" )

       AutoExecInterval = ( 60 )

       MaxConnections = ( maximum number of forked daemons )

       ChecksumDatabase = ( filename )

       IfElapsed = ( time-in-minutes )

       DenyBadClocks = ( false )

       AllowConnectionsFrom = ( IP numbers )

       DenyConnectionsFrom = ( IP numbers )

       AllMultipleConnectionsFrom = ( IP numbers )

       LogAllConnections = ( false/true )

       SkipVerify = ( IP numbers )

 groups:

   Group definitions

 import:

   Files to import

 admit: | grant:

   classes::

      /file-or-directory

        wildcards/hostnames

 deny:

   classes::

      /file-or-directory

        wildcards/hostnames root=hostlist secure=true/on

The file consists of a control section and access information. You may use the control section to define any variables which you want to use in the remainder of your file. Two variables are special here, they are reserved.

cfrunCommand
This string is the command which you would like to be executed remotely by the cfrun command.

AutoExecCommand
This is the name of a command which you use to execute cfengine automatically after the interval specified in AutoExecInterval. Since the output route is ambiguous for a daemon, you should provide a wrapper for cfengine which mails you the output, just as you would with cron. This script should not normally produce any output itself. Any output will go to syslog.

AutoExecInterval
A number of minutes after which you would like cfengine to be run, even if you do not force a run with cfrun. This can be used instead of, or in addition to cron. If used with cron, take precautions to set suitable values for IfElapsed so that unnecessary overlap is avoided.

MaxConnections
This integer value sets a limit on the maximum number of child daemon threads which cfservd will `fork' in order to handle remote requests. The default value is ten.

IfElapsed
The IfElapsed anti-spamming filter is also built into cfservd so that a remote user cannot even get as far as causing cfengine to parse its input files (which could be used for spamming in itself). The time is in minutes, the default is one hour.

ChecksumDatabase
This is the path and filename to a database which will cache MD5 checksum values server-side. This optimization is only available if you have the Berkeley database library `libdb' on your system. If this variable is not defined, no database caching will be used and checksum values will be computed directly on request. The utility of this solution is a trade-off between the time it takes to compute the checksum versus the time for a disk-based lookup.

DenyBadClocks
If this is set to off, cfservd will not deny access to clients whose clocks are off by more than one hour. The default is to deny access to systems whose clocks differ by more than one hour. This can prevent messages of the form `Can't stat' file when remote copying.

AllowConnectionsFrom
This variable allows a list of numerical IP masks to be specified, which cfservd will allow connections from. If the list is not empty and a host whose IP address is not specified attempts to connect to the daemon, its connection will be closed immediately. This can be used to prevent hanging connection attacks from malicous hosts and other denial of service attacks which would bind thread resources.
 
     control:

      AllowConnectionsFrom = ( 128.39.89  192.2.0.10 )

DenyConnectionsFrom

Hosts which are included by the allow-list above can be explicitly denied access using this list.
 
     control:

      DenyConnectionsFrom = ( 128.39.89.76 )  # rogue host

AllowMultipleConnectionsFrom
This variable should contain a list of IP wildcards to hosts which are allowed simultaneous sessions on the server. Hosts which are not in this list are allowed to connect only once, i.e. they must terminate and reconnect in order to establish a new session. This is to prevent a possible attacker from opening multiple sockets and never closing them, resulting in a denial of service attack. Hosts IP's can be placed here if they could have overlapping copy sessions (e.g. long backup transfers which can run over time). This prevents the error message "Multiple connections denied/spam shield".

This replaces the AllowMultipleConnections boolean variable which existed in version 1.5.4 (only).

SkipVerify

If connecting hosts use a Network Address Translator in order to share an IP address, reverse lookup will fail to give a correct verification of host identity. You can switch off cfservd's verification of host identity for specific IP addresses or patterns using this command. E.g.

 
SkipVerify = ( 192.0.0.10  192.0.2.  )

NOTE!! This is a security risk because it means that cfservd implicitly trusts the connecting hosts! You should be very careful in using Network Address Translators in a secure environment. It is not recommended for sites which require a high level of security.

LogAllConnections
If set to true, every successful connection will be logged to syslog. This could be useful for identifying abuses of the service, if the server should come under attack, e.g. a denial of service attack. The IP address can then be excluded from the allowed connections list.

root=
This list specificies the names of hosts which are to have read access to files, regardless of the owner of the file. This effectively gives root users on connecting hosts privileges to non-root owned files on the server, but not vice-versa, similar to the NFS root mapping, except that there is no question of a client being able to modify files on the server. Caution: cfservd trusts the DNS service, so be aware that cache poisoning attacks are a possible way of bypassing access controls.

secure=true
If this option is set, cfservd will only serve the named files if the copy access type is secure, i.e. on an encrypted link. This presupposes that cfengine has been compiled with a working DES or SSLeay library.

Following the control section comes a list of files or directories and hosts which may access these. If permissions are granted to a directory then all sub directories are automatically granted also. Note that symbolic links are not checked for, so you may need to specifically deny access to links if they are plain files, but cfservd does not follow symbolic links and give access to files in other directories.

Fully qualified hostnames should be given in this file. Do not forget to define the domain name. Authentication calls the unix function gethostbyname() and so on to identify and verify connecting hosts, so the names in the file must reflect the type on names returned by this function. You may use wildcards in names to match, for instance, all hosts from a particular domain.

Here is an example file
 
#####################################################
#
# This is a cfservd config file
#
#####################################################
 
groups:

  PasswdHost = ( nexus )

#####################################################
  
control:
  
  #
  # Assuming CFINPUTS is defined
  #

  cfrunCommand = ( "/usr/local/bin/cfengine" )  

  variable = ( /usr/local/publicfiles )

#####################################################
  
admit:   # Can also call this grant:
 
   PasswdHost::
 
     /etc/passwd
 
        *.iu.hioslo.no
 
    FtpHost::

    # An alternative to ftp, grant anyone 

       /local/ftp/pub
 
         *

    any::

       $CFINPUTS/cfrun.sh

         *.iu.hioslo.no

#####################################################
 
deny:
 
   /etc/services
 
       borg.iu.hioslo.no

  /local/ftp

       *.pain-in-the-ass.com


NOTE I: cfservd is not rpc.mountd, access control is by filename, not by device name. Do not assume that files lying in subdirectories are not open for access simply because they lie on a different device. You should give the real path name to file and avoid symbolic links.

NOTE II: access control is per host and per user. User names are assumed to be common to both hosts. There is an implicit trust relationship here. There is no way to verify whether the user on the remote host is the same user as the user with the same name on the local host.

If you still have problems with lack of access, it could be that you have forgotten to define the domain name for your network, or that you do not understand the TCP wrappers files `/etc/hosts.access' and `/etc/hosts.deny'.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.3.3 TCP wrappers

Cfengine tries to incorporate the TCP wrappers package if you have it on your system. If you do, then the files `/etc/hosts.allow' and `/etc/hosts.deny' allow you to give the cfengine/cfservd service an extra level of protection from `clever' spoofing attempts.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8. Security and cfengine

8.1 Security hints  
8.2 Checksum Databases  
8.3 Whom do you trust?  
8.4 Firewalls  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.1 Security hints

Cfengine is not specifically a tool for implementing high security solutions for system administration, but it has many features which can be used to monitor the state of your systems and warn about potential breaches in security. Here are some suggestions as to how you can be more security conscious with cfengine's help.

CERT advisories
The CERT coordination centre (Computer Emergency Response Team) publishes warnings about known bugs and security risks in computer systems which can lead to compromised security. Their recommendations often involve disabling certain programs, changing permissions to remove setuid root flags and editing configuration files. These are things which you can deal with using cfengine.

disabling binaries
When to elect to disable a file, cfengine renames it, moves it to a file repository (if you have defined one) and changes the mode of the file to read only for its owner. This is sufficient to disable binary programs and plain files.

The setuid log
Cfengine is always on the lookout for files which are setuid or setgid root. It doesn't go actively looking for them, but whenever you get cfengine to check a file or directory with the files feature, it will make a note of setuid programs it finds there. These are recorded in the file `cfengine.host.log' which is stored under `/etc/cfengine' or `/var/log/cfengine'. When new setuid programs are discovered, a warning is printed, but only if you are root. If you ever want a complete list, delete the log file and cfengine will think that all of the setuid programs it finds are new. The log file is not readable by normal users.

ChecksumDatabase
In files you can set the option checksum=md5 which will result in the md5 value of the named file being cached in a database for future reference. If the file changes in any way this will be registered and a security warning will be issued. This gives cfengine behaviour like Tripwire.

Suspicious filenames
Whenever cfengine opens a directory and scans through files (files, tidy, copy), it is on the lookout for suspicious filenames, i.e. files like `.. .' containing only space and/or dots. Such files are never created by sensible people, but are often used by hackers to try to hide dangerous programs. Cfengine prints warnings about such files. The variable list FileExtensions may be used to detect concealed directories during these searches, if users create directories which look like common files.

Spoofing
Spoofing refers to attempts to masquerade as another host when sending network transmissions. The cfservd program attempts to unmask such attempts by performing double reverse lookups in the name service. This verifies by a trusted server that the socket address and the host name are really who they claim to be. If you have the TCP wrappers package on your system (libwrap) then cfservd will attempt to use it to detect other spoofs too, See section 7.3.3 TCP wrappers. If you don't have TCP wrappers, then the only line of defense is the double reverse lookup.

Race conditions in file copying
When copying files from a source, it is possible that something might go wrong during the operation and leave a corrupt file in place. For example, the disk might become full while copying a file. This could lead to problems. Cfengine deals with this by always copying to a new file on the destination filesystem (prefix `.cfnew') and then renaming it into place, only if the transfer was successful. This ensures that there is space on the filesystem and that nothing went wrong with the network connection or the disk during copying.

size= in copy
As a further check on copying, cfengine allows you to define acceptable limits on the size of files. After all, sometimes errors might occur quite independently of anything you are doing with cfengine. Perhaps the master password file got emptied somehow, or got replaced by a binary, through some silly mistake. By checking making an estimate of the expected size of the file and adding it to the copy command, you can avoid installing a corrupt file and making a localized problem into a global one.

useshell= in shellcommands
There are dangers in starting scripts from programs which run with root privileges. Normally, shell commands are started by executing them with the help of a `/bin/sh -c' command. The trouble with this is that it leaves one open to a variety of attacks. One example is fooling the shell into starting foreign programs by manipulating the IFS variable to treat '/' as a separator. You can ask cfengine to start programs directly, without involving an intermediary shell, by setting the useshell variable to false. The disadvantage is that you will not be able to use shell directives such as `|' and > in your commands.

warnnonusermail and warnnonownermail in control
Some users try to hide files in the mail spool directory since they have write access to it. Using the above and their corresponding `delete' functions, you can check whether someone has tried to place a bogus file in the mail directory. A bogus file is identified as being one which either does not belong to a user on the system, or which does not have the name of a user on the system.

Using cfengine to restart daemons
Always remember that processes which are started by a script or by cfengine inherit the environment variables which the parent script has, including the timezone, path and umask. If you are unwary, you might end up resetting the system clock or permission mask for certain services. Be careful.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.2 Checksum Databases

Cfengine can be used to check for changes in files which only something as exacting as an MD5 checksum/digest can detect. If you define a checksum database and activate checksum verification,

 
control:

  ChecksumDatabase = ( /etc/cfengine/cache.db )

files:

   /filename checksum=md5 ....

cfengine will build a Berkeley db database of file checksums and warn you when files' checksums change. This gives cfengine Tripwire functionality. It can be used to show up Trojan horse versions of programs. It should be used sparingly though since database management and MD5 checksum computation are resource intensive opoerations and this could add significant time to a cfengine run.

NOTE! Warnings are usually unecessary. If you are worried about the integrity of the system then don't bother warning about checksum mismatches here. Make an md5 copy comparison with a read only medium which has correct versions of the program on it. That way if a binary is compromised you will not only warn about it but also repair the damage immediately!

The control variable ChecksumUpdates may be switched to on in order to force cfengine to update its checksum database after warning of a change. The default value of this variable is off for cfengine but on for cfservd. This is because cfservd uses a database as a cache, while cfengine uses it as a security check.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.3 Whom do you trust?

All the developments of the last few years point to the unpleasant fact that we need to be extra security conscious on the net. In order to have any meaningful discussion about security, you need to determine who you trust and who you don't trust. No one from outside your network can force cfengine to do anything you don't want it to do (unless root access to your system has been compromised by another route), but you might decide to collect a file from a remote server which could sabotage your system a treat. Cfengine does not implement more exacting security than normal host validation. If you are collecting files from remote servers, you should make sure that they come from a machine that you trust, particularly if they are files which could lead to privileged access to your system. Cfengine places the responsibility on you. You can make cfengine destroy your system, but no one else can, so make sure you think about what you are doing.

For example, it would be an extremely foolish idea to copy a binary program such as `/bin/ps' from a host you know nothing about. This program runs as root. If someone were to replace that version of `ps' with a trojan horse command, you would have effectively opened your system to attack.

In remote copies you are setting up an implicit trust relationship. First of all you trust integrity of the host you are collecting files from. Secondly you trust that they have the same username database with regard to access control. The root user on the collecting host has the same rights ro read files as the root user on the server. The same applies to any matched user name. A non-matched username has the same rights as nobody.

Cfengine performs no cryptographic coding of messages at present, so if you are sending sensitive data via cfengine, it should be coded in advance.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.4 Firewalls

Cfengine is a useful tool for implementing, monitoring and maintaining firewalls. You can control what programs are supposed to be on the firewall and what programs are not supposed to be there. You can control file permissions, processes and a dozen other things which make up the configuration of a bastion host. At some point in the future this space might expand into a discussion about how you set up a bastion host using cfengine.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

Variable Index

Jump to:   !   "   $   '   -   /   `  
A   B   C   D   E   F   H   I   M   O   R   S   T   U  

Index Entry Section

!
!4.1 Classes

"
"4.11 Quoted strings

$
$(arch)4.2 Variable substitution
$(binserver)4.2 Variable substitution
$(class)4.2 Variable substitution
$(cr)4.2 Variable substitution
$(date)4.2 Variable substitution
$(dblquote)4.2 Variable substitution
$(dollar)4.2 Variable substitution
$(domain)4.2 Variable substitution
$(faculty)4.2 Variable substitution
$(fqhost)4.2 Variable substitution
$(host)4.2 Variable substitution
$(ipaddress)4.2 Variable substitution
$(lf)4.2 Variable substitution
$(n)4.2 Variable substitution
$(quote)4.2 Variable substitution
$(site)4.2 Variable substitution
$(spc)4.2 Variable substitution
$(sysadm)4.2 Variable substitution
$(tab)4.2 Variable substitution
$(timezone)4.2 Variable substitution
$(year)4.2 Variable substitution

'
'4.11 Quoted strings

-
-a option4.2 Variable substitution
-D option4.1 Classes
-f option3.4 Invoking cfengine
-f option3.5 CFINPUTS environment variable
-h option3.4 Invoking cfengine
-n option3.4 Invoking cfengine
-N option4.1 Classes
-N option4.6 Debugging tips
-v option3.4 Invoking cfengine

/
/etc/cfengine/cfengine.log4.10 Log files written by cfengine
/etc/exports5.2 Using netgroups

`
`4.11 Quoted strings

A
acl5.12 Managing ACLs
any4.5 The generic class any

B
binserver4.2 Variable substitution
binserver5.6.4 Special variables
binserver5.6.4 Special variables

C
CFALLCLASSES4.2 Variable substitution
ChecksumDatabase8.1 Security hints
ChecksumUpdates8.2 Checksum Databases

D
domain4.2 Variable substitution

E
exclude=4.9 Recursive file sweeps/directory traversals
exec4.2 Variable substitution

F
faculty4.2 Variable substitution
filter=4.9 Recursive file sweeps/directory traversals

H
host4.2 Variable substitution

I
include=4.9 Recursive file sweeps/directory traversals

M
MaxCfengines4.2 Variable substitution
moduledirectory4.4.5 Writing plugin modules

O
OutputPrefix4.2 Variable substitution

R
repchar4.2 Variable substitution

S
site4.2 Variable substitution
split4.2 Variable substitution
split4.13 Iterating over lists
sysadm4.2 Variable substitution

T
timezone4.2 Variable substitution

U
underscoreclasses4.2 Variable substitution
underscoreclasses4.2 Variable substitution

Jump to:   !   "   $   '   -   /   `  
A   B   C   D   E   F   H   I   M   O   R   S   T   U  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

Concept Index

Jump to:   !   -   .   /  
A   B   C   D   E   F   G   H   I   L   M   N   O   P   Q   R   S   T   U   V   W   Y  

Index Entry Section

!
!4.1 Classes

-
-d option in cfrun7.2.3 cfrun
-h option3.4 Invoking cfengine
-N option4.6 Debugging tips
-S option in cfrun7.2.3 cfrun

.
`.cfdisabled' files5.9 Disabling and the file repository
.cfengine.rm4.10 Log files written by cfengine
.cfnew8.1 Security hints
`.cfnew' files7.2.1 Remote file distribution
`.cfsaved' files5.9 Disabling and the file repository

/
/bin/sh -c problem.8.1 Security hints
`/etc/cfengine'8.1 Security hints
/etc/cfengine/cfengine.log4.10 Log files written by cfengine
`/etc/hosts.equiv'5.9 Disabling and the file repository
`/etc/inetd.conf' file and cfengine7.2.1 Remote file distribution
`/home'5.7 Using the automounter
`/users'5.7 Using the automounter
`/var/adm/wtmpx'5.9 Disabling and the file repository
`/var/log/cfengine'8.1 Security hints
/var/log/cfengine/cfengine.log4.10 Log files written by cfengine
`/var/lp/logs/lpsched'5.9 Disabling and the file repository

A
Access control4.7 Access control
Access control by directory7.3.2 Configuration file `cfservd.conf'
Access control in cfservd7.3.2 Configuration file `cfservd.conf'
Access control lists5.12 Managing ACLs
ACL aliases5.12 Managing ACLs
ACLs5.12 Managing ACLs
ACLs, DFS5.12 Managing ACLs
ACLs, solaris5.12 Managing ACLs
Actions, order of3.2 Program structure
AFS5.7 Using the automounter
AllowConnectionsFrom variable7.3.2 Configuration file `cfservd.conf'
Annulling entries when debugging4.6 Debugging tips
Atomic operations in cfengine7.2.4 Spamming and security
Atoms in cfengine7.2.4 Spamming and security
`auto_direct'5.7 Using the automounter
`auto_master'5.7 Using the automounter
AutoExecInterval variable7.3.2 Configuration file `cfservd.conf'
automount5.7 Using the automounter

B
Backup policy5.3 Files and links
Binary server5.6.1 NFS filesystem resources
Binary server, matching5.6.4 Special variables
Binary servers, declaring5.6.3 How does it work?
binserver variable and actionsequence5.6.4 Special variables
Broadcasts to the cfengine service.7.2.3 cfrun

C
CERT advisories8.1 Security hints
CFALLCLASSES4.2 Variable substitution
cfengine model5.6 Cfengine's model for NFS-mounted filesystems
cfengine model, how it works5.6.3 How does it work?
cfengine, starting3.4 Invoking cfengine
`cfengine.conf'3.4 Invoking cfengine
`cfengine.conf'3.5 CFINPUTS environment variable
`cfengine.conf' file7.1 Cfengine network services
CFINPUTS variable3.5 CFINPUTS environment variable
CFINPUTS variable7.3.2 Configuration file `cfservd.conf'
cfrun4.7 Access control
cfrun program7.1 Cfengine network services
cfrun program7.2.1 Remote file distribution
cfrun program7.2.2 Remote execution of cfengine
cfrunCommand variable7.3.2 Configuration file `cfservd.conf'
cfservd and access keyword4.7 Access control
cfservd daemon7.1 Cfengine network services
cfservd dameon7.2.2 Remote execution of cfengine
`cfservd.conf' file7.1 Cfengine network services
`cfservd.conf' file7.3.2 Configuration file `cfservd.conf'
cfwatcher program7.1 Cfengine network services
ChecksumDatabase8.1 Security hints
ChecksumDatabase variable7.3.2 Configuration file `cfservd.conf'
ChecksumUpdates8.2 Checksum Databases
Class data and scripts4.2 Variable substitution
Class, generic any4.5 The generic class any
Classes4.1 Classes
Classes based on shell commands4.4.3 shellcommand classes
Classes, compound4.1 Classes
Classes, defining and undefining4.1 Classes
Clock synchronization during copying7.2.1 Remote file distribution
Comments3.2 Program structure
Compound classes4.1 Classes
Computer emergency response team8.1 Security hints
Config file, default name3.4 Invoking cfengine
Contention during copying under load6.2 Splaying host times
Control files2.3.1 Control files
copy, file sweeps4.9 Recursive file sweeps/directory traversals
core files, caution!5.3 Files and links
Cron jobs, controlling with cfengine6. Using cfengine as a front end for cron

D
Day of the week6.3 Building flexible time classes
Deadlock protection7.2.6 Deadlocks and runaway loops
Debugging, annulling entries4.6 Debugging tips
Default file3.4 Invoking cfengine
Defining variables using other variables4.2 Variable substitution
DenyBadClocks variable7.3.2 Configuration file `cfservd.conf'
DenyConnectionsFrom variable7.3.2 Configuration file `cfservd.conf'
Device boundaries and remote copy access7.3.2 Configuration file `cfservd.conf'
DFS5.7 Using the automounter
DHCP2.3.2 Network interface
Directory Names, use of wildcards4.8 Wildcards in directory names
Disk full, problems during copying8.1 Security hints
DNS2.3.4 Name servers (DNS)
Dots in hostnames4.1 Classes

E
editfiles, file sweeps4.9 Recursive file sweeps/directory traversals
Environment variable, CFINPUTS3.5 CFINPUTS environment variable
Environment variables4.2 Variable substitution
Environment variables4.2 Variable substitution
Environment variables, inheritance8.1 Security hints
Exceptions4.4 Defining classes and making exceptions
exclude=4.9 Recursive file sweeps/directory traversals
exclude=, problems4.9 Recursive file sweeps/directory traversals
Excluding actions in a controlled way4.4 Defining classes and making exceptions
ExpireAfter, caution setting to zero!7.2.6 Deadlocks and runaway loops
Exporting filesystems5.2 Using netgroups
Exporting filesystems5.6.4 Special variables

F
File search paths3.5 CFINPUTS environment variable
Files, checking permissions2.3.5 Monitoring important files
Files, configuration2.3.1 Control files
Files, control2.3.1 Control files
files, file sweeps4.9 Recursive file sweeps/directory traversals
filter=4.9 Recursive file sweeps/directory traversals
Format3.2 Program structure
Free format3.2 Program structure
Fully qualified names4.1 Classes

G
Grouping time values6.3 Building flexible time classes
groups and time intervals6.3 Building flexible time classes

H
Hard class name collision4.2 Variable substitution
Hard links2.3.6 Making links
Help3.4 Invoking cfengine
Home directories and automount5.7 Using the automounter
Home server5.6.1 NFS filesystem resources
Home servers, declaring5.6.3 How does it work?
Host name gets truncated4.1 Classes
Hostname collision4.2 Variable substitution
HUP and cfservd, don't need to7.3.1 Installation of cfservd

I
ifconfig2.3.2 Network interface
IfElapsed, caution setting to zero!7.2.6 Deadlocks and runaway loops
ignore=4.9 Recursive file sweeps/directory traversals
Ignoring, private lists in files, copy and links4.9 Recursive file sweeps/directory traversals
include=4.9 Recursive file sweeps/directory traversals
Infinite loops7.2.6 Deadlocks and runaway loops
Invoking cfengine3.4 Invoking cfengine
Iteration over lists4.13 Iterating over lists

L
Linking to binservers5.6.4 Special variables
Links2.3.6 Making links
Load balancing6.2 Splaying host times
localhost and remote copying7.2.6 Deadlocks and runaway loops
Lock files for ordinary users7.2.4 Spamming and security
Log files4.10 Log files written by cfengine
Log files, rotating5.9 Disabling and the file repository
Logical NOT4.1 Classes

M
Macros4.2 Variable substitution
MaxConnections variable7.3.2 Configuration file `cfservd.conf'
moduledirectory4.4.5 Writing plugin modules
Modules, user defined plug-ins4.4 Defining classes and making exceptions
Monitoring important files2.3.5 Monitoring important files
Months6.3 Building flexible time classes
Mount points5.6.2 Unique filesystem mountpoints
Multiple package configuration4.13 Iterating over lists
Musts in cfengine3.1 What you must have in a cfengine program

N
Name collision4.2 Variable substitution
Name server2.3.4 Name servers (DNS)
Naming convention5.6.2 Unique filesystem mountpoints
Nested macros4.2 Variable substitution
netgroups5.2 Using netgroups
Network Address Translators7.3.2 Configuration file `cfservd.conf'
network configuration2.3.2 Network interface
network interface2.3.2 Network interface
NFS2.3.3 Network File System (NFS) or distribution?
NFS mounted filesystems5.6 Cfengine's model for NFS-mounted filesystems
NFS resources5.6.1 NFS filesystem resources
NIS5.2 Using netgroups
NOT operator4.1 Classes

O
Operator ordering4.1 Classes
Optional features in cfengine3.3 Optional features in cfengine
Order of actions3.2 Program structure
Ordinary users, lock files7.2.4 Spamming and security

P
Package configuration, multiple4.13 Iterating over lists
Path to input files3.5 CFINPUTS environment variable
Patterns4.8 Wildcards in directory names
Permissions, extended5.12 Managing ACLs
Piping input into cfengine3.5 CFINPUTS environment variable
Plug-in modules4.4 Defining classes and making exceptions
Policy for running the system5.1 General considerations
Program format3.2 Program structure
Program structure3.2 Program structure

Q
Quoting strings4.11 Quoted strings

R
Race conditions during copying8.1 Security hints
rdist program7.1 Cfengine network services
Remote distribution of files7.1 Cfengine network services
Remote execution of cfengine7.1 Cfengine network services
Remote execution of cfengine7.2.2 Remote execution of cfengine
Rereading `cfservd.conf'7.3.1 Installation of cfservd
Restarting cfservd7.3.1 Installation of cfservd
Restricting access4.7 Access control
Rotating files5.9 Disabling and the file repository
`run-cfengine' file.6. Using cfengine as a front end for cron
Running cfengine from a single master host7.2.3 cfrun
Running cfengine from a single master host7.2.3 cfrun
Running cfengine remotely7.2.2 Remote execution of cfengine
Running cfrun7.2.3 cfrun

S
Scripts, passing classes to4.2 Variable substitution
Sections, order of3.2 Program structure
Security and environment variables8.1 Security hints
server=7.2.1 Remote file distribution
server= when copying to localhost7.2.6 Deadlocks and runaway loops
setgid root log4.10 Log files written by cfengine
setuid log8.1 Security hints
setuid root log4.10 Log files written by cfengine
setuid root programs8.1 Security hints
Setuid scripts4.7 Access control
Shell commands which define classes4.4.3 shellcommand classes
Shell, starting programs8.1 Security hints
Special variables5.6.4 Special variables
Splaying host times6.2 Splaying host times
SplayTime in cfrun7.2.3 cfrun
split4.13 Iterating over lists
Spoofing8.1 Security hints
Starting cfengine3.4 Invoking cfengine
Starting commands without a shell8.1 Security hints
STDIN, reading from3.5 CFINPUTS environment variable
Strings4.11 Quoted strings
Structure of a program3.2 Program structure
Suspicious filenames8.1 Security hints
System administrator, name4.2 Variable substitution
System policy5.1 General considerations

T
TCP wrappers8.1 Security hints
tidy, file sweeps4.9 Recursive file sweeps/directory traversals
Tidying files5.3 Files and links
Time classes6.3 Building flexible time classes
Tripwire8.1 Security hints
Trust model8.3 Whom do you trust?

U
underscoreclasses4.2 Variable substitution
User programs which define classes4.4.3 shellcommand classes
useshell=8.1 Security hints

V
Variable substitution4.2 Variable substitution
Variables and Macros4.2 Variable substitution
Variables, cfengine4.2 Variable substitution
Variables, cfengine model5.6.4 Special variables
Variables, environment4.2 Variable substitution
Variables, setting to result of a shell command4.2 Variable substitution
Variables, using4.2 Variable substitution
Verifying with -n option3.4 Invoking cfengine

W
warnnonownermail8.1 Security hints
warnnonusermail8.1 Security hints
Wildcard, any class4.5 The generic class any
Wildcards4.8 Wildcards in directory names
Wildcards, in directory names4.8 Wildcards in directory names

Y
Years6.3 Building flexible time classes

Jump to:   !   -   .   /  
A   B   C   D   E   F   G   H   I   L   M   N   O   P   Q   R   S   T   U   V   W   Y  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

FAQ Index

Jump to:   B   C   D   H   I   M   P   S   T   W  

Index Entry Section

B
Brackets (parentheses) in classes.4.1 Classes

C
Can't stat error when remote copying7.3.2 Configuration file `cfservd.conf'
Checksums take too long to compute.7.3.2 Configuration file `cfservd.conf'
Configure multiple packages4.13 Iterating over lists

D
Define classes based on result of user program4.4.3 shellcommand classes
Denial of service attacks7.3.2 Configuration file `cfservd.conf'

H
Hanging connections attacks7.3.2 Configuration file `cfservd.conf'
How can I make complex time intervals using time classes?6.3 Building flexible time classes
How can I use cfengine to make a global cron file?6. Using cfengine as a front end for cron
How do I quote quotes?4.11 Quoted strings
How to keep all users in `/home'5.7 Using the automounter

I
Iterating over lists4.13 Iterating over lists

M
Mailbox policing8.1 Security hints
MD5 checksums take a long time to compute.7.3.2 Configuration file `cfservd.conf'

P
Parentheses in classes.4.1 Classes

S
split, using a space4.13 Iterating over lists

T
Time classes, picking out complex time intervals6.3 Building flexible time classes
Tripwire functionality8.2 Checksum Databases

W
Why do I get network access denied to files I have granted access to?7.3.2 Configuration file `cfservd.conf'
Why does cfservd give access to files on a different filesystem?7.3.2 Configuration file `cfservd.conf'

Jump to:   B   C   D   H   I   M   P   S   T   W  


[Top] [Contents] [Index] [ ? ]

Footnotes

(1)

On some systems, core dumps cannot be switched off!

(2)

This unique naming scheme was suggested to me originally by Knut Borge at USIT of the University of Oslo.

(3)

Note: if the filesystem was in the fstab but not actually mounted a warning is issued telling you that the filesystem was probably not exported correctly on host1.

(4)

One possibility is that an NFS filesystem cannot be mounted because the host serving the filesystem is out of service. If this is the case then a subsequent re-run when the server resumes normal service will succeed.

(5)

Recall the `spam' song from Monty Python's flying circus?

(6)

Recall the `spam' song from Monty Python's flying circus?

(7)

Recall the `spam' song ... get the idea?


[Top] [Contents] [Index] [ ? ]

Table of Contents

1. AUTOMATED SYSTEM ADMINISTRATION
2. Overview
2.1 What is cfengine and who can use it?
2.2 Site configuration
2.3 Key Concepts
2.3.1 Control files
2.3.2 Network interface
2.3.3 Network File System (NFS) or distribution?
2.3.4 Name servers (DNS)
2.3.5 Monitoring important files
2.3.6 Making links
2.4 Functionality
3. Getting started
3.1 What you must have in a cfengine program
3.2 Program structure
3.3 Optional features in cfengine
3.4 Invoking cfengine
3.5 CFINPUTS environment variable
3.6 What to aim for
4. More advanced concepts
4.1 Classes
4.2 Variable substitution
4.3 Undefined variables
4.4 Defining classes and making exceptions
4.4.1 Command line classes
4.4.2 actionsequence classes
4.4.3 shellcommand classes
4.4.4 Feedback classes
4.4.5 Writing plugin modules
4.5 The generic class any
4.6 Debugging tips
4.7 Access control
4.8 Wildcards in directory names
4.9 Recursive file sweeps/directory traversals
4.10 Log files written by cfengine
4.11 Quoted strings
4.12 Regular expressions
4.13 Iterating over lists
5. Designing a global system configuration
5.1 General considerations
5.2 Using netgroups
5.3 Files and links
5.4 Copying files
5.5 Managing processes
5.6 Cfengine's model for NFS-mounted filesystems
5.6.1 NFS filesystem resources
5.6.2 Unique filesystem mountpoints
5.6.3 How does it work?
5.6.4 Special variables
5.6.5 Example programs for mounting resources
5.7 Using the automounter
5.8 Editing Files
5.9 Disabling and the file repository
5.10 Running user scripts
5.11 Compressing old log files
5.12 Managing ACLs
6. Using cfengine as a front end for cron
6.1 Structuring `cfengine.conf'
6.2 Splaying host times
6.3 Building flexible time classes
6.4 Choosing a scheduling interval
7. Cfengine and network services
7.1 Cfengine network services
7.2 How it works
7.2.1 Remote file distribution
7.2.2 Remote execution of cfengine
7.2.3 cfrun
7.2.4 Spamming and security
7.2.5 Some points on the cfservd protocol
7.2.6 Deadlocks and runaway loops
7.3 Configuring cfservd
7.3.1 Installation of cfservd
7.3.2 Configuration file `cfservd.conf'
7.3.3 TCP wrappers
8. Security and cfengine
8.1 Security hints
8.2 Checksum Databases
8.3 Whom do you trust?
8.4 Firewalls
Variable Index
Concept Index
FAQ Index

[Top] [Contents] [Index] [ ? ]

Short Table of Contents

1. AUTOMATED SYSTEM ADMINISTRATION
2. Overview
3. Getting started
4. More advanced concepts
5. Designing a global system configuration
6. Using cfengine as a front end for cron
7. Cfengine and network services
8. Security and cfengine
Variable Index
Concept Index
FAQ Index

[Top] [Contents] [Index] [ ? ]

About this document

This document was generated using texi2html

The buttons in the navigation panels have the following meaning:

Button Name Go to From 1.2.3 go to
[ < ] Back previous section in reading order 1.2.2
[ > ] Forward next section in reading order 1.2.4
[ << ] FastBack previous or up-and-previous section 1.1
[ Up ] Up up section 1.2
[ >> ] FastForward next or up-and-next section 1.3
[Top] Top cover (top) of document  
[Contents] Contents table of contents  
[Index] Index concept index  
[ ? ] About this page  

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

This document was generated by Brett Smith on July, 18 2001 using texi2html