This manual is for version 2.2.10 of cfengine and was last updated on the 24 December 2008.
Next: Getting started, Previous: Top, Up: Top [Contents][Index]
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”.
| • What is cfengine?: | ||
| • Site configuration: | the problem | |
| • Key concepts: | the solution | |
| • Functionality: | an advertisement |
Next: Site configuration, Previous: Overview, Up: Overview [Contents][Index]
Cfengine is a tool for setting up and maintaining computer systems. It consists of several components:
An autonomous configuration agent (required).
A file server and remote activation service (optional).
A scheduling and report service (recommended).
An anomaly detection service (strongly recommended).
A way of activating cfagent remotely (use this as you need to).
A way of examining the contents of helper databases (helper).
Ancillary tool for cfenvd (helper).
Key generation tool (run once on every host).
The agent cfagent can be used without the other programs, but not all of the capabilities of cfengine will be available unless the components are installed and used appropriately.
Cfengine incorporates a declarative 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 doing other things instead of manual
configuration.
The main purpose of cfengine is to allow you to create a single system configuration which will allow you to define how every host on your network should be configured, and to do so in an intuitive way – either centralized or decentralized as you prefer. 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; 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.
Cfengine grew out of the need to control the accumulation of complex shell scripts used in the automation of key system maintenance at University College in Oslo. There were a lot of scripts, written in shell and in Perl, performing system administration tasks such as file tidying, find-database updates, process checking and several other tasks. In a mixed environment, shell scripts work very poorly: shell commands have differing syntax across different operating systems, and 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 and 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.
As an inexperienced cfengine user, you will probably find yourself trying to do things as you would have tried to do them in shell or Perl. This is probably not the right way to think when using cfengine. You will need to think in a more ‘cfengine way’. When reading the manual, keep in mind that cfengine’s way of working is to think about what the final result should be like, rather than on how to get there (with shell and Perl you specify what to do, rather than what you would like).
The remainder of this manual assumes that you know a little about BSD and UNIX System V systems and have every day experience in using either the C shell (csh) or the Bourne shell (sh), 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...
Next: Key concepts, Previous: What is cfengine?, Up: Overview [Contents][Index]
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 V 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 system 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.
Next: Functionality, Previous: Site configuration, Up: Overview [Contents][Index]
Some of the important issues in system administration which cfengine can help with.
| • Control files: | textfiles which configure | |
| • Network interface: | ethernet parameters | |
| • Network File System (NFS): | sharing resources | |
| • Name servers (DNS): | setting up a name service | |
| • Monitoring important files: | permission and ownership | |
| • Making links: | aliases |
Next: Network interface, Previous: Key concepts, Up: Key concepts [Contents][Index]
One of the endearing characteristics of BSD and System V 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 cfagent will automate for you.
On Windows systems, configuration data are stored in a system registry. With the right tools, the Windows system registry can also be edited by cfengine, but this requires more care.
Next: Network File System (NFS), Previous: Control files, Up: Key concepts [Contents][Index]
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 cfagent.
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).
Cfagent’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.
Next: Name servers (DNS), Previous: Network interface, Up: Key concepts [Contents][Index]
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) makes this possible.
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. Cfagent will help you with the last two in a very transparent way. You could also use the text-editing facility in cfagent to edit the exports file, but there are other ways to update the exports file using NIS and netgroups, which we shall not go into here. If you are in doubt, look up the manual page on exports(5).
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 cfagent to copy files in this
way, See Emulating rdist.
Next: Monitoring important files, Previous: Network File System (NFS), Up: Key concepts [Contents][Index]
There are two ways to specify addresses on the internet (called IP addresses). One is to use the text address like ‘ftp.uu.net’ and the other is to use the numerical form ‘192.48.96.9’. Alas, there is no direct one-to-one correspondence between the numerical addresses and the textual ones, thus a service (called DNS) is required to map one to the other.
The service is performed by one or more special hosts on the network called name servers. Each host must know how to contact a name server or it will probably hang the first time you give it an IP address. You tell it how to contact a name server by editing the text-file /etc/resolv.conf. This file must contain the domain name for your domain and a list of possible name servers which can be contacted, in order of priority. Since this is a special file which every host must have, you don’t have to use the general text file editing facilities in cfagent. You can just define the name servers for each host in the cfagent file and cfagent will do the editing to /etc/resolv.conf automatically. If you want to change the priority of name servers 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!
Next: Making links, Previous: Name servers (DNS), Up: Key concepts [Contents][Index]
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; 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 userid 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 but unwritable by normal users.
Simple accidents and careless actions under stress could result in, for example, the password file being writable to ordinary users. If this were the case, the security of the entire system would be compromised. Cfagent therefore allows you to monitor the permissions, ownership, and general existence of files and directories and, if you wish, to either correct them or warn about them automatically.
Previous: Monitoring important files, Up: Key concepts [Contents][Index]
One of the difficulties with having so many different variations on the theme of BSD and System V 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. Cfagent 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 cfagent 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.
Cfagent will also allow you to make hard links to regular files, but not to other kinds of files. A hard link that points to a symbolic link is the same as a hard link to the file the symbolic link points to.
Previous: Key concepts, Up: Overview [Contents][Index]
The notes above give you a rough idea of what cfengine can be used for. Here is a quick summary of cfagent’s capabilities.
How do you run cfagent? You can run it as a cron job, or you can run it
manually. You may run cfagent scripts/programs as often
as you like. Each time you run a script, cfengine 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 repeatedly with
the help of cron and/or cfexecd.
Next: More advanced concepts, Previous: Overview, Up: Top [Contents][Index]
| • What you must have: | a skeleton cfagent program | |
| • Program structure: | an overview | |
| • Building a distributed configuration : | ||
| • Options: | spices and conveniences | |
| • Invoking cfagent: | from the command line | |
| • Running cfengine permanently monitoring and restarting cfexecd: | ||
| • CFINPUTS environment variable: | the cfengine search path | |
| • What to aim for: |
Next: Program structure, Previous: Getting started, Up: Getting started [Contents][Index]
A cfagent 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 cfagent program or configuration file is a list of declarations of items to be checked and perhaps fixed. You begin by creating a file called cfagent.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:
name=( list ) are
used to assign the value on the right hand side to the name on the left hand side
of the equals sign.
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
action sequence. 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 cfagent what do to and in which order.
The links: section of the file tells cfagent 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 action sequence, 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 (Solaris) 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 cfagent, telling you that /bin exists and is not a link. The lesson is that, if we want to use cfagent 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
cfagent. 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 cfagent 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.
Next: Building a distributed configuration, Previous: What you must have, Up: Getting started [Contents][Index]
To summarize the previous section, here is a sketch of a typical cfagent 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, copy, homeservers, binservers, mailserver, mountables, import, broadcast, resolve, defaultroute, directories, miscmounts, files, ignore, tidy, required, links, disable, shellcommands, strategies 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 cfagent 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
...
Next: Options, Previous: Program structure, Up: Getting started [Contents][Index]
If a configuration is to be specified at one central location, how does it get distributed to many hosts? The simple answer is to get cfengine to distribute the configuration to the hosts. To do that, a separate configuration file is used. Why?
Imagine what would happen if you made a mistake in the configuration, i.e. a syntax error which got distributed to every host. Now all the hosts would be unable to run cfengine, and thereafter unable to download a corrected configuration file. The whole setup would be broken. To prevent this kind of accident, a separate configuration file is used to copy the files and binaries to each host. This configuration should be simple, and should almost never be edited: they key word here is reliability.
| • Startup update.conf: | ||
| • Startup cfservd.conf: | ||
| • Where should I put the files?: |
Next: Startup cfservd.conf, Previous: Building a distributed configuration, Up: Building a distributed configuration [Contents][Index]
The file update.conf can have more or less the same form for all sites, looking something like this.
#######
#
# BEGIN update.conf
#
# This script distributes the configuration, a simple file so that,
# if there are syntax errors in the main config, we can still
# distribute a correct configuration to the machines afterwards, even
# though the main config won't parse. It is read and run just before the
# main configuration is parsed.
#
#######
control:
actionsequence = ( copy tidy ) # Keep this simple and constant
domain = ( iu.hio.no ) # Needed for remote copy
#
# Which host/dir is the master for configuration roll-outs?
#
policyhost = ( nexus.iu.hio.no )
master_cfinput = ( /masterfiles/inputs )
#
# Some convenient variables
#
workdir = ( /var/cfengine )
cf_install_dir = ( /usr/local/sbin )
# Avoid server contention
SplayTime = ( 5 )
############################################################################
#
# Make sure there is a local copy of the configuration and
# the most important binaries in case we have no connectivity
# e.g. for mobile stations or during DOS attacks
#
copy:
$(master_cfinput) dest=$(workdir)/inputs
r=inf
mode=700
type=binary
exclude=*.lst
exclude=*~
exclude=#*
server=$(policyhost)
$(cf_install_dir)/cfagent dest=$(workdir)/bin/cfagent
mode=755
backup=false
type=checksum
$(cf_install_dir)/cfservd dest=$(workdir)/bin/cfservd
mode=755
backup=false
type=checksum
$(cf_install_dir)/cfexecd dest=$(workdir)/bin/cfexecd
mode=755
backup=false
type=checksum
#####################################################################
tidy:
#
# Cfexecd stores output in this directory.
# Make sure we don't build up files and choke on our own words!
#
$(workdir)/outputs pattern=* age=7
#######
#
# END cf.update
#
#######
Next: Where should I put the files?, Previous: Startup update.conf, Up: Building a distributed configuration [Contents][Index]
In order to set up remote distribution from a central server, you will need to start the cfservd service on the host from which the configuration is to be copied, and grant access to the hosts which need to download it. Here is a simple get-started file which does this:
#########################################################
#
# This is a cfservd config file - it is used for the server
# part of cfengine, for remote file transfers and control
# over cfengine using the cfrun program.
#
#########################################################
control:
domain = ( iu.hio.no )
cfrunCommand = ( "/var/cfengine/bin/cfagent" )
any::
IfElapsed = ( 1 )
ExpireAfter = ( 15 )
MaxConnections = ( 50 )
MultipleConnections = ( true )
#########################################################
grant:
# Grant access to all hosts at example.org.
# Files should be world readable
/masterfiles/inputs *.example.org
# Make sure there is permission to execute by cfrun
/var/cfengine/bin/cfagent *.example.org
########
#
# END cfservd.conf
#
########
Previous: Startup cfservd.conf, Up: Building a distributed configuration [Contents][Index]
Where should the files be located? To organize your files, you should think of three potential locations, for different purposes:
Modules and methods are normally kept in a separate directory than inputs files are kept in, because they require a directory with special authorizations whe executing. This is good practice As long as the update.conf places the master versions in the correct location (usually /var/cfengine/modules) on the local host, all will be okay.
You should not try to copy files directly from a version controlled repository, as you might end up sending out an incomplete or partially tested version of the files to all your hosts.
# Example update.conf
control:
master_cfinput = ( /usr/local/masterfiles/cfengine/inputs )
workdir = ( /var/cfengine )
copy:
# Copy from bullet 2 to bullet 3
$(master_cfinput) dest=$(workdir)/inputs
r=inf
mode=700
type=binary
exclude=*.lst
exclude=*~
exclude=#*
server=$(policyhost)
trustkey=true
$(master_modules) dest=$(workdir)/modules
r=inf
mode=700
type=binary
exclude=*.lst
exclude=*~
exclude=#*
server=$(policyhost)
trustkey=true
Next: Invoking cfagent, Previous: Building a distributed configuration, Up: Getting started [Contents][Index]
Cfagent doesn’t do anything unless you ask it to. When you run a cfagent 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 cfagent positively chatty. Cfagent 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 cfagent 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 cfagent 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 = ( example.org )
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 cfagent 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 cfagent 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 cfagent 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.
Next: Running cfengine permanently monitoring and restarting cfexecd, Previous: Options, Up: Getting started [Contents][Index]
Cfagent may be invoked in a number of ways. Here are some examples:
host% cfagent host% cfagent --file myfile host% cfagent -f myfile -v -n host% cfagent --help
The first of these (the default command, with no arguments) causes
cfagent to look for a file called cfagent.conf in the directory
pointed to by the environment variables CFINPUTS
or /var/cfengine/inputs by default,
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 cfagent
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 cfagent with a filename, you can also treat cfagent files as scripts by starting your cfagent program with the standard shell line:
#!/usr/local/sbin/cfagent -f # # My config script #
Here we assume that you have installed cfengine under the directory
/usr/local/sbin. 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.
Next: CFINPUTS environment variable, Previous: Invoking cfagent, Up: Getting started [Contents][Index]
Once you are happy using cfengine, you will want it to run least once per hour on your systems. This is easily achieved by adding the following line to the root crontab file of each system:
0,30 * * * * /usr/local/sbin/cfexecd -F
This is enough to ensure that cfengine will get run. Any output generated by this job, will be stored in /var/cfengine/outputs. In addition, if you add the following to the file cfagent.conf, the system administrator will be emailed a summary of any output:
control: smtpserver = ( mailhub.example.org ) # site MTA which can talk smtp sysadm = ( mark@example.org ) # mail address of sysadm
Fill in suitable values for these variables.
An alternative, or additional way to run cfengine, is to run the cfexecd
program is daemon mode (without the ‘-F’) option. In this mode, the daemon
lives in the background and sleeps, activating only in accordance with
a scheduling policy. The default policy is to run once every hour (equivalent
to Min00_05). Here is how you would modify cfagent.conf in
order to make the daemon execute cfagent every half-hour:
control: # When should cfexecd in daemon mode wake up the agent? schedule = ( Min00_05 Min30_35 )
Note that the time specifications are the basic cfengine time classes, See Building flexible time classes. Although one of these methods should suffice, no harm will arise from running both cron and the cfexecd side-by-side. Cfagents locking mechanisms ensure that no contention will occur.
The other components of cfengine can be started by cfagent itself:
processes: "cfenvd" restart "/usr/local/sbin/cfenvd" "cfservd" restart "/usr/local/sbin/cfservd"
Note that, to start cfexecd by cfengine, one must do this
processes: "bin/cfexecd$" restart "/usr/local/sbin/cfexecd"
It’s important to use as specific a regular expression as possible in match
statements (the path to the program and the regular expression metacharacter
$ meaning "end of line", in this example) because bare strings can
often match unexpected processes. For instance, using cfexecd by
itself will also match a process spawned by cfagent -F, which shows
up as /var/cfagent/bin/cfagent -Dfrom_cfexecd in the process table!
Next: What to aim for, Previous: Running cfengine permanently monitoring and restarting cfexecd, Up: Getting started [Contents][Index]
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
cfagent.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/masterfiles/cfengine/inputs host# cfagent -f myfile
In this example, cfengine tries to open
myfile.
in the directory
/usr/local/masterfiles/cfengine/inputs.
If no value is set for CFINPUTS, then the default location
is the trusted cfengine directory
/var/cfengine/inputs.
Previous: CFINPUTS environment variable, Up: Getting started [Contents][Index]
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.
Running cfengine from cron means that it will be run in parallel on your systems. Cfengine on one host does not have to wait for cfengine on another host to complete.
cfservd on all your systems so that cfengine can be executed
remotely, so that you can immediately “push" changes to all your
hosts with cfrun. Think carefully about whom you wish to give permission to run
cfengine from the net, See Configuring cfservd. Set up you
cfservd.conf file accordingly. You can also use this daemon to
grant access rights for remote file copying.
Cfrun polls all your hosts serially and gives you a concatenated indexed list of problems on all hosts. The disadvantage with cfrun is that each host has to wait its turn.
cfservd to the system startup scripts, or to inittab
so that it starts when you boot your system.
When you have set up these components, you can sit back and edit the configuration files and watch things being done.
Next: Global configurations, Previous: Getting started, Up: Top [Contents][Index]
| • Classes basics: | ||
| • Variable substitution: | ||
| • Undefined variables: | ||
| • Defining classes: | making decisions | |
| • The generic class any: | a wildcard | |
| • Debugging tips: | nullifying classes | |
| • Access control: | specifying user access to programs | |
| • Wildcards in directory names: | multiple searches | |
| • File sweeps: | ||
| • Security in File sweeps: | ||
| • Log files: | ||
| • Quoted strings: | ||
| • Regular expressions: | ||
| • Iterating over lists: |
Next: Variable substitution, Previous: More advanced concepts, Up: More advanced concepts [Contents][Index]
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:
ultrix, sun4 etc.
This is referred to henceforth as a hard class.
Monday, Tuesday, Wednesday...).
Hr00, Hr01, ... Hr23).
Min00, Min17, ... Min45).
Min00_05, Min05_10"top">• u" rel="up">Cfagent reference&nbd $(synd means: ignore the) bug lisleft
G -is un
the code>
The default vaings working quickly.
- Run cfengine from cron eveable-Index" title="If thisoup with compound identifier Dots [.] not allowed in group identifier
froame="index-Environme
ning texug a file: rform a co
control:
domain = ( example.org )
netmask = ( 255.255.255.0 )
tplace ClassMMET CET )
mountpattern = ( /mydomain/mountpoint )
actionsequence =
%squo; class to loaountpath ref‰E-rR^q˜]›ÏÂ×G±d was to bgnals
Itto mountf ¶u—
%squo; class to loaountpath ref‰E-rR^q˜]›ÏÂ×G±d ntents" rel="contents">Contents][ &nb ntents" riable-Index" title="Index" class="smallexample">
action-type:
class1::
list of things to do...
cla>action-type
A filter is a way of selecting or pruning during a search over
files or processes. Since filter rules could apply to several objectitle="Table of contents" reath ref‰E-rR^q˜]› î}Âontents" reath ref‰E-rR^q˜]› î}Âontents" reath ref‰E-rR^q˜]› î}Âontents" reath ref‰E-rR^q˜]› î}Âontents" reath ref‰E-rR^q˜]›
Def«w§ÝÈN›îôØ_s's in commag))" reath ref‰E-rR^ nts" reeth ref‰E-rROq˜]¨ath ref‰E-rR^q˜]ntity -1">< owner=0its" title="Table of contents" rel="contents">Contents
][< owner=0its" title="Table of contentsR^q˜]ntity R^qô]ntity R^qô]nt
The file's destinapressCommandContents][Contable of conteots" rel="c, or wiontents][,start-stop)
True if the current relative domain name begins with baseC)Ù™}Õjvcne-pointer-in-edi" rel="pmeKeys">5.e>BeginGroa thenticacne-pov>
such as
#!/bin/sh
PACKAGESITE=http://my.local.reposkss="smallexaoulCommand = ( "/var/c
vs">4.25 instive inuus">
Whd
, cmp=Filly IfEer">
Nexo5 instive inuus
ther. Thestiv5 instive inur/c
ries" "/var/c
inur/c
r>
,sted version of tce c , ">
Whd
, cmp=Filce cesystems containing
hostive ins="left" valign="top">• Log files:
align="left" files-while-s smart to fol p">•
alp">
A>
Cfen
Eoce’.
, sun4, etc. &nbs