<HTML>
<HEAD>
<!-- Created by texi2html 1.56k from cfengine-Tutorial.texinfo on 16 October 2000 -->
<TITLE>GNU cfengine</TITLE>
</HEAD>
<BODY>
<H1>cfengine tutorial</H1>
<H2>Edition 5.1 for version 1.5.4</H2>
<ADDRESS>Mark Burgess</ADDRESS>
<ADDRESS>Faculty of Engineering, Oslo College, Norway</ADDRESS>
<P>
<P><HR><P>
<H1><A NAME="SEC1" HREF="cfengine-Tutorial_toc.html#TOC1">AUTOMATED SYSTEM ADMINISTRATION</A></H1>
<P>
<EM>Kirk</EM>:
"I'm curious, Doctor, why is it called the M5?"
<P>
<EM>Daystrom</EM>:
"Well you see, M1 to M4 were not entirely successful. This one is.
M5 is ready to take control of your ship."
<P>
<EM>Kirk</EM>:
"Total control?"
<P>
<EM>Daystrom</EM>:
"That is what it is designed for."
<P>
<EM>Kirk</EM>:
"There are some things that Men have to do to remain Men, your computer
takes that away."
<P>
<EM>Daystrom</EM>:
"The computer can do your job ... One machine can do all those things
that Men do now. Men can go on to do greater things..."
<P>
<EM>--ST: The ultimate computer</EM>
<H1><A NAME="SEC2" HREF="cfengine-Tutorial_toc.html#TOC2">Overview</A></H1>
<P>
<EM>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".</EM>
<H2><A NAME="SEC3" HREF="cfengine-Tutorial_toc.html#TOC3">What is cfengine and who can use it?</A></H2>
<P>
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 <CODE>cron</CODE>. 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.
<P>
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.
<P>
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.
<P>
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.
<P>
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 <EM>Example
configuration file</EM> 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...
<H2><A NAME="SEC4" HREF="cfengine-Tutorial_toc.html#TOC4">Site configuration</A></H2>
<P>
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
<SAMP>`if..then..else..'</SAMP> tests which make it hard to see what is really
going on.
<P>
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.
<P>
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.
<H2><A NAME="SEC5" HREF="cfengine-Tutorial_toc.html#TOC5">Key Concepts</A></H2>
<P>
<EM>Some of the important issues in system
administration which cfengine can help with.</EM>
<H3><A NAME="SEC6" HREF="cfengine-Tutorial_toc.html#TOC6">Control files</A></H3>
<P>
<A NAME="IDX1"></A>
<A NAME="IDX2"></A>
<A NAME="IDX3"></A>
<P>
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 <TT>`/etc/passwd'</TT>, to add a new
disk you must edit <TT>`/etc/fstab'</TT> 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.
<H3><A NAME="SEC7" HREF="cfengine-Tutorial_toc.html#TOC7">Network interface</A></H3>
<P>
<A NAME="IDX4"></A>
<A NAME="IDX5"></A>
<A NAME="IDX6"></A>
<P>
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 <CODE>ifconfig</CODE> command. This can also be checked and
configured automatically by cfengine.
<P>
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).
<H3><A NAME="SEC8" HREF="cfengine-Tutorial_toc.html#TOC8">Network File System (NFS) or distribution?</A></H3>
<P>
<A NAME="IDX7"></A>
<P>
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'.
<P>
A filesystem is one partition of a disk drive -- or one unit of disk
space which can be accessed by a single `logical device'
<SAMP>`/dev/something'</SAMP>. To make a filesystem available to other hosts
you have to do three things.
<UL>
<LI>On the host the disk is physically connected to you must <EM>export</EM> the filesystem
by adding something to the file <TT>`/etc/exports'</TT>. This tells NFS who
is allowed to access the disk and who isn't.
<LI>On the host which is to access the filesystem you must create a mount point. This
is a name in the directory tree at which you want to add the files to
your local filesystem.
<LI>On the host which is to access the files you must mount the filesystem onto the
mount point. The mount operation is the jargon for telling the system
to access the device on which the data are stored. Mounting is
analogous to opening a file: files are opened, filesystems are mounted.
</UL>
<P>
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 <EM>netgroups</EM> which we shall not go into here.
If you are in doubt, look up the manual page on exports.
<P>
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 <CODE>rdist</CODE> have been used for
this purpose. You may also use cfengine to copy files in this
way, See section <A HREF="cfengine-Tutorial.html#SEC64">Remote file distribution</A>.
<H3><A NAME="SEC9" HREF="cfengine-Tutorial_toc.html#TOC9">Name servers (DNS)</A></H3>
<P>
<A NAME="IDX8"></A>
<A NAME="IDX9"></A>
<P>
There are two ways to specify addresses on the internet (called IP
addresses). One is to use the textual address like <SAMP>`ftp.uu.net'</SAMP>
and the other is to use the numerical form <SAMP>`192.48.96.9'</SAMP>. 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.
<P>
The service is performed by one or more special hosts on the network
called <EM>nameservers</EM>. 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 <TT>`/etc/resolv.conf'</TT>. 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!
<H3><A NAME="SEC10" HREF="cfengine-Tutorial_toc.html#TOC10">Monitoring important files</A></H3>
<P>
<A NAME="IDX10"></A>
<A NAME="IDX11"></A>
<P>
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.
<P>
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 <EM>your</EM> 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.
<P>
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.
<H3><A NAME="SEC11" HREF="cfengine-Tutorial_toc.html#TOC11">Making links</A></H3>
<P>
<A NAME="IDX12"></A>
<P>
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 <EM>symbolic link</EM>.
<P>
It is often very convenient to make symbolic links. For example, you
might want the sendmail configuration file <TT>`/etc/sendmail.cf'</TT> to be
a link to a global configuration file, say,
<PRE>
<TT>`/usr/local/mail/etc/sendmail.cf'</TT>
</PRE>
<P>
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 time 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.
<P>
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.
<A NAME="IDX13"></A>
<H2><A NAME="SEC12" HREF="cfengine-Tutorial_toc.html#TOC12">Functionality</A></H2>
<P>
The notes above give you a rough idea of what cfengine can be used for.
Here is a summary of cfengine's capabilities.
<UL>
<LI>Check and configure the network interface.
<LI>Edit textfiles for the system and for all users.
<LI>Make and maintain symbolic links, including multiple links from
a single command.
<LI>Check and set the permissions and ownership of files.
<LI>Tidy (delete) junk files which clutter the system.
<LI>Systematic, automated mounting of NFS filesystems.
<LI>Checking for the presence of important files and filesystems.
<LI>Controlled execution of user scripts and shell commands.
<LI>Cfengine follows a class-based decision structure.
<LI>Process management.
</UL>
<P>
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 <CODE>cron</CODE>. (see the reference manual).
<H1><A NAME="SEC13" HREF="cfengine-Tutorial_toc.html#TOC13">Getting started</A></H1>
<H2><A NAME="SEC14" HREF="cfengine-Tutorial_toc.html#TOC14">What you must have in a cfengine program</A></H2>
<P>
<A NAME="IDX14"></A>
<P>
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.
<P>
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 <TT>`cfengine.conf'</TT>. The simplest meaningful file you can
create is something like this:
<PRE>
# Comment...
control:
actionsequence = ( links )
links:
/bin -> /usr/bin
</PRE>
<P>
The
example above checks and makes (if necessary) a link from <TT>`/bin'</TT> to <TT>`/usr/bin'</TT>.
Let's examine this example more closely. In a cfengine program:
<UL>
<LI>
Use of space is unrestricted. You can start new lines wherever you like.
You should generally have a space before and after parentheses to avoid
confusing the parser.
<LI>
A comment is some text which is ignored by cfengine. The <SAMP>`#'</SAMP> symbol
designates a comment and means: ignore the remaining text on this line.
A comment symbol must have a space in front of it, or start a new line
so that cfengine knows you don't mean the symbol as part of another
word.
<LI>
Words which end in a single colon define <EM>sections</EM> in a program. Under a
given section you group together all declarations of a given type. Section names
must all be taken from a list defined by the language. You cannot define your
own sections.
<LI>
Words which end in two colons are so-called <EM>class</EM> names. They are
used for making decisions in cfengine.
<LI>
Statements which are of the form <CODE><VAR>name</VAR>=( <VAR>list</VAR> )</CODE> are
used to assign the value on the right hand side to the name on the left hand side
of the equals sign.
</UL>
<P>
In simple example above has three of the four types of object described
above. The <CODE>control:</CODE> section of any program tells cfengine how to
behave. In this example it adds the action <VAR>links</VAR> to the
actionsequence. For <VAR>links</VAR> 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.
<P>
The <CODE>links:</CODE> 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
<VAR>links</VAR> in the action sequence.
<P>
To summarize, you <EM>must</EM> have:
<UL>
<LI>Some declarations which specify things to be done.
<LI>An action sequence which tells cfengine which sections to process,
how many times and in which order they should be processed.
</UL>
<P>
Now let's think a bit about how useful this short example program is.
On a SunOS system, where the directory <TT>`/bin'</TT> is in fact supposed
to be a link, such a check could be useful, but on some other system
where <TT>`/bin'</TT> is a not a link but a separate directory, this would
result in an error message from cfengine, telling you that <TT>`/bin'</TT>
exists and is not a link. The lesson is that, if we want to use
cfengine to make <EM>one single</EM> 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:
<PRE>
# Comment...
control:
actionsequence = ( links )
links:
sun4::
/bin -> /usr/bin
# other links
osf::
# other links
</PRE>
<P>
The names which have double colons after them are called <EM>classes</EM>
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
<CODE>sun4</CODE>, <CODE>sun3</CODE>, <CODE>osf</CODE> 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 <CODE>osf</CODE>. Since
it cannot be a member more than one of the above, this distinguishes
between different types of operating system and creates a hidden
<CODE>if</CODE>..<CODE>then</CODE>...<CODE>else</CODE> test.
<P>
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.
<P>
Now let's see how to add another kind of action to the action sequence.
<PRE>
# Comment...
control:
actionsequence = ( tidy links )
links:
/bin -> /usr/bin
tidy:
/tmp pattern=* age=7 recurse=inf
</PRE>
<P>
We have now added a new kind of declaration called <CODE>tidy:</CODE> which
deletes files. In the example above, we are looking at files in the
directory <TT>`/tmp'</TT> which match the pattern <SAMP>`*'</SAMP> and have not been
accessed for more than seven days. The search for these files descends
recursively down any number of subdirectories.
<P>
To make any of this happen we must add the word <VAR>tidy</VAR> to the action
sequence. If we don't, the declaration will be ignored. Notice also
that, regardless of the fact that <CODE>links:</CODE> comes before
<CODE>tidy:</CODE>, the order in the action sequence tells us that all
<CODE>tidy</CODE> actions will be performed before <CODE>links:</CODE>.
<P>
The above structure can be repeated to build up a configuration file or script.
<H2><A NAME="SEC15" HREF="cfengine-Tutorial_toc.html#TOC15">Program structure</A></H2>
<P>
<A NAME="IDX15"></A>
<A NAME="IDX16"></A>
<P>
<A NAME="IDX17"></A>
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.
<P>
An individual section-declaration in the program looks something like this:
<PRE>
<VAR>action-type</VAR>:
<VAR>class1</VAR>::
<VAR>list of things to do...</VAR>
<VAR>class2</VAR>::
<VAR>list of things to do...</VAR>
</PRE>
<P>
<CODE>action-type</CODE> is one of the following reserved words:
<PRE>
groups, control, homeservers, binservers, mailserver, mountables,
import, broadcast, resolve, defaultroute, directories, miscmounts,
files, ignore, tidy, required, links, disable, shellcommands,
editfiles, processes
</PRE>
<P>
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.
<P>
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
<CODE>actionsequence</CODE>, (see the reference manual). Probably you will want to
coordinate the two so that they match as far as possible.
<A NAME="IDX18"></A>
<A NAME="IDX19"></A>
<A NAME="IDX20"></A>
<P>
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.
<A NAME="IDX21"></A>
<A NAME="IDX22"></A>
<A NAME="IDX23"></A>
<PRE>
######################################################################
#
# Example of structure
#
######################################################################
groups:
<VAR>group1</VAR> = ( <VAR>host</VAR> <VAR>host</VAR> ... )
<VAR>group2</VAR> = ( <VAR>host</VAR> <VAR>host</VAR> ... )
...
######################################################################
control:
<VAR>class</VAR>::
site = ( <VAR>mysite</VAR> )
domain = ( <VAR>mydomain</VAR> )
...
actionsequence =
(
<VAR>action name</VAR>
....
)
mountpattern = ( <VAR>mountpoint</VAR> )
homepattern = ( <VAR>wildcards matching home directories</VAR> )
addinstallable = ( <VAR>foo</VAR> <VAR>bar</VAR> )
addclasses = ( <VAR>foo</VAR> <VAR>bar</VAR> )
######################################################################
homeservers:
<VAR>class</VAR>::
<VAR>home servers</VAR>
binservers:
<VAR>class</VAR>::
<VAR>binary servers</VAR>
mailserver:
<VAR>class</VAR>::
<VAR>mail server</VAR>
mountables:
<VAR>class</VAR>::
<VAR>list of resources</VAR>
######################################################################
import:
<VAR>class</VAR>:: <VAR>include file</VAR>
<VAR>class</VAR>:: <VAR>include file</VAR>
######################################################################
broadcast:
<VAR>class</VAR>:: <VAR>ones</VAR> # or zeros / zeroes
defaultroute:
<VAR>class</VAR>:: <VAR>my-gw</VAR>
######################################################################
resolve:
any::
<VAR>list of nameservers</VAR>
...
</PRE>
<P>
<H2><A NAME="SEC16" HREF="cfengine-Tutorial_toc.html#TOC16">Optional features in cfengine</A></H2>
<P>
<A NAME="IDX24"></A>
<P>
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. In fact it's just like one of those
people you try to avoid at the office because they only complain about
what's wrong and never ever say anything positive. But all this can
change.
<P>
If you like, 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 <SAMP>`-v'</SAMP> or <SAMP>`--verbose'</SAMP> options, it
will supply you cheerily with a resume of what it is doing. Certain
warning messages also get printed in verbose mode.
<P>
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 <CODE>control:</CODE> section of the control file.
Some special control variables are used for this purpose. Here is a
short example:
<PRE>
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
)
</PRE>
<P>
To get verbose output you must run cfengine with the appropriate command
line option <SAMP>`--verbose'</SAMP> or <SAMP>`-v'</SAMP>.
<P>
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.
<P>
Before leaving this brief advertisement for control parameters, it is
worth noting the definition of <CODE>mountpattern</CODE> 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...
<P>
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.
<H2><A NAME="SEC17" HREF="cfengine-Tutorial_toc.html#TOC17">Invoking cfengine</A></H2>
<P>
<A NAME="IDX25"></A>
<A NAME="IDX26"></A>
<A NAME="IDX27"></A>
<P>
Cfengine may be invoked in a number of ways. Here are some examples:
<PRE>
host% cfengine
host% cfengine --file myfile
host% cfengine -f myfile -v -n
host% cfengine --help
</PRE>
<P>
<A NAME="IDX28"></A>
<A NAME="IDX29"></A>
<A NAME="IDX30"></A>
The first of these (the default command, with no arguments) causes
cfengine to look for a file called <TT>`cfengine.conf'</TT> in the current
directory and execute it silently. The second command reads the file
<TT>`myfile'</TT> and works silently. The third works in verbose mode and
the <CODE>-n</CODE> 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.
<A NAME="IDX31"></A>
<A NAME="IDX32"></A>
<A NAME="IDX33"></A>
<P>
The complete list of options is listed in the summary at the beginning
of this manual, or you can see it by giving the <CODE>-h</CODE> option,
(see the reference manual).
<A NAME="IDX34"></A>
<A NAME="IDX35"></A>
<A NAME="IDX36"></A>
<P>
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:
<PRE>
#!/local/gnu/bin/cfengine -f
#
# My config script
#
</PRE>
<P>
<A NAME="IDX37"></A>
Here we assume that you have installed cfengine under the directory
<TT>`/local/gnu/bin'</TT>. By adding a header like this to the first line
of your program and making the file executable with the <CODE>chmod</CODE>
shell command, you can execute the program just by typing its
name--i.e. without mentioning cfengine explicitly at all.
<P>
As a novice to cfengine, it is advisable to check all programs with the
<CODE>-n</CODE> 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.
<H2><A NAME="SEC18" HREF="cfengine-Tutorial_toc.html#TOC18">CFINPUTS environment variable</A></H2>
<P>
Whenever cfengine looks for a file it asks a question: is the filename
an absolute name (that is a name which begins from <TT>`/'</TT> like
<CODE>/usr/file</CODE>), 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?
<A NAME="IDX38"></A>
<A NAME="IDX39"></A>
<A NAME="IDX40"></A>
<A NAME="IDX41"></A>
<A NAME="IDX42"></A>
<P>
If you use an absolute filename either on the command line using
<CODE>-f</CODE> or in the <CODE>import</CODE> 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 <SAMP>`.'</SAMP> or <SAMP>`-'</SAMP> then cfengine reads its input from the
standard input.
<A NAME="IDX43"></A>
<A NAME="IDX44"></A>
<P>
<A NAME="IDX45"></A>
If you run cfengine without arguments (so that the default filename is
<TT>`cfengine.conf'</TT>) or you specify a file without a leading slash in
the <CODE>import</CODE> section, then the value of the environment variable
<CODE>CFINPUTS</CODE> is prepended to the start of the file name. This allows
you to keep your configuration in a standard place, pointed to by
<CODE>CFINPUTS</CODE>. For example:
<PRE>
host# setenv CFINPUTS /usr/local/gnu/lib/cfengine/inputs
host# cfengine -f myfile
</PRE>
<P>
In this example, cfengine tries to open
<P>
<TT>`/usr/local/gnu/lib/cfengine/inputs/myfile'</TT>.
<H2><A NAME="SEC19" HREF="cfengine-Tutorial_toc.html#TOC19">What to aim for</A></H2>
<P>
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.
<UL>
<LI>
Run cfengine from cron every hour on all your systems. Be sure to
label long tasks, or tasks which do not need to be performed often
by a <EM>time class</EM> which prevents it from being executed
all the time, See section <A HREF="cfengine-Tutorial.html#SEC56">Using cfengine as a front end for <CODE>cron</CODE></A>.
<EM>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.</EM>
<LI>
Set up <CODE>cfd</CODE> on all your systems so that cfengine can be executed
remotely, so that you can immediately "push" changes to all your
hosts with <CODE>cfrun</CODE>. Think carefully about whom you wish to give permission to run
cfengine from the net, See section <A HREF="cfengine-Tutorial.html#SEC70">Configuring <CODE>cfd</CODE></A>. Set up you
<TT>`cfd.conf'</TT> file accordingly. You can also use this daemon to
grant access rights for remote file copying.
<EM>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.</EM>
<LI>
Don't forget to add <CODE>cfd</CODE> to the system startup scripts, or to <TT>`inittab'</TT>
so that it starts when you boot your system.
<LI>
Add <EM>all</EM> your hosts to the <TT>`cfrun.hosts'</TT> file. It does not
matter that some may be master servers and others clients. The locking
mechanisms will protect you from silliness, See section <A HREF="cfengine-Tutorial.html#SEC69">Deadlocks and runaway loops</A>. Cfengine will work it out. Cfrun allows you to remotely execute
cfengine on groups of hosts which satisfy a list of cfengine classes.
</UL>
<P>
When you have set up these components, you can sit back and edit the
configuration files and watch things being done.
<H1><A NAME="SEC20" HREF="cfengine-Tutorial_toc.html#TOC20">More advanced concepts</A></H1>
<H2><A NAME="SEC21" HREF="cfengine-Tutorial_toc.html#TOC21">Classes</A></H2>
<P>
<A NAME="IDX46"></A>
<P>
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 <CODE>if</CODE>...<CODE>then</CODE>...<CODE>else</CODE> 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 <EM>class</EM> 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.
<P>
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.
<P>
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
<EM>actions</EM> 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.
<P>
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.
<P>
A <EM>cfengine action</EM> looks like this:
<PRE>
<VAR>action-type</VAR>:
<VAR>compound-class</VAR>::
<VAR>declaration</VAR>
</PRE>
<P>
A single class can be one of several things:
<UL>
<LI>The name of an operating system architecture e.g. <CODE>ultrix</CODE>, <CODE>sun4</CODE> etc.
This is referred to henceforth as a <EM>hard class</EM>.
<LI>The (unqualified) name of a particular host. If your system returns a fully
qualified domain name for your host, cfengine truncates it so as to unqualify
the name.
<LI>The name of a user-defined group of hosts.
<LI>A day of the week (in the form <CODE>Monday Tuesday Wednesday..</CODE>).
<LI>An hour of the day (in the form Hr00, Hr01 ... Hr23).
<LI>Minutes in the hour (in the form Min00, Min17 ... Min45).
<LI>A five minute interval in the hour (in the form Min00_05, Min05_10 ... Min55_00)
<LI>A day of the month (in the form Day1 ... Day31).
<LI>A month (in the form January, February, ... December).
<LI>A year (in the form Yr1997, Yr2001).
<LI>An arbitrary user-defined string. (see the reference manual).
</UL>
<P>
A compound class is a sequence of simple classes connected by dots or
`pipe' symbols (vertical bars). For example:
<P>
<A NAME="IDX47"></A>
<A NAME="IDX48"></A>
<PRE>
myclass.sun4.Monday::
sun4|ultrix|osf::
</PRE>
<P>
A compound class evaluates to `true' if all of the individual classes
are separately true, thus in the above example the actions which follow
<CODE>compound_class::</CODE> are only carried out if the host concerned is in
<CODE>myclass</CODE>, is of type <CODE>sun4</CODE> and the day is Monday!
In the second example, the host parsing the file must be either of
type <CODE>sun4</CODE> <EM>or</EM> <CODE>ultrix</CODE> <EM>or</EM> <CODE>osf</CODE>.
In other words, compound classes support two operators: AND and OR,
written <SAMP>`.'</SAMP> and <SAMP>`|'</SAMP> respectively. Cfengine doesn't
care how many of these operators you use (since it skips over blank
class names), so you could write either
<PRE>
solaris|irix::
</PRE>
<P>
or
<PRE>
solaris||irix::
</PRE>
<P>
depending on your taste. On the other hand, the order in which cfengine
evaluates AND and OR operations <EM>does</EM> matter, and the rule
is that AND takes priority over OR, so that <SAMP>`.'</SAMP> 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.
<P>
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 <CODE>-D</CODE> and <CODE>-N</CODE> can be used for this
purpose. See also <CODE>addclasses</CODE> in the Reference manual.
<A NAME="IDX49"></A>
<A NAME="IDX50"></A>
<A NAME="IDX51"></A>
<P>
<A NAME="IDX52"></A>
<A NAME="IDX53"></A>
<A NAME="IDX54"></A>
<A NAME="IDX55"></A>
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++) <SAMP>`!'</SAMP>. For instance, the
following example would allow all hosts except for <CODE>myhost</CODE>:
<PRE>
<VAR>action</VAR>:
!myhost::
<VAR>command</VAR>
</PRE>
<P>
and similarly, so allow all hosts in a user-defined group <CODE>mygroup</CODE>,
<EM>except</EM> for <CODE>specialhost</CODE>, you would write
<PRE>
<VAR>action</VAR>:
mygroup.!myhost::
<VAR>command</VAR>
</PRE>
<P>
which reads `mygroup AND NOT myhost'. The NOT operator can also be
combined with OR. For instance
<PRE>
<VAR>class1</VAR>|!<VAR>class2</VAR>
</PRE>
<P>
would select hosts which were either in class 1, or those
which were not in class 2.
<P>
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:
<PRE>
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
</PRE>
<P>
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:
<PRE>
cfengine -p -v
</PRE>
<P>
and these will be displayed. For example, solaris 2.4 systems
generate the additional classes <CODE>sunos_5_4</CODE> and <CODE>sunos_sun4m</CODE>,
<CODE>sunos_sun4m_5_4</CODE>.
<P>
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. <CODE>uname -n</CODE> 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! <EM>NOTE: in order to ensure that
the fully qualified name of the host becomes a class you must define the
domain variable.</EM> The dots in this string will be replaced by underscores.
<A NAME="IDX56"></A>
<A NAME="IDX57"></A>
<A NAME="IDX58"></A>
<P>
In summary, the operator ordering in cfengine classes is as follows:
<A NAME="IDX59"></A>
<A NAME="IDX60"></A>
<A NAME="IDX61"></A>
<DL COMPACT>
<DT><SAMP>`()'</SAMP>
<DD>
Parentheses override everything.
<DT><SAMP>`!'</SAMP>
<DD>
The NOT operator binds tightest.
<DT><SAMP>`.'</SAMP>
<DD>
The AND operator binds more tightly than OR.
<DT><SAMP>`|'</SAMP>
<DD>
OR is the weakest operator.
</DL>
<H2><A NAME="SEC22" HREF="cfengine-Tutorial_toc.html#TOC22">Variable substitution</A></H2>
<P>
<A NAME="IDX62"></A>
<A NAME="IDX63"></A>
<A NAME="IDX64"></A>
<A NAME="IDX65"></A>
<A NAME="IDX66"></A>
<A NAME="IDX67"></A>
<A NAME="IDX68"></A>
<A NAME="IDX69"></A>
<A NAME="IDX70"></A>
<A NAME="IDX71"></A>
<A NAME="IDX72"></A>
<P>
<A NAME="IDX73"></A>
<A NAME="IDX74"></A>
<A NAME="IDX75"></A>
<P>
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.
<UL>
<LI>Environment variables from the shell
<LI>Special variables used in cfengine features
<LI>General macro-string substitution.
</UL>
<P>
Environment variables are fetched directly from the shell on whatever
system is running the program. An example of a special variable is the
<CODE>domain</CODE> 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:
<PRE>
control:
myvar = ( /usr/local/mydir/lib/very/long/path ) # define macro
...
links:
$(myvar) -> /another/directory
</PRE>
<P>
Here we define a macro called <CODE>myvar</CODE>, which is later used to
define the creation of a link. As promised we can also define
class-dependent variables:
<PRE>
control:
sun4:: myvar = ( sun )
hpux:: myvar = ( HP )
</PRE>
<P>
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.
<P>
You can also import values from the execution of a shell command
by prefixing a command with the word <CODE>exec</CODE>.
<P>
<A NAME="IDX76"></A>
<A NAME="IDX77"></A>
<PRE>
control:
listing = ( "exec /bin/ls" )
</PRE>
<P>
This sets the variable `listing' to the output of the command in the
quotes.
<P>
Variables are referred to in either of two different ways, depending on
your taste. You can use the forms <CODE>$(variable)</CODE> or
<CODE>${variable}</CODE>. 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.
<DL COMPACT>
<DT><CODE>AllClasses</CODE>
<DD>
A long string in the form <SAMP>`CFALLCLASSES=class1:class2...'</SAMP>. 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.
<A NAME="IDX78"></A>
<A NAME="IDX79"></A>
<A NAME="IDX80"></A>
<A NAME="IDX81"></A>
<DT><CODE>arch</CODE>
<DD>
The current detailed architecture string--an amalgamation of the
information from <EM>uname</EM>. Non-definable.
<A NAME="IDX82"></A>
<DT><CODE>binserver</CODE>
<DD>
The default server for binary data. See section <A HREF="cfengine-Tutorial.html#SEC44">Cfengine's model for NFS-mounted filesystems</A>.
Non definable.
<A NAME="IDX83"></A>
<DT><CODE>class</CODE>
<DD>
The currently defined system hard-class (e.g. <CODE>sun4</CODE>, <CODE>hpux</CODE>).
Non-definable.
<A NAME="IDX84"></A>
<DT><CODE>date</CODE>
<DD>
The current date string. Note that if you use this in a shell command it might
be interpreted as a list varaible, since it contains the default separator
<SAMP>`:'</SAMP>.
<A NAME="IDX85"></A>
<DT><CODE>domain</CODE>
<DD>
The currently defined domain.
<A NAME="IDX86"></A>
<DT><CODE>faculty</CODE>
<DD>
The faculty or site as defined in control (see site).
<A NAME="IDX87"></A>
<DT><CODE>fqhost</CODE>
<DD>
The fully qualified (DNS/BIND) hostname of the system, which
includes the domain name as well.
<A NAME="IDX88"></A>
<DT><CODE>host</CODE>
<DD>
The hostname of the machine running the program.
<A NAME="IDX89"></A>
<DT><CODE>ipaddress</CODE>
<DD>
The numerical form of the internet address of the host currently running
cfengine.
<A NAME="IDX90"></A>
<DT><CODE>MaxCfengines</CODE>
<DD>
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.
<A NAME="IDX91"></A>
<DT><CODE>OutputPrefix</CODE>
<DD>
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,
<PRE>
OutputPrefix = ( "cfengine:$(host):")
</PRE>
<A NAME="IDX92"></A>
<DT><CODE>RepChar</CODE>
<DD>
The character value of the string used by the file repository in
constructing unique filenames from path names. This is the character which
replaces <SAMP>`/'</SAMP> (see the reference manual).
<A NAME="IDX93"></A>
<DT><CODE>site</CODE>
<DD>
This variable is identical to <CODE>$(faculty)</CODE> and may be used interchangeably.
<A NAME="IDX94"></A>
<DT><CODE>split</CODE>
<DD>
The character on which list variables are split (see the reference manual).
<A NAME="IDX95"></A>
<DT><CODE>sysadm</CODE>
<DD>
The name or mail address of the system administrator.
<A NAME="IDX96"></A>
<DT><CODE>timezone</CODE>
<DD>
The current timezone as defined in <CODE>control</CODE>.
<A NAME="IDX97"></A>
<DT><CODE>UnderscoreClasses</CODE>
<DD>
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.
<A NAME="IDX98"></A>
<A NAME="IDX99"></A>
<A NAME="IDX100"></A>
<A NAME="IDX101"></A>
<A NAME="IDX102"></A>
<A NAME="IDX103"></A>
<DT><CODE>year</CODE>
<DD>
The current year.
<A NAME="IDX104"></A>
</DL>
<P>
These variables are kept special because they play a special role in
setting up a system configuration. See section <A HREF="cfengine-Tutorial.html#SEC38">Designing a global system configuration</A>.
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.
<P>
<EM>NOTE: the above control variables are not case sensitive, unlike
user macros, so you should not define your own macros with these names.</EM>
<P>
The following variables are also reserved and may be used to produce
troublesome special characters in strings.
<DL COMPACT>
<DT><CODE>cr</CODE>
<DD>
Expands to the carriage-return character.
<A NAME="IDX105"></A>
<DT><CODE>dblquote</CODE>
<DD>
Expands to a double quote <CODE>"</CODE>
<A NAME="IDX106"></A>
<DT><CODE>dollar</CODE>
<DD>
Expands to <SAMP>`$'</SAMP>.
<A NAME="IDX107"></A>
<DT><CODE>lf</CODE>
<DD>
Expands to a line-feed character (unix end of line).
<A NAME="IDX108"></A>
<DT><CODE>n</CODE>
<DD>
Expands to a newline character.
<A NAME="IDX109"></A>
<DT><CODE>quote</CODE>
<DD>
Expands to a single quote <CODE>'</CODE>.
<A NAME="IDX110"></A>
<DT><CODE>spc</CODE>
<DD>
Expands simply to a single space. This can be used to place spaces in
filenames etc.
<A NAME="IDX111"></A>
<DT><CODE>tab</CODE>
<DD>
Expands to a single tab character.
<A NAME="IDX112"></A>
</DL>
<P>
You can use variables in the following places:
<UL>
<LI>In any directory name. The <CODE>$(binserver)</CODE> variable is not always appropriate in this context. For instance
</UL>
<PRE>
links:
osf::
/$(site)/${host}/directory -> somefile
</PRE>
<UL>
<LI>In any quoted string. (See <CODE>shellcommands</CODE> in the Reference manual).
</UL>
<PRE>
shellcommands:
any::
"/bin/echo $(timezone) | /bin/mail $(sysadm)"
'/bin/echo "double quotes!"'
</PRE>
<P>
<A NAME="IDX113"></A>
<P>
The latter possibility enables cfengine's variables to be passed
on to user-defined scripts.
<UL>
<LI>To define the values of options passed to various actions,
in the form <CODE><VAR>option</VAR>=$(variable)</CODE>.
</UL>
<P>
Variables can be defined differently under different classes by
preceding the definition with a class name. For example:
<PRE>
control:
sun4:: my_macro = ( User_string_1 )
irix:: my_macro = ( User_string_2 )
</PRE>
<P>
Here the value assigned to <CODE>$(my_macro)</CODE> 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.
<PRE>
control:
physics:: sysadm = ( mark,fred )
chemistry:: sysadm = ( localsys@domain )
</PRE>
<P>
<A NAME="IDX114"></A>
<A NAME="IDX115"></A>
<P>
Note, incidentally, that the <SAMP>`-a'</SAMP> option
can be used to print out the mail address of the system administrator
for any wrapper scripts.
<H2><A NAME="SEC23" HREF="cfengine-Tutorial_toc.html#TOC23">Defining classes and making exceptions</A></H2>
<P>
<A NAME="IDX116"></A>
<A NAME="IDX117"></A>
<P>
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.
<UL>
<LI>Classes may be defined manually from the command line.
<LI>Classes may be defined locally in the actionsequence in order to
execute only some of the actions within a special category.
<LI>Classes may become defined if cfengine actually needs to carry out an action to
repair the system's configuration.
<LI>Classes may be defined by user-defined plug-in modules.
<A NAME="IDX118"></A>
<A NAME="IDX119"></A>
</UL>
<P>
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.
<H3><A NAME="SEC24" HREF="cfengine-Tutorial_toc.html#TOC24">Command line classes</A></H3>
<P>
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 <EM>include</EM>. We use <CODE>addclasses</CODE> to
do this.
<PRE>
addclasses = ( include othersymbols )
</PRE>
<P>
The purpose of this
would be to allow certain `excludable actions' to be defined.
Actions defined by
<PRE>
any.include::
<VAR>actions</VAR>
</PRE>
<P>
will normally be carried out, because we have defined <CODE>include</CODE> to
be true using <CODE>addclasses</CODE>. But if cfengine is run in a restricted
mode, in which <CODE>include</CODE> is set to false, we can exclude these
actions.
<P>
So, by defining the symbol <CODE>include</CODE> to be false, you can exclude
all of the actions which have <CODE>include</CODE> as a member. There are two
ways in which this can be done, one is to negate a class globally using
<PRE>
cfengine -N include
</PRE>
<P>
This undefines the class <CODE>include</CODE> for the entire duration of the
program.
<H3><A NAME="SEC25" HREF="cfengine-Tutorial_toc.html#TOC25">actionsequence classes</A></H3>
<P>
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
<SAMP>`.'</SAMP> to separate the words. In this case the symbol only evaluates
to `true' for the duration of the action to which it it attached. Here
is an example:
<PRE>
links.onlysome
shellcommands.othersymbols.onlysome
</PRE>
<P>
In the first case <EM><CODE>onlysome</CODE> is defined to be true</EM> while
this instance of <CODE>links</CODE> is executed. That means that only actions
labelled with the class <CODE>onlysome</CODE> will be executed as a result of
that statement. In the latter case, both <CODE>onlysome</CODE> and
<CODE>othersymbols</CODE> are defined to be true for the duration of
<CODE>shellcommands</CODE>.
<P>
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.
<H3><A NAME="SEC26" HREF="cfengine-Tutorial_toc.html#TOC26">shellcommand classes</A></H3>
<P>
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
<PRE>
groups:
have_cc = ( "/bin/test -f /usr/ucb/cc" "/bin/test -f /local/gnu/cc" )
</PRE>
<P>
Note that as of version 1.4.0 of cfengine, you may use the word
<CODE>classes</CODE> as an alias for <CODE>groups</CODE>. 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 <SAMP>`have_cc'</SAMP>) 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 <SAMP>`have_cc'</SAMP> will be defined above if either <TT>`/usr/ucb/cc'</TT>
or <TT>`/local/gnu/cc'</TT> exist, or both.
<A NAME="IDX120"></A>
<A NAME="IDX121"></A>
<A NAME="IDX122"></A>
<A NAME="IDX123"></A>
<H3><A NAME="SEC27" HREF="cfengine-Tutorial_toc.html#TOC27">Feedback classes</A></H3>
<P>
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
<PRE>
define=<VAR>classlist</VAR>
</PRE>
<P>
Classes like these should generally be declared at the start of a program
unless the <CODE>define</CODE> statements always precede the actions which
use the defined classes, with <CODE>addinstallable</CODE>.
<H3><A NAME="SEC28" HREF="cfengine-Tutorial_toc.html#TOC28">Writing plugin modules</A></H3>
<P>
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.
<P>
Modules must lie in a special directory defined by the variable
<CODE>moduledirectory</CODE>.
<A NAME="IDX124"></A>
<A NAME="IDX125"></A>
They must have a name of the form <TT>`module:<VAR>mymodule</VAR>'</TT> 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 <SAMP>`+'</SAMP> sign are treated as classes to be defined
(like -D), while lines which begin with a <SAMP>`-'</SAMP> sign are treated as
classes to be undefined (like -N). 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:
<PRE>
control:
moduledirectory = ( /local/cfengine/modules )
actionsequence = (
files
module:myplugin.specialclass
copy
)
...
</PRE>
<P>
Note that the class definitions for the module can also be defined in as
<CODE>AddInstallables</CODE>, if this is more convenient.
Next we write the plugin itself.
<PRE>
#!/usr/bin/perl
#
# module:myplugin
#
# lots of computation....
if (<VAR>special-condition</VAR>)
{
print "+specialclass";
}
</PRE>
<P>
Modules inherit the environment variables
<H2><A NAME="SEC29" HREF="cfengine-Tutorial_toc.html#TOC29">The generic class <CODE>any</CODE></A></H2>
<P>
<A NAME="IDX126"></A>
<A NAME="IDX127"></A>
<A NAME="IDX128"></A>
<P>
The generic wildcard <CODE>any</CODE> may be used to stand for any class.
Thus instead of assigning actions for the class <CODE>sun4</CODE> only you
might define actions for any architecture by specifying:
<PRE>
any::
<VAR>actions</VAR>
</PRE>
<P>
If you don't specify any class at all then cfengine assumes a default value of <CODE>any</CODE> for the
class.
<H2><A NAME="SEC30" HREF="cfengine-Tutorial_toc.html#TOC30">Debugging tips</A></H2>
<P>
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:
<PRE>
myclass::
</PRE>
<P>
can be changed to
<PRE>
Xmyclass::
</PRE>
<P>
Since <CODE>Xmyclass</CODE> no longer matches any defined classes, and is not
the name of any host it will simply be ignored. The <CODE>-N</CODE> option
can also be used to the same effect. (see Reference manual).
<A NAME="IDX129"></A>
<A NAME="IDX130"></A>
<A NAME="IDX131"></A>
<A NAME="IDX132"></A>
<H2><A NAME="SEC31" HREF="cfengine-Tutorial_toc.html#TOC31">Access control</A></H2>
<P>
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 <CODE>control:</CODE> section of your program. For example,
<PRE>
control:
...
access = ( mark root )
</PRE>
<P>
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.
<A NAME="IDX133"></A>
<A NAME="IDX134"></A>
<A NAME="IDX135"></A>
<P>
Note: if you are running cfengine via the <CODE>cfrun</CODE> program
<A NAME="IDX136"></A>
then cfengine is always started with the same user identity as
the cfd process on the remote host.
<A NAME="IDX137"></A>
Normally this is the root user identity. This means that
the access keyword will have no effect on the use of
the command <CODE>cfrun</CODE>.
<H2><A NAME="SEC32" HREF="cfengine-Tutorial_toc.html#TOC32">Wildcards in directory names</A></H2>
<P>
<A NAME="IDX138"></A>
<A NAME="IDX139"></A>
<P>
In the two actions <CODE>files</CODE> and <CODE>tidy</CODE> 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 <EM>wildcards</EM>. For example, the directory names
<PRE>
/usr/*/*
/bla/*/ab?/bla
</PRE>
<P>
represent all of the <EM>directories</EM> (and only directories) which
match the above wildcard strings. Cfengine opens each matching
directory and iterates the action over all directories which match.
<P>
The symbol <SAMP>`?'</SAMP> matches any single character, whereas <SAMP>`*'</SAMP>
matches any number of characters, in accordance with shell
file-substitution wildcards.
<A NAME="IDX140"></A>
<A NAME="IDX141"></A>
<P>
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 <CODE>pattern</CODE> directive in
<CODE>tidy</CODE> can be used to specify patterns when tidying files and under
<CODE>files</CODE> all files are considered, (see Reference manual),
<H2><A NAME="SEC33" HREF="cfengine-Tutorial_toc.html#TOC33">File sweeps</A></H2>
<P>
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.
<UL>
<LI>
As part of a <CODE>files</CODE> action, for checking access rights and ownership
of files.
<A NAME="IDX142"></A>
<LI>
As part of a <CODE>tidy</CODE> action, for checking files for deletion.
<A NAME="IDX143"></A>
<LI>
As part of a <CODE>copy</CODE> action, while recursively checking whether to
copy a file tree.
<A NAME="IDX144"></A>
</UL>
<P>
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
<UL>
<LI>
excluding certain named directories and their subdirectories with <CODE>ignore</CODE>.
<LI>
excluding certain files and directories matching a specific pattern.
<LI>
including only a subset of files matching specific patterns.
</UL>
<P>
The tidy action is slightly different in this respect, since it
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 <CODE>tidy</CODE>
is different and is documented in the section on tidying, (see Reference manual).
<P>
Items declared under the global <CODE>ignore</CODE> section affect files,
copy, links and tidy. For file sweeps within files, copy and links, you
may provide private ignore lists using <CODE>ignore=</CODE>.
<A NAME="IDX145"></A>
<A NAME="IDX146"></A>
<P>
For file sweeps within <CODE>files</CODE> and <CODE>copy</CODE> you can specify
specific search parameters using the keywords <CODE>include=</CODE>
and <CODE>exclude=</CODE>.
<A NAME="IDX147"></A>
<A NAME="IDX148"></A>
<A NAME="IDX149"></A>
<A NAME="IDX150"></A>
For example,
<PRE>
files:
/usr/local/bin m=0755 exclude=*.ps action=fixall
</PRE>
<P>
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 <TT>`.ps'</TT>), (see Reference manual).
<P>
Specifying the <CODE>include=</CODE> keyword is slightly different since it
automatically restricts the search to only named patterns, 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 <CODE>exclude=<VAR>pattern</VAR></CODE>.
In other words, exclusions always override inclusions.
<P>
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 <TT>`.ps'</TT>
files above, you would need to code something like this:
<PRE>
files:
/usr/local/bin m=0644 include=*.ps action=fixall
</PRE>
<P>
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.
<A NAME="IDX151"></A>
<H2><A NAME="SEC34" HREF="cfengine-Tutorial_toc.html#TOC34">Log files written by cfengine</A></H2>
<P>
<A NAME="IDX152"></A>
<A NAME="IDX153"></A>
<A NAME="IDX154"></A>
<A NAME="IDX155"></A>
<P>
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
<CODE>Syslog</CODE> variable, (see Reference manual).
<P>
The first log cfengine keeps is for every user
(every subdirectory of a home directory filesystem). A file
<CODE>~/.cfengine.rm</CODE> keeps a list of all the files which were deleted
during the last pass of the <CODE>tidy</CODE> 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.
<P>
<A NAME="IDX156"></A>
Another file is built when cfengine searches through file trees in the
<CODE>files</CODE> 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 <CODE>/etc/cfengine/cfengine.log</CODE>. The file
is not readable for general users.
<A NAME="IDX157"></A>
<A NAME="IDX158"></A>
<H2><A NAME="SEC35" HREF="cfengine-Tutorial_toc.html#TOC35">Quoted strings</A></H2>
<P>
In several cfengine commands, you use quoted strings to define a quantity
of text which may contain spaces. For example
<PRE>
control:
macro = ( "mycommand" )
editfiles:
{ $(HOME)/myfile
AppendIfNoSuchLine 'This text contains space'
}
</PRE>
<P>
In each case you may use any one of the three types of quote marks in
order to delimit strings,
<PRE>
' <VAR>or</VAR> " <VAR>or</VAR> `
</PRE>
<P>
If you choose, say <CODE>"</CODE>, 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.
<A NAME="IDX159"></A>
<A NAME="IDX160"></A>
<A NAME="IDX161"></A>
<A NAME="IDX162"></A>
<A NAME="IDX163"></A>
<A NAME="IDX164"></A>
If you need to quote a quoted string, then you should choose a delimiter
which does not conflict with the substring.
<P>
Note that you can use special variables for certain symbols in a string
See section <A HREF="cfengine-Tutorial.html#SEC22">Variable substitution</A>.
<H2><A NAME="SEC36" HREF="cfengine-Tutorial_toc.html#TOC36">Regular expressions</A></H2>
<P>
Regular expressions can be used in cfengine in connection with
<CODE>editfiles</CODE> and <CODE>processes</CODE> 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.
<P>
<EM>NOTE: the special characters <SAMP>`*'</SAMP> and <SAMP>`?'</SAMP>
used in wildcards do not have the
same meanings as regular expressions!</EM>.
<P>
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 <SAMP>`cfengine'</SAMP> would match only the string "cfengine", not
"Cfengine" or "cfengin" etc. Other regular expressions could match more
general strings. For instance, the regular expression <SAMP>`c*'</SAMP> matches
any number of c's (including none). Thus this expression would match the
empty string, "c", "cccc", "ccccccccc", but not "cccx".
<P>
Here is a list of regular expression special characters and operators.
<DL COMPACT>
<DT><SAMP>`\'</SAMP>
<DD>
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 <CODE>[\]</CODE> or quoted with a backslash itself <SAMP>`\\'</SAMP>.
<DT><SAMP>`\b'</SAMP>
<DD>
Matches word boundary operator.
<DT><SAMP>`\B'</SAMP>
<DD>
Match within a word (operator).
<DT><SAMP>`\<'</SAMP>
<DD>
Match beginning of word.
<DT><SAMP>`\>'</SAMP>
<DD>
Match end of word.
<DT><SAMP>`\w'</SAMP>
<DD>
Match a character which can be part of a word.
<DT><SAMP>`\W'</SAMP>
<DD>
Match a character which cannot be part of a word.
<DT><SAMP>`<VAR>any character</VAR>'</SAMP>
<DD>
Matches itself.
<DT><SAMP>`.'</SAMP>
<DD>
Matches any character
<DT><SAMP>`*'</SAMP>
<DD>
Match zero or more instances of the previous object. e.g. <SAMP>`c*'</SAMP>.
If no object precedes it, it represents a literal asterisk.
<DT><SAMP>`+'</SAMP>
<DD>
Match one or more instances of the preceding object.
<DT><SAMP>`?'</SAMP>
<DD>
Match zero or one instance of the preceding object.
<DT><SAMP>`{ }'</SAMP>
<DD>
Number of matches operator. <SAMP>`{5}'</SAMP> would match exactly 5
instances of the previous object. <SAMP>`{6,}'</SAMP> would match at least
6 instances of the previous object. <SAMP>`{7,12}'</SAMP> 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.
<DT><SAMP>`|'</SAMP>
<DD>
The logical OR operator, OR's any two regular expressions.
<DT><SAMP>`[<VAR>list</VAR>]'</SAMP>
<DD>
Defines a list of characters which are to be considered as a single
object (ORed). e.g. <SAMP>`[a-z]'</SAMP> matches any character in the range a to
z, <SAMP>`abcd'</SAMP> matches either a, b, c or d. Most characters are
ordinary inside a list, but there are some exceptions: <SAMP>`]'</SAMP> ends the
list unless it is the first item, <SAMP>`\'</SAMP> quotes the next character,
<SAMP>`[:'</SAMP> and <SAMP>`:]'</SAMP> define a character class operator (see below),
and <SAMP>`-'</SAMP> represents a range of characters unless it is the first
or last character in the list.
<DT><SAMP>`[^<VAR>list</VAR>]'</SAMP>
<DD>
Defines a list of characters which are NOT to be matched. i.e.
match any character except those in the list.
<DT><SAMP>`<SAMP>`[:<VAR>class</VAR>:]'</SAMP>'</SAMP>
<DD>
Defines a class of characters, using the ctype-library.
<DL COMPACT>
<DT><CODE>alnum</CODE>
<DD>
Alpha numeric character
<DT><CODE>alpha</CODE>
<DD>
An alphabetic character
<DT><CODE>blank</CODE>
<DD>
A space or a TAB
<DT><CODE>cntrl</CODE>
<DD>
A control character.
<DT><CODE>digit</CODE>
<DD>
0-9
<DT><CODE>graph</CODE>
<DD>
same as print, without space
<DT><CODE>lower</CODE>
<DD>
a lower case letter
<DT><CODE>print</CODE>
<DD>
printable characters (non control characters)
<DT><CODE>punct</CODE>
<DD>
neither control nor alphanumeric symbols
<DT><CODE>space</CODE>
<DD>
space, carriage return, line-feed, vertical tab and form-feed.
<DT><CODE>upper</CODE>
<DD>
upper case letter
<DT><CODE>xdigit</CODE>
<DD>
a hexadecimal digit 0-9, a-f
</DL>
<DT><SAMP>`<SAMP>`(..)'</SAMP>'</SAMP>
<DD>
Groups together any number of operators.
<DT><SAMP>`\<VAR>digit</VAR>'</SAMP>
<DD>
Back-reference operator (refer to the GNU regex documentation).
<DT><SAMP>`^'</SAMP>
<DD>
Match start of a line.
<DT><SAMP>`$'</SAMP>
<DD>
Match the end of a line.
</DL>
<P>
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).
<PRE>
^# 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
</PRE>
<H2><A NAME="SEC37" HREF="cfengine-Tutorial_toc.html#TOC37">Iterating over lists</A></H2>
<P>
Shell list variables are normally defined by joining together a list of
directories using a concatenation character such as <SAMP>`:'</SAMP>. A typical
example of this is the PATH variable:
<PRE>
PATH=/usr/bin:/usr/local/bin:/usr/sbin
</PRE>
<P>
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:
<UL>
<LI>
in the `to' field of a multiple link action,
<LI>
in the `from' field of a copy action,
<LI>
in the directory field of a tidy action,
<LI>
in the directory field of the files action,
<LI>
in the ignore action,
<LI>
in a shell command.
</UL>
<P>
This typically allows communication with PATH-like
environment variables in the shell.
<A NAME="IDX165"></A>
<A NAME="IDX166"></A>
<A NAME="IDX167"></A>
<A NAME="IDX168"></A>
<P>
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 <CODE>split</CODE> variable
in the control section of the program (see Reference manual).
<P>
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
<PRE>
control:
actionsequence = ( links tidy )
links:
/allbin +> $(PATH)
tidy:
# Hopefully no-match matches nothing
/allbin pattern=no-match age=0 links=tidy
</PRE>
<P>
<VAR>no-match</VAR> is not a reserved word in cfengine, this is
just a string you do not expect to match any file.
<P>
Alternatively, you might want to define an internal list using
a space as a separator:
<A NAME="IDX169"></A>
<PRE>
control:
split = ( " " )
mylist = ( "mark ricky bad-dude" )
tidy:
/mnt/home1/$(mylist) pattern=*.cfsaved age=1
</PRE>
<P>
This example iterates the tidy action over the directories <TT>`/mnt/home1/mark'</TT>,
<TT>`/mnt/home1/ricky'</TT> and <TT>`/mnt/home1/bad-dude'</TT>.
<P>
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
<TT>`bin'</TT>, <TT>`lib'</TT> etc in several different package directories.
<A NAME="IDX170"></A>
<A NAME="IDX171"></A>
<A NAME="IDX172"></A>
<H1><A NAME="SEC38" HREF="cfengine-Tutorial_toc.html#TOC38">Designing a global system configuration</A></H1>
<P>
This chapter is about building strategies for putting together a
site configuration for your entire network.
<H2><A NAME="SEC39" HREF="cfengine-Tutorial_toc.html#TOC39">General considerations</A></H2>
<P>
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.
<A NAME="IDX173"></A>
<A NAME="IDX174"></A>
<P>
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.
<P>
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.
<P>
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.
<H2><A NAME="SEC40" HREF="cfengine-Tutorial_toc.html#TOC40">Using netgroups</A></H2>
<P>
<A NAME="IDX175"></A>
<A NAME="IDX176"></A>
<A NAME="IDX177"></A>
<A NAME="IDX178"></A>
<P>
If you use the network information service (NIS) on your local network
then you may already have defined <EM>netgroups</EM> 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 <CODE>/etc/exports</CODE> file as you use to define
the mount groups and classes.
<P>
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.
<P>
To make a netgroup you need to define a list in the file
<CODE>/etc/netgroup</CODE> 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:
<PRE>
mylist-name (host1,,) (host2,,) (host3,,) (host4,,)
norway-sun4-host (saga,,) (tor,,) (odin,,)
foes-linux-hosts (borg,,)
</PRE>
<P>
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.
<P>
The usefulness of netgroups is that they can be used to stand for a list
of hostnames in system files like <TT>`/etc/exports'</TT>. 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.
<P>
The netgroups can now be used in cfengine programs by using the <CODE>+</CODE>
or <CODE>@+</CODE> symbols in the <CODE>groups</CODE> section. (see Reference manual).
<H2><A NAME="SEC41" HREF="cfengine-Tutorial_toc.html#TOC41">Files and links</A></H2>
<P>
File and link management takes several forms.
Actions are divided into three categories called
<CODE>files</CODE>, <CODE>tidy</CODE> and <CODE>links</CODE>. 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:
<PRE>
files:
<VAR>class</VAR>::
/<VAR>path</VAR> mode=<VAR>mode</VAR> owner=<VAR>owner</VAR> group=<VAR>group</VAR>
recurse=<VAR>no-of-levels</VAR> action=<VAR>action</VAR>
</PRE>
<P>
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 <CODE>recurse</CODE> directive, and various options for dealing with
symbolic links and device boundaries. The mode-string defines the
allowed file-mode (by analogy with <SAMP>`chmod'</SAMP>) 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.
<P>
For example,
<PRE>
files:
any::
/usr/*/bin mode=a+rx,o-w own=root r=inf act=fixall
</PRE>
<P>
which (in abbreviated form) would check recursively all files and
directories starting from directories matching the wildcard
(e.g. <TT>`/usr/local/bin'</TT>, <TT>`/usr/ucb/bin'</TT>). By default, <CODE>fixall</CODE>
causes the permissions and ownership of the files to be fixed without
further warning.
<P>
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 <CODE>links=tidy</CODE> in the files
section. If this is set, cfengine will remove any symbolic links which
do not point to existing files (see Reference manual).
<P>
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
<PRE>
links:
binaryhost::
/local/elm/bin +> /local/bin
</PRE>
<P>
links all of the files in <TT>`/local/elm/bin'</TT> to corresponding files
in <TT>`/local/bin'</TT>. 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.
<P>
The need to tidy junk files has become increasingly evident during the
history of cfengine. Files build up quickly in areas like <TT>`/tmp'</TT>,
<TT>`/var/tmp'</TT>. 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 <TT>`core'</TT> files<A NAME="DOCF1" HREF="cfengine-Tutorial_foot.html#FOOT1">(1)</A>
and compilation by-products (<SAMP>`.o'</SAMP> files and <SAMP>`.log'</SAMP> 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:
<PRE>
tidy:
AllHomeServers::
home pattern=core r=inf age=0
home/.wastebacket 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
</PRE>
<P>
all hosts in the group <SAMP>`AllHomeServers'</SAMP> are instructed to
iterate over all users' home directories (using the wildcard
<CODE>home</CODE>) and look for files matching special patterns.
Cfengine tests the <EM>access time</EM> 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 <TT>`.wastebasket'</TT> are deleted
only after they have lain there untouched for 14 days, and so on.
<P>
<A NAME="IDX179"></A>
<A NAME="IDX180"></A>
<P>
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.
<P>
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.
<P>
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
<CODE>~/.cfengine.rm</CODE>.
<P>
You might consider tidying certain files only once a week, in which case
a command such as
<PRE>
tidy:
AllHomeServers.Sunday::
<VAR>files to tidy</VAR>
</PRE>
<P>
could be useful. Nonsense files, such as `core' files could be tidied every night.
<P>
<A NAME="IDX181"></A>
<EM>NOTE! Be careful when telling cfengine to delete core files. If
you write a wildcard like <CODE>core*</CODE>, then you could risk deleting
important system files such as <CODE>core.h</CODE>.</EM>
<H2><A NAME="SEC42" HREF="cfengine-Tutorial_toc.html#TOC42">Copying files</A></H2>
<P>
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.
<P>
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.
<UL>
<LI>
A date-stamp comparison with a master file, using last-change times, can
be used to tell cfengine to recopy a file from the master if the master
file is newer than the copy.
<LI>
A checksum can be computed for each file and compared with one for
the master file. If the contents of the copy file differs in any way from
the master, the file will be re-copied.
</UL>
<P>
Cfengine allows you to do the following
<UL>
<LI>
Copy a single file to another file in a different location, perhaps with a
new name, new permissions and a different owner.
<LI>
Copy a single file to all users on the system, changing the owner of the
file for each user automatically. (This could be used to distribute and
update standard setup files.)
<LI>
Recursively copy an entire file tree, omitting files which match a list
of wildcard-patterns, or linking certain files instead of copying.
</UL>
<P>
You can find out more about copying in the reference section.
<H2><A NAME="SEC43" HREF="cfengine-Tutorial_toc.html#TOC43">Managing processes</A></H2>
<P>
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
<TT>`cron'</TT> and <TT>`inetd'</TT> the HUP signal, after editing their
configuration files, or killing unwanted processes (such as user
programs which hog the system at peak usage times).
<P>
You can read more about this in the reference section .
<H2><A NAME="SEC44" HREF="cfengine-Tutorial_toc.html#TOC44">Cfengine's model for NFS-mounted filesystems</A></H2>
<P>
<A NAME="IDX182"></A>
<A NAME="IDX183"></A>
<P>
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 <EM>home directories</EM> and <EM>binary
directories</EM>. A home directory is a place where users' login
directories are kept. This is traditionally a directory called
<TT>`/home'</TT> or <TT>`/users'</TT> 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 <TT>`/usr/local'</TT> or simply <TT>`/local'</TT>.
<P>
In this chapter we shall consider a scheme for using cfengine to make NFS filesystem management
quite painless.
<H3><A NAME="SEC45" HREF="cfengine-Tutorial_toc.html#TOC45">NFS filesystem resources</A></H3>
<P>
<A NAME="IDX184"></A>
<P>
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: <EM>binary</EM> filesystems (those
which contain compiled software) and <EM>user</EM> or <EM>home</EM>
filesystems (which contain users' login areas).
<P>
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.
<P>
<A NAME="IDX185"></A>
<A NAME="IDX186"></A>
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 <CODE>ultrix</CODE> system onto an
<CODE>HPUX</CODE> system. There would be no point -- binary resources are
<EM>architecture</EM> or <EM>hard-class dependent</EM>. But home directories
are architecture independent.
<P>
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!
<H3><A NAME="SEC46" HREF="cfengine-Tutorial_toc.html#TOC46">Unique filesystem mountpoints</A></H3>
<P>
<A NAME="IDX187"></A>
<A NAME="IDX188"></A>
<P>
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 <CODE>/usr/local</CODE>, both of
which we might like to mount since they contain different software.
<P>
A simple but extremely useful naming scheme is the following.
<A NAME="DOCF2" HREF="cfengine-Tutorial_foot.html#FOOT2">(2)</A> 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:
<UL>
<LI>
When mounting a remote filesystem on your local system, the local and
remote directories should always have exactly the same name.
<LI>
The name of every filesystem mountpoint should be unique and tell
you something meaningful about where it is located and
what its function is.
<LI>
You can always make links from special unique names to more general
names like <TT>`/usr/local'</TT>. If you this involves compiled software and
you do this on one host, you should do it on others which are of the
same type.
<LI>
It doesn't matter whether software compiles in the path names
of special directories into software as long as you follow
the points above.
</UL>
<P>
Each filesystem is given a directory
name composed of three parts:
<PRE>
/site/host/contents
</PRE>
<P>
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:
<PRE>
/physics/einstein/local # /usr/local for einstein@physics
/physics/newton/u1 # user partition 1 for newton@physics
</PRE>
<P>
On the machines which are home to the `local' partition, it is better to
make a link to <CODE>/usr/local</CODE> than call the filesystem
<CODE>/usr/local</CODE> directly. This is because it makes the procedure of
organizing the entire network much clearer.
<P>
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 <CODE>/usr/local</CODE>, so this small amount of extra work
is really no work at all.
<P>
The whole naming convention is compactly summarized by defining a mount
point variable, <CODE>mountpattern</CODE>. With the present scheme, this can
be defined as
<PRE>
mountpattern = ( /$(site)/$(host) )
</PRE>
<P>
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
<CODE>homepattern</CODE> pattern variable, which is used to distinguish
between home directories and binary resources. (See <CODE>homepattern</CODE>
in the reference section). You can think of this as being part of the
naming convention. In this text, we use the convention <CODE>u1 u2
u3...</CODE> for home disks. You could equally well use <CODE>home1 home2...</CODE>
etc. As long as the name is unique, it doesn't matter.
<P>
The full list of named resources should now be listed in the
<CODE>mountables</CODE> list, which is simply a list of all the resources
available for mounting on the network.
<H3><A NAME="SEC47" HREF="cfengine-Tutorial_toc.html#TOC47">How does it work?</A></H3>
<P>
<A NAME="IDX189"></A>
<A NAME="IDX190"></A>
<A NAME="IDX191"></A>
<P>
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.
<P>
Suppose we make a <CODE>binserver</CODE> declaration:
<PRE>
binservers:
mygroup.sun4::
einstein
newton
</PRE>
<P>
This would tell cfengine that it should mount all binary resources from
hosts <CODE>einstein</CODE> or <CODE>newton</CODE> onto any host of type <CODE>sun4</CODE>
in the group <CODE>mygroup</CODE>. Every filesystem which is listed in
<CODE>mountables</CODE> and is not a home directory will be mounted.
<P>
Home directories and binary resources are kept separate automatically by
cfengine, because a home directory is one whose contents-name matches
the <CODE>homepattern</CODE> pattern variable. See section <A HREF="cfengine-Tutorial.html#SEC46">Unique filesystem mountpoints</A>.
<P>
A <CODE>homeserver</CODE> declaration:
<PRE>
homeservers:
mygroup::
einstein
newton
schwinger
feynman
</PRE>
<P>
would correspondingly mean mount all the home directory resources on the
hosts in the list on all hosts in the group <CODE>mygroup</CODE>. Clearly it
is unnecessary to distinguish between the architecture platform types of
the actual servers for user directories.
<P>
In each case, cfengine will mount filesystems, make the appropriate
directories for the mount point and edit the filesystem table.
<H3><A NAME="SEC48" HREF="cfengine-Tutorial_toc.html#TOC48">Special variables</A></H3>
<P>
<A NAME="IDX192"></A>
<A NAME="IDX193"></A>
<A NAME="IDX194"></A>
<A NAME="IDX195"></A>
<P>
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 <CODE>/usr/local</CODE>. All
you need do now is to make a link:
<PRE>
links:
any::
/usr/local -> /$(site)/$(binserver)/local
</PRE>
<P>
The meaning of this is that, on any host, the directory
<CODE>/usr/local</CODE> should be a link to the `nearest' binary server's
`local' resource. The <CODE>$(binserver)</CODE> 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.
<P>
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
<CODE>/physics/einstein/local</CODE> 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 <CODE>$(host)</CODE> as the highest priority binary server for any
host. That means that if you have a local filesystem, it will always
have priority.
<P>
<A NAME="IDX196"></A>
<A NAME="IDX197"></A>
<A NAME="IDX198"></A>
In contrast, if the host `schwinger' ran the command above, it would
find no local filesystem called <CODE>/physics/schwinger/local</CODE>, so it
would go along the list of defined binary servers, find `einstein' and
try again. It will succeed in finding `einstein' <EM>provided all the
binary servers were mounted before the link command is executed</EM>. This
means that you should structure the <CODE>actionsequence</CODE> so that all
filesystems are mounted before any links are made.
<P>
With a little practice, the cfengine model can lead to an enormous
simplification of the issue of NFS-mountable resources.
<P>
<A NAME="IDX199"></A>
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 <CODE>editfiles</CODE> facility to add entries to
<TT>`/etc/exports'</TT> (see <CODE>editfiles</CODE> in the Reference manual). In practice this is very
difficult to do and perhaps not desirable.
<H3><A NAME="SEC49" HREF="cfengine-Tutorial_toc.html#TOC49">Example programs for mounting resources</A></H3>
<P>
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.
<PRE>
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
</PRE>
<P>
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.
<P>
The next thing that happens is that <CODE>mountinfo</CODE> builds a list of
the filesystems which each host has successfully mounted. Then by
calling <CODE>addmounts</CODE> 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 <CODE>mountables</CODE> tells cfengine what filesystems are available
over the network for the server hal. There are three filesystems which
can be mounted, called <TT>`/univ/home1'</TT>, <TT>`/univ/home2'</TT> and
<TT>`/univ/local'</TT>. 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.
<P>
Finally we come to <CODE>links</CODE> in the action sequence. This tells
cfengine to look at the defined links. There is one link defined: a
link from <TT>`/usr/local'</TT> to the mounted filesystem
<TT>`/univ/local'</TT>. 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 <TT>`/usr/local'</TT> to
<TT>`/univ/local'</TT>.
<P>
Here is another simple example program for checking and automatically
mounting an NFS based <CODE>/usr/local</CODE> and all home directories onto
all hosts on a small network. Here we have several servers and must
therefore use some classes.
<PRE>
#
# 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
</PRE>
<P>
Let's suppose we run this program on host2 which is an ultrix machine.
This host belongs to the class <CODE>mygroup</CODE> and the hard-class
<CODE>ultrix</CODE>. 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.
<P>
The action sequence starts by mounting all of the filesystems currently
in the filesystem table <TT>`/etc/fstab'</TT>. 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
<TT>`host1:/mysite/host1/u1'</TT> and <TT>`host1:/mysite/host1/u2'</TT>. If
they are not present they are added to <TT>`/etc/fstab'</TT><A NAME="DOCF3" HREF="cfengine-Tutorial_foot.html#FOOT3">(3)</A>. Next, we know that the binary server is server1,
so we should check for <TT>`server1:/mysite/server1/local'</TT>. 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.
<P>
Note that, in the process of adding the filesystems to
<TT>`/etc/fstab'</TT>, 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.
<P>
Finally, we reach the link section and we try to expand the variables.
<CODE>$(site)</CODE> expands to <TT>`mysite'</TT>. <CODE>$(binserver)</CODE> expands
first to the hostname (host2), but <TT>`/mysite/host2/local'</TT> does not
exist, so it then goes to the binserver list, which substitutes server1
for the value of <CODE>$(binserver)</CODE>. Since
<TT>`/mysite/server1/local'</TT> does exist and is now mounted, cfengine
makes a link to this directory from <TT>`/usr/local'</TT>. The script is
then completed.
<P>
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<A NAME="DOCF4" HREF="cfengine-Tutorial_foot.html#FOOT4">(4)</A>.
<H2><A NAME="SEC50" HREF="cfengine-Tutorial_toc.html#TOC50">Using the automounter</A></H2>
<P>
<A NAME="IDX200"></A>
<P>
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.
<P>
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.
<P>
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 <TT>`/etc/auto_master'</TT>,
<TT>`auto_direct'</TT> etc.
<A NAME="IDX201"></A>
<A NAME="IDX202"></A>
<P>
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 <TT>`/etc/fstab'</TT>, or the equivalent for
your system.
<P>
From cfengine, you can use the automounter instead of the static mount model
by
<UL>
<LI>
omitting <CODE>addmounts</CODE>, <CODE>mountinfo</CODE>, <CODE>mountall</CODE>
from the actionsequence, in the control part
of your cfengine program,
<LI>
using <CODE>editfiles</CODE> to edit the relevant configuration files
such as <TT>`/etc/auto_master'</TT>, or <TT>`auto_direct'</TT> etc,
<LI>
using the <CODE>AutomountDirectResources</CODE> command in editfiles
to dump the list of cfengine class-based list of mountables
into a file of your choice in the correct format for
autmount's direct maps,
<LI>
using <CODE>processes</CODE> to restart the automounter
(send the hangup signal <CODE>hup</CODE>), or perhaps stop and restart
the daemon by sending the <CODE>term</CODE> signal (you should never
send the <CODE>kill</CODE> signal).
<LI>
using the multiple link facilities to link in indirect mounted
filesystems as required, and <CODE>files</CODE> or <CODE>tidy</CODE> to
clean up stale links afterwards,
<LI>
perhaps using <CODE>copy</CODE> to distribute basic automount configuration
files to multiple systems.
</UL>
<P>
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
<TT>`/usr/local'</TT> 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.
<A NAME="IDX203"></A>
<A NAME="IDX204"></A>
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.
<P>
<A NAME="IDX205"></A>
<A NAME="IDX206"></A>
<A NAME="IDX207"></A>
Some systems advocate grouping all users' login (home) directories
under a common directory called <TT>`/home'</TT> or <TT>`users'</TT>.
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
<A NAME="IDX208"></A>
<PRE>
/<VAR>site</VAR>/<VAR>host</VAR>/home1
/<VAR>site</VAR>/<VAR>host</VAR>/home2
...
</PRE>
<P>
and then link them as follows:
<PRE>
/home +> /<VAR>site</VAR>/<VAR>host</VAR>/home1
/home +> /<VAR>site</VAR>/<VAR>host</VAR>/home2
...
</PRE>
<P>
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.
<H2><A NAME="SEC51" HREF="cfengine-Tutorial_toc.html#TOC51">Editing Files</A></H2>
<P>
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.
<P>
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.
<PRE>
editfiles:
{ /etc/inetd.conf
HashCommentLinesContaining "finger"
}
</PRE>
<P>
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) <SAMP>`#'</SAMP>, <SAMP>`%'</SAMP> as used in TeX and on AIX systems, and
C++-style <SAMP>`//'</SAMP>.
<P>
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 <SAMP>`# '</SAMP> and the
default comment-end string is the empty string. For instance, to define
C style comments you could write:
<PRE>
{ <VAR>file</VAR>
SetCommentStart "/* "
SetCommentEnd " */"
# Comment out all lines containing printf!
CommentLinesMatching ".*printf.*"
}
</PRE>
<P>
Other applications for these editing commands include monitoring and
controlling root-access to hosts by editing files such as <TT>`.rhosts'</TT>
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).
<P>
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 the with <CODE>home</CODE> pseudo-wildcard. If one writes
<PRE>
{ home/.cshrc
AppendIfNoSuchLine "# Sys admin/cfengine: put next line here"
AppendIfNoSuchLine "setenv PRINTER newprinter"
}
</PRE>
<P>
then the users' files are checked one-by-one for the given lines of
text, and edited if necessary.
<P>
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.
<P>
The behaviour of cfengine should not be confused with that of <EM>sed</EM>
or <EM>perl</EM>. 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:
<UL>
<LI>Load file into memory.
<LI>Is the size of the file within sensible user-definable limits?
If not, file could be binary, refuse to edit.
<LI>Check each editing command and count the number of edits made.
<LI>If number of edits is greater than zero, rename the old file
and save the edited version in its place. Inform about the edit.
<LI>If no edits are made, do nothing, say nothing.
</UL>
<P>
Equivalent one-line sed operations involve editing the same file
perhaps many times to achieve the same results--without the
safety checks in addition.
<H2><A NAME="SEC52" HREF="cfengine-Tutorial_toc.html#TOC52">Disabling and the file repository</A></H2>
<P>
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 <SAMP>`+'</SAMP> symbol in
the file <TT>`/etc/hosts.equiv'</TT>.
<A NAME="IDX209"></A>
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.
<PRE>
disable:
/etc/hosts.equiv
</PRE>
<P>
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 <TT>`/var/adm/wtmpx'</TT> and
<TT>`/var/lp/logs/lpsched'</TT>. Other files like <VAR>/var/adm/messages</VAR>
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
<A NAME="IDX210"></A>
<A NAME="IDX211"></A>
<PRE>
disable:
Sunday::
/var/lp/logs/lpsched rotate=3
</PRE>
<P>
Now, when cfengine is run, it renamed the file <TT>`lpsched'</TT> to
a file called <TT>`lpsched.1'</TT>. It also renames <TT>`lpsched.1'</TT>
as <TT>`lpsched.2'</TT> 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 <CODE>rotate=empty</CODE> and cfengine
will simply empty the log file.
<A NAME="IDX212"></A>
<A NAME="IDX213"></A>
<P>
When ever cfengine disables a file (<CODE>disable</CODE> or <CODE>links</CODE> with
the <SAMP>`!'</SAMP> operator), or saves a new file on top of an old one
(<CODE>copy</CODE> or <CODE>editfiles</CODE>), it makes a backup of the
original. Usually disabled files are renamed by appending the string
<TT>`.cfdisabled'</TT> the the filename; copied files are saved by appending
the string <TT>`.cfsaved'</TT>.
<A NAME="IDX214"></A>
<A NAME="IDX215"></A>
It is possible to switch off backup file
generation in the copy feature by setting the variable
<CODE>backup=false</CODE>, 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:
<PRE>
control:
repository = ( <VAR>directory-name</VAR> )
</PRE>
<P>
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.
<H2><A NAME="SEC53" HREF="cfengine-Tutorial_toc.html#TOC53">Running user scripts</A></H2>
<P>
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.
<PRE>
shellcommands:
myhost.Sunday::
"/usr/bin/find/updatedb"
</PRE>
<P>
Cfengine scripts can be passed variables using normal variable
substitution:
<PRE>
control:
cfbin = ( /local/gnu/lib/cfengine/bin )
backupdir = ( /iu/dax/backup )
shellcommands:
"$(cfbin)/cfbackup -p -f $(backupdir) -s /iu/nexus/u1"
</PRE>
<P>
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:
<UL>
<LI>
Pass the variable <CODE>$(allclasses)</CODE> to the script. This contains a
list of all classes in the form of a string
<PRE>
CFALLCLASSES=<VAR>class1</VAR>:<VAR>class2</VAR>:...
</PRE>
This variable always contains an up to date list of the defined
classes.
<LI>
Use the command line option <SAMP>`-u'</SAMP> or <SAMP>`--use-env'</SAMP>. When this
is defined, cfengine defines an internal environment variable
called <SAMP>`CFALLCLASSES'</SAMP> which contains the same list as above.
Unfortunately, system 5 boxes don't seem to like having to update
an environment variable continuously and tend to dump core, so
this is not the default behaviour!
</UL>
<P>
<H2><A NAME="SEC54" HREF="cfengine-Tutorial_toc.html#TOC54">Compressing old log files</A></H2>
<P>
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
<TT>`file.1'</TT>, <TT>`file.2'</TT>...<TT>`file.10'</TT> will match this wildcard
and the compression program sees that they get compressed. The output
is dumped to avoid spurious messages.
<PRE>
shellcommands:
"$(gnu)/gzip /var/log/*.[0-9] /var/log/*.[0-9][0-9] > /dev/null 2>&1"
</PRE>
<P>
Cfengine will also recognize rotated files if they have been compressed, with
suffixes <TT>`.Z'</TT>, <TT>`.gz'</TT>, <TT>`.rbz'</TT> or <TT>`.rbz'</TT>.
<P>
<H2><A NAME="SEC55" HREF="cfengine-Tutorial_toc.html#TOC55">Managing ACLs</A></H2>
<P>
<A NAME="IDX216"></A>
<A NAME="IDX217"></A>
<A NAME="IDX218"></A>
<P>
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.
<P>
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
<KBD>ls -l</KBD> 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 <SAMP>`chmod'</SAMP> thing. And
then they would say: so what's so great about this Unix then?
<P>
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.
<P>
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.
<P>
A cfengine bare-bones file-checking program looks like this:
<PRE>
#
# 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
</PRE>
<P>
<A NAME="IDX219"></A>
<A NAME="IDX220"></A>
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 <CODE>acl</CODE> directive. It
is a deceptively simply looking animal, but it hides a wealth of
complexity. The <CODE>zap</CODE> 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:
<PRE>
# ...contd
acl:
{ zap
method:append
fstype:solaris
user:rmz:rwx
user:len:r
}
</PRE>
<P>
As you can see, an ACL is a compound object--a bundle of information
which specifies which users have which permissions. Because ACLs are
<EM>lists</EM> 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.
<P>
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:
<PRE>
files:
$(HOME)/myfile acl=acl_alias1 action=fixall
acl:
{ acl_alias1
method:append
fstype:solaris
user:len:rwx
}
</PRE>
<P>
ACLs are viewed in Solaris with the command <SAMP>`getfacl'</SAMP>.
Suppose that, before running this program, our test-file had permissions
<PRE>
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
</PRE>
<P>
After the cfengine run, the ACL would become:
<PRE>
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
</PRE>
<P>
Suppose we wanted to to remove 'w' bit for user <SAMP>`jacobs'</SAMP>, or make sure
that it was never there.
<PRE>
{ acl_alias1
method:append
fstype:solaris
user:jacobs:-w
}
</PRE>
<P>
Note that the method used here is append. That means that, whatever other
access permissions we might have granted on this file, the user <SAMP>`jacobs'</SAMP>
(a known cracker) will have no write permissions on the file. Had we
used the method <CODE>overwrite</CODE> above, we would have eliminated all
other access permissions for every user and added the above.
If we really wanted to burn <SAMP>`jacobs'</SAMP>, we could remove all rights to
the file like this
<PRE>
user:jacobs:noaccess
</PRE>
<P>
The keyword <CODE>noaccess</CODE> removes all bits. Note that this is not
necessarily the same as doing a <CODE>-rwx</CODE>, since some filesystems,
like DFS, have more bits than this. Then, if we want to forgive and forget,
the ACLs may be removed for <CODE>jacobs</CODE> with the syntax
<PRE>
user:jacobs:default
</PRE>
<P>
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.
<A NAME="IDX221"></A>
<P>
DFS ACLs look a little different. They are examined with the
<SAMP>`acl_edit'</SAMP> command or with
<A NAME="IDX222"></A>
<PRE>
dcecp -c acl show <filename>
</PRE>
<P>
In order to effect changes to the DFS, you have to perform a DCE login
to obtain authentication cookies. The user <SAMP>`cell_admin'</SAMP> is a
special user account for administrating a local DFS cell. Suppose we
have a file with the following DCE ACL:
<PRE>
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---
</PRE>
<P>
Now we want to add <SAMP>`wx'</SAMP> permissions for user
<SAMP>`cell_admin'</SAMP>, and add new entries with <SAMP>`rx'</SAMP> permissons
for group <CODE>acct-admin</CODE> and user <SAMP>`root'</SAMP>. This is done with the
following ACL alias:
<PRE>
{ 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
}
</PRE>
<P>
The local cell name <TT>`/.../iu.hioslo.no'</TT> 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:
<PRE>
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---
</PRE>
<P>
For the sake of simplicity we have only used standard Unix
bits <SAMP>`rwx'</SAMP> here, but more complicated examples may be found
in DFS. For example,
<PRE>
user:mark:+rwx,-cid
</PRE>
<P>
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.
<P>
The objects referred to in DFS as <CODE>user_obj</CODE>, <CODE>group_obj</CODE>
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 <SAMP>`_obj'</SAMP> suffices. A user field of <SAMP>`*'</SAMP> is a simple
abbreviation for the owner of the file.
<P>
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.
<H1><A NAME="SEC56" HREF="cfengine-Tutorial_toc.html#TOC56">Using cfengine as a front end for <CODE>cron</CODE></A></H1>
<P>
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 <CODE>editfiles</CODE> 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:
<UL>
<LI>
It is easier to keep track of what cron jobs are running on the
system when you have everything in one place.
<LI>
You can use all of your carefully crafted groups and user-defined
classes to identify which host should run which programs.
</UL>
<P>
<A NAME="IDX223"></A>
<P>
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 <CODE>cron</CODE>'s
time specification possibilities, so this does not restrict you
in any way, See section <A HREF="cfengine-Tutorial.html#SEC59">Building flexible time classes</A>. The only price
is the overhead of parsing the cfengine configuration file.
<A NAME="IDX224"></A>
<P>
To be more concrete, imagine installing the following <TT>`crontab'</TT>
file onto every host on your network:
<PRE>
#
# Global Cron file
#
0,15,30,45 * * * * /usr/local/cfengine/inputs/run-cfengine
</PRE>
<P>
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 <TT>`run-cfengine'</TT> as the `scheduling interval'
and discuss its implications in more detail below.
<P>
<A NAME="IDX225"></A>
The script <TT>`run-cfengine'</TT> would replace any <TT>`cfdaily'</TT> or
<TT>`cfhourly'</TT> scripts which you might have, and can as simple as this
<PRE>
#!/bin/sh
#
# Script run-cfengine
export CFINPUTS=/usr/local/cfengine/inputs
/usr/local/gnu/bin/cfengine
#
# Should we pipe mail to a special user?
#
</PRE>
<P>
or it could be more fancy. You could also use the <TT>`cfwrap'</TT> 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 <CODE>sysadm</CODE> in the
Reference manual).
<PRE>
#
# Global Cron file
#
0,15,30,45 * * * * <VAR>path</VAR>/cfwrap <VAR>path</VAR>/run-cfengine
</PRE>
<P>
You might not want to run your entire system configuration
<TT>`cfengine.conf'</TT> every time cron fires up cfengine. An alternative
would be to keep a separate fil for cron jobs called, say,
<TT>`cf.cron'</TT>. You would then replace the <TT>`run-cfengine'</TT>
file by
<PRE>
#!/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?
#
</PRE>
<P>
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 <TT>`cf.cron'</TT> 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.
<H2><A NAME="SEC57" HREF="cfengine-Tutorial_toc.html#TOC57">Structuring <TT>`cfengine.conf'</TT></A></H2>
<P>
The structure of <TT>`cfengine.conf'</TT> 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:
<UL>
<LI>
By placing individual actions under classes which restrict the times at
which they are executed,
<PRE>
<VAR>action</VAR>:
Hr00.Min10_15||Hr12.Min45_55::
<VAR>Command</VAR>
</PRE>
<LI>
By choosing a different <CODE>actionsequence</CODE> depending on the
time of day.
<PRE>
control:
Hr00:: # Action-sequence for daily run at midnight
actionsequence = ( <VAR>sequence</VAR> )
!Hr00:: # Action-sequence otherwise
actionsequence = ( <VAR>sequence</VAR> )
</PRE>
<LI>
By importing modules based on time classes.
<PRE>
import:
Hr00:: cf.dailyjobs
any:: cf.hourlyjobs
</PRE>
</UL>
<P>
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.
<H2><A NAME="SEC58" HREF="cfengine-Tutorial_toc.html#TOC58">Splaying host times</A></H2>
<P>
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:
<PRE>
control:
SplayTime = ( 60 ) # minutes
</PRE>
<P>
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.
<A NAME="IDX226"></A>
<A NAME="IDX227"></A>
<A NAME="IDX228"></A>
<P>
Splaying can be switched off temporarily with the <SAMP>`-q'</SAMP> or <SAMP>`--no-splay'</SAMP>
options.
<H2><A NAME="SEC59" HREF="cfengine-Tutorial_toc.html#TOC59">Building flexible time classes</A></H2>
<P>
<A NAME="IDX229"></A>
<A NAME="IDX230"></A>
<A NAME="IDX231"></A>
Each time cfengine is run, it reads the system clock and defines the
following classes based on the time and date:
<DL COMPACT>
<DT><CODE>Yr<VAR>xx</VAR>::</CODE>
<DD>
The current year, e.g. <SAMP>`Yr1997'</SAMP>, <SAMP>`Yr2001'</SAMP>. 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!
<A NAME="IDX232"></A>
<DT><CODE><VAR>Month</VAR>::</CODE>
<DD>
The current month can be used for defining very long term variations in
the system configuration, e.g. <SAMP>`January'</SAMP>, <SAMP>`February'</SAMP>. 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.
<A NAME="IDX233"></A>
<DT><CODE><VAR>Day</VAR>::</CODE>
<DD>
The day of the week may be used as a class, e.g. <SAMP>`Monday'</SAMP>, <SAMP>`Sunday'</SAMP>.
<A NAME="IDX234"></A>
<DT><CODE>Day<VAR>xx</VAR>::</CODE>
<DD>
A day in the month (date) may be used to single out by date, e.g. the first
day of each month defines <SAMP>`Day1'</SAMP>, the 21st <SAMP>`Day21'</SAMP> etc.
<DT><CODE>Hr<VAR>xx</VAR>::</CODE>
<DD>
An hour of the day, in 24-hour clock notation: <SAMP>`Hr00'</SAMP>...<SAMP>`Hr23'</SAMP>.
<DT><CODE>Min<VAR>xx</VAR>::</CODE>
<DD>
The precise minute a which cfengine was started: <SAMP>`Min0'</SAMP> ... <SAMP>`Min59'</SAMP>.
This is probably not useful alone, but these values may be combined
to define arbitrary intervals of time.
<DT><CODE>Min<VAR>xx</VAR>_<VAR>xx</VAR>::</CODE>
<DD>
The five-minute interval in the hour at which cfengine was executed, in the form
<SAMP>`Min0_5'</SAMP>, <SAMP>`Min5_10'</SAMP> .. <SAMP>`Min55_0'</SAMP>.
</DL>
<P>
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 <CODE>group</CODE> or <CODE>classes</CODE>
action to create an alias for a group of time values.
<A NAME="IDX235"></A>
<A NAME="IDX236"></A>
Here are some creative examples:
<PRE>
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)
</PRE>
<P>
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 an excellent and readable way of
pinpointing intervals of time within a program, without having to
use <SAMP>`|'</SAMP> and <SAMP>`.'</SAMP> operators everywhere.
<H2><A NAME="SEC60" HREF="cfengine-Tutorial_toc.html#TOC60">Choosing a scheduling interval</A></H2>
<P>
How often should you call your global cron script? There are several
things to think about:
<UL>
<LI>
How much fine control do you need? Running cron jobs once each hour is
usually enough for most tasks, but you might need to exercise finer
control for a few special tasks.
<LI>
Are you going to run the entire cfengine configuration file
or a special light-weight file?
<LI>
System latency. How long will it take to load, parse and run the
cfengine script?
</UL>
<P>
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 <A HREF="cfengine-Tutorial.html#SEC67">Spamming and security</A>.
<H1><A NAME="SEC61" HREF="cfengine-Tutorial_toc.html#TOC61">Cfengine and network services</A></H1>
<P>
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 <CODE>rsh</CODE> protocols.
<H2><A NAME="SEC62" HREF="cfengine-Tutorial_toc.html#TOC62">Cfengine network services</A></H2>
<P>
By starting the daemon called <CODE>cfd</CODE>, 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.
<A NAME="IDX237"></A>
<A NAME="IDX238"></A>
<A NAME="IDX239"></A>
Cfengine network services are built around the following components:
<DL COMPACT>
<DT><CODE>cfengine</CODE>
<DD>
The configuration engine, whose only contact with the netork is via
remote copy requests. This component does the hard work of configuring
the system based on rules specified in the file <TT>`cfengine.conf'</TT>. It
does not and cannot grant any access to a system from the network.
<A NAME="IDX240"></A>
<DT><CODE>cfd</CODE>
<DD>
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 <TT>`cfd.conf'</TT>.
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.
<A NAME="IDX241"></A>
<DT><CODE>cfrun</CODE>
<DD>
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.
<DT><CODE>cfwatch</CODE>
<DD>
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.
</DL>
<P>
With these components you can emulate programs like <CODE>rdist</CODE>
<A NAME="IDX242"></A>
<A NAME="IDX243"></A>
<A NAME="IDX244"></A>
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.
<H2><A NAME="SEC63" HREF="cfengine-Tutorial_toc.html#TOC63">How it works</A></H2>
<H3><A NAME="SEC64" HREF="cfengine-Tutorial_toc.html#TOC64">Remote file distribution</A></H3>
<P>
This section describes how you can set up <CODE>cfd</CODE> 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.
<P>
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 <CODE>rdist</CODE> 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.
<P>
Also, in contrast to programs like <CODE>rdist</CODE> which distribute files
over many hosts, cfengine does not require any general <CODE>root</CODE>
access to a system using the <TT>`.rhosts'</TT> file or the
<TT>`/etc/hosts.equiv'</TT> file. It is sufficient to run the daemon as
root. You can not run it by adding it to the <TT>`/etc/inetd.conf'</TT>
file on your system however.
<A NAME="IDX245"></A>
The restricted functionality of the daemon protects your system from
attempts to execute general commands as the root user using <CODE>rsh</CODE>.
<P>
To remotely access files on a server, you add the keywork <CODE>server=<VAR>host</VAR></CODE>
<A NAME="IDX246"></A>
to a copy command. Consider the following example
which illustrates how you might distribute a password file from a masterhost
to some clients.
<PRE>
copy:
PasswdClients::
/etc/passwd dest=/etc/passwd owner=root group=0 server=<VAR>server-host</VAR>
</PRE>
<P>
Given that the <CODE>cfd</CODE> daemon is running on <VAR>server-host</VAR>, 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.
<A NAME="IDX247"></A>
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 <TT>`.cfnew'</TT>.
<A NAME="IDX248"></A>
Only when the file has been successfully collected will cfengine make a
copy of the old file, (see <CODE>repository</CODE> 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.
<P>
Cfengine places a timeout of a few seconds on network connections to
avoid hanging processes.
<P>
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 <CODE>cfrun</CODE> which simply asks the
<A NAME="IDX249"></A>
host running the daemon to run the cfengine program locally.
<P>
<EM>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.</EM>
<H3><A NAME="SEC65" HREF="cfengine-Tutorial_toc.html#TOC65">Remote execution of cfengine</A></H3>
<P>
<A NAME="IDX250"></A>
It is a good idea to execute cfengine by getting <CODE>cron</CODE> 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:
<PRE>
myhost% cfrun <VAR>remote-host</VAR> -v
<VAR>output....</VAR>
</PRE>
<P>
A simple user interface is provided to accomplish this. <CODE>cfrun</CODE>
makes a connection to a remote cfd-daemon
<A NAME="IDX251"></A>
<A NAME="IDX252"></A>
<A NAME="IDX253"></A>
and executes cfengine on that system with the privileges of the
cfd-daemon (usually <CODE>root</CODE>). This has a two advantages:
<UL>
<LI>
You avoid having to log in on a remote host in order to reconfigure
it.
<LI>
Users other than root can run cfengine to fix any problems with
the system.
</UL>
<P>
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 <A HREF="cfengine-Tutorial.html#SEC67">Spamming and security</A>.
<H3><A NAME="SEC66" HREF="cfengine-Tutorial_toc.html#TOC66"><CODE>cfrun</CODE></A></H3>
<P>
The syntax of the <CODE>cfrun</CODE> command is
<PRE>
cfrun -<VAR>option</VAR> --<VAR>longoption</VAR> <VAR>class1</VAR> <VAR>class2 ...</VAR>
</PRE>
<P>
With the exception of the <SAMP>`-d'</SAMP> and <SAMP>`-S'</SAMP> options, all options are passed
<A NAME="IDX254"></A>
<A NAME="IDX255"></A>
on to the remote hosts and are ignored locally. The <SAMP>`-q'</SAMP> 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 <SAMP>`-Dnewclass'</SAMP>, 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.
<A NAME="IDX256"></A>
<P>
Each host evaluates the classes sent by <CODE>cfrun</CODE>
and decides whether cfengine should be invoked.
<A NAME="IDX257"></A>
Only hosts which belong to the classes defined on the <CODE>cfrun</CODE>
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.
<P>
<CODE>cfrun</CODE> uses a configuration file which is located under the
<CODE>CFINPUTS</CODE> 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.
<A NAME="IDX258"></A>
<P>
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 <CODE>cfrun</CODE>, 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 <CODE>cfrun</CODE> command. The format of the file
is as follows
<PRE>
#
# Comment ..
#
domain=<VAR>my.domain</VAR>
access=<VAR>user1</VAR>,<VAR>user2</VAR>
<VAR>hostname1</VAR> <VAR>options</VAR>
<VAR>hostname2</VAR> <VAR>options</VAR>
...
</PRE>
<P>
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:
<PRE>
funny.domain -i # problem host
</PRE>
<P>
<A NAME="IDX259"></A>
<A NAME="IDX260"></A>
You could use <CODE>cfrun</CODE> 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.
<H3><A NAME="SEC67" HREF="cfengine-Tutorial_toc.html#TOC67">Spamming and security</A></H3>
<P>
The term `spamming' refers to the senseless repetition of something in a
malicious way intended to drive someone crazy<A NAME="DOCF5" HREF="cfengine-Tutorial_foot.html#FOOT5">(5)</A>. In the computer world some
malicious users, a bit like `flashers' in the park<A NAME="DOCF6" HREF="cfengine-Tutorial_foot.html#FOOT6">(6)</A> 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<A NAME="DOCF7" HREF="cfengine-Tutorial_foot.html#FOOT7">(7)</A>.
<P>
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.
<P>
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:
<UL>
<LI>
Restricting cfengine access to root would prevent regular users,
in trouble, from being able to fix problems when the system
administrator was unavailable. A time-based lock does not
prevent this kind of freedom.
<LI>
Accidents with cron or shell scripts could start cfengine
more often than desirable. We also need to protect against
such accidents.
<LI>
We can prevent malicious attacks regardless of whom they may
come from.
</UL>
<P>
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:
<UL>
<LI>
The minimum time which should have passed since the last time
that action was executed. It will not be executed again until
this amount of time has elapsed. (Default time is 0 minutes so
that users un-aware of this feature will not be confused by it.)
<LI>
The maximum amount of time cfengine should wait for an old
instantiation of cfengine to finish before killing it
and starting again. (Default time is 120 minutes.)
</UL>
<P>
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 <EM>minutes</EM>.
<PRE>
actionsequence
(
action.IfElapsed<VAR>time-in-mins</VAR>
action.ExpireAfter<VAR>time-in-mins</VAR>
)
</PRE>
<P>
or globally,
<PRE>
control:
IfElapsed = ( <VAR>time-in-mins</VAR> )
ExpireAfter = ( <VAR>time-in-mins</VAR> )
</PRE>
<P>
For example:
<PRE>
control:
actionsequence =
(
files.IfElapsed240.ExpireAfter180
copy
tidy
)
IfElapsed = ( 30 )
</PRE>
<P>
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.
<P>
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.
<P>
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.
<A NAME="IDX261"></A>
<A NAME="IDX262"></A>
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:
<DL COMPACT>
<DT><CODE>copy, editfiles, shellcommands</CODE>
<DD>
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.
<DT><CODE>netconfig, resolve, umount, mailcheck, addmounts, disable, processes</CODE>
<DD>
All commands of this action-type are locked simultaneously,
since they can lead to contention.
<DT><CODE>mountall, mountinfo, required, checktimezone</CODE>
<DD>
These are not locked at all.
</DL>
<P>
<A NAME="IDX263"></A>
<A NAME="IDX264"></A>
Cfengine creates a directory <TT>`~/.cfengine'</TT> for writing lock files
for ordinary users.
<P>
The option <SAMP>`-K'</SAMP> or <SAMP>`--no-lock'</SAMP> can be used to switch off the
locking checks, but note that when running cfengine remotely via <CODE>cfd</CODE>,
this is not possible.
<H3><A NAME="SEC68" HREF="cfengine-Tutorial_toc.html#TOC68">Some points on the cfd protocol</A></H3>
<P>
Cfd 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.
<P>
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.
<H3><A NAME="SEC69" HREF="cfengine-Tutorial_toc.html#TOC69">Deadlocks and runaway loops</A></H3>
<P>
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.
<A NAME="IDX265"></A>
<A NAME="IDX266"></A>
<P>
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 <CODE>IfElapsed</CODE> time
or the <CODE>ExpireAfter</CODE> time to zero.
<A NAME="IDX267"></A>
<A NAME="IDX268"></A>
In general, if you wish to avoid problems like this, you
should not disable the locking mechanism by setting these two
times to zero.
<P>
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
<CODE>server=</CODE> directive in a copy with `localhost' to avoid unnecessary
network connections.
<A NAME="IDX269"></A>
<A NAME="IDX270"></A>
The prevents one kind of deadlock which could occur: namely cfrun
executes cfengine on host A (cfd 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 cfd
to unblock, but this would be impossible since cfd cannot unblock until
it has the file. By avoiding remote copies to localhost, this possibility
is avoided.
<H2><A NAME="SEC70" HREF="cfengine-Tutorial_toc.html#TOC70">Configuring <CODE>cfd</CODE></A></H2>
<H3><A NAME="SEC71" HREF="cfengine-Tutorial_toc.html#TOC71">Installation of <CODE>cfd</CODE></A></H3>
<P>
To install the cfengine daemon component, you will need to register a
port for cfengine by adding the following line to the system file
<TT>`/etc/services file'</TT>
<PRE>
cfengine 5308/tcp
</PRE>
<P>
You could do this for all hosts by adding the following to your
cfengine configuration
<PRE>
editfiles:
{ /etc/services
AppendIfNoSuchLine "cfengine 5308/tcp"
}
</PRE>
<P>
To start cfengine at boot time, you need to place a line
of the following type in your system startup files:
<PRE>
# Start cfengine server
cfd
</PRE>
<P>
Note that <CODE>cfd</CODE> 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.
<A NAME="IDX271"></A>
<A NAME="IDX272"></A>
<A NAME="IDX273"></A>
<H3><A NAME="SEC72" HREF="cfengine-Tutorial_toc.html#TOC72">Configuration file <TT>`cfd.conf'</TT></A></H3>
<P>
The server daemon is controlled by a file called
<TT>`cfd.conf'</TT>.
<A NAME="IDX274"></A>
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.
<P>
Though they are not compatible, <TT>`cfengine.conf'</TT> and <TT>`cfd.conf'</TT>
are similar in several ways:
<UL>
<LI>
Both files use classes to label entries, so that you may use
the same configuration file to control all hosts on your network. This
is a convenience which saves you the trouble of maintaining many
different files.
<LI>
Both files are searched for using the contents of the variable
<CODE>CFINPUTS</CODE>.
<A NAME="IDX275"></A>
<LI>
You can use <CODE>groups</CODE> and <CODE>import</CODE> in both files
to break up files into convenient modules and to import
common resources, such as lists of groups.
</UL>
<P>
Note that the classes in the <TT>`cfd.conf'</TT> 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.
<P>
Host name authentication is not by class or group but by hostname, like
the <TT>`/etc/exports'</TT> file on most unix systems. The syntax for the
file is as follows:
<PRE>
control:
<VAR>classes</VAR>::
domain = ( <VAR>DNS-domain-name</VAR> )
cfrunCommand = ( "<VAR>script/filename</VAR>" ) # Quoted
AutoExecCommand = ( "<VAR>cfengine-start-script</VAR>" )
AutoExecInterval = ( 60 )
MaxConnections = ( <VAR>maximum number of forked daemons</VAR> )
ChecksumDatabase = ( <VAR>filename</VAR> )
IfElapsed = ( <VAR>time-in-minutes</VAR> )
DenyBadClocks = ( <VAR>false</VAR> )
AllowConnectionsFrom = ( <VAR>IP numbers</VAR> )
DenyConnectionsFrom = ( <VAR>IP numbers</VAR> )
MultipleConnections = ( <VAR>false/true</VAR> )
LogAllConnections = ( <VAR>false/true</VAR> )
groups:
<VAR>Group definitions</VAR>
import:
<VAR>Files to import</VAR>
admit: | grant:
<VAR>classes</VAR>::
/<VAR>file-or-directory</VAR>
<VAR>wildcards/hostnames</VAR>
deny:
<VAR>classes</VAR>::
/<VAR>file-or-directory</VAR>
<VAR>wildcards/hostnames</VAR> root=<VAR>hostlist</VAR> secure=<VAR>true/on</VAR>
</PRE>
<P>
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.
<DL COMPACT>
<DT><CODE>cfrunCommand</CODE>
<DD>
This string is the command which you would like to be executed
remotely by the <CODE>cfrun</CODE> command.
<A NAME="IDX276"></A>
<DT><CODE>AutoExecCommand</CODE>
<DD>
This is the name of a command which you use to execute cfengine
automatically after the interval specified in <CODE>AutoExecInterval</CODE>.
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.
<DT><CODE>AutoExecInterval</CODE>
<DD>
A number of minutes after which you would like cfengine to be
run, even if you do not force a run with <KBD>cfrun</KBD>. This can
be used instead of, or in addition to cron. If used with cron,
take take to set suitable values for <CODE>IfElapsed</CODE> so that
unnecessary overlap is avoided.
<A NAME="IDX277"></A>
<DT><CODE>MaxConnections</CODE>
<DD>
This integer value sets a limit on the maximum number of
child daemon threads which cfd will `fork' in order
to handle remote requests. The default value is ten.
<DT><CODE>IfElapsed</CODE>
<DD>
The <CODE>IfElapsed</CODE> anti-spamming filter is also built into
<CODE>cfd</CODE> 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.
<A NAME="IDX278"></A>
<DT><CODE>ChecksumDatabase</CODE>
<DD>
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 <SAMP>`libdb'</SAMP> 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.
<A NAME="IDX279"></A>
<A NAME="IDX280"></A>
<A NAME="IDX281"></A>
<DT><CODE>DenyBadClocks</CODE>
<DD>
If this is set to <CODE>off</CODE>, cfd 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.
<A NAME="IDX282"></A>
<A NAME="IDX283"></A>
<DT><CODE>AllowConnectionsFrom</CODE>
<DD>
This variable allows a list
of numerical IP masks to be specified, which cfd 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.
<PRE>
control:
AllowConnectionsFrom = ( 128.39.89 192.2.0.10 )
</PRE>
<A NAME="IDX284"></A>
<A NAME="IDX285"></A>
<A NAME="IDX286"></A>
<DT><CODE>DenyConnectionsFrom</CODE>
<DD>
Hosts which are included by the allow-list above can be explicitly
denied access using this list.
<PRE>
control:
DenyConnectionsFrom = ( 128.39.89.76 ) # rogue host
</PRE>
<A NAME="IDX287"></A>
<DT><CODE>MultipleConnections</CODE>
<DD>
This variable defaults to "false" or "off". If true, only one connection
per host is allowed. This can be used to help prevent denial of service
attacks (spamming).
<DT><CODE>LogAllConnections</CODE>
<DD>
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.
<DT><CODE><CODE>root=</CODE></CODE>
<DD>
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: cfd trusts the DNS service, so be aware that
cache poisoning attacks are a possible way of bypassing access controls.
<DT><CODE><CODE>secure=true</CODE></CODE>
<DD>
If this option is set, cfd will only serve the named files
if the copy access type is <CODE>secure</CODE>, i.e. on an encrypted
link. This presupposes that cfengine has been compiled with
a working DES or SSLeay library.
</DL>
<P>
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 cfd does not follow
symbolic links and give access to files in other directories.
<P>
Fully qualified hostnames should be given in this file. Do not forget to
define the domain name. Authentication calls the unix function
<CODE>gethostbyname()</CODE> 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.
<P>
Here is an example file
<PRE>
#####################################################
#
# This is a cfd 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
</PRE>
<P>
<EM>NOTE I: cfd is not <CODE>rpc.mountd</CODE>, 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.</EM>
<P>
<B>NOTE II: access control is per host and per user. User names are assumed
to be common o 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.</B>
<P>
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 <TT>`/etc/hosts.access'</TT> and
<TT>`/etc/hosts.deny'</TT>.
<A NAME="IDX288"></A>
<A NAME="IDX289"></A>
<A NAME="IDX290"></A>
<A NAME="IDX291"></A>
<P>
<A NAME="IDX292"></A>
<H3><A NAME="SEC73" HREF="cfengine-Tutorial_toc.html#TOC73">TCP wrappers</A></H3>
<P>
Cfengine tries to incorporate the TCP wrappers package if you have it on
your system. If you do, then the files <TT>`/etc/hosts.allow'</TT> and
<TT>`/etc/hosts.deny'</TT> allow you to give the cfengine/cfd service an extra
level of protection from `clever' spoofing attempts.
<H1><A NAME="SEC74" HREF="cfengine-Tutorial_toc.html#TOC74">Security and cfengine</A></H1>
<H2><A NAME="SEC75" HREF="cfengine-Tutorial_toc.html#TOC75">Security hints</A></H2>
<P>
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.
<DL COMPACT>
<DT><EM>CERT advisories</EM>
<DD>
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.
<A NAME="IDX293"></A>
<A NAME="IDX294"></A>
<DT><EM>disabling binaries</EM>
<DD>
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.
<DT><EM>The setuid log</EM>
<DD>
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 <CODE>files</CODE> feature, it will make
a note of setuid programs it finds there. These are recorded in the
file <TT>`cfengine.<VAR>host</VAR>.log'</TT> which is stored under <TT>`/etc/cfengine'</TT> or
<TT>`/var/log/cfengine'</TT>.
<A NAME="IDX295"></A>
<A NAME="IDX296"></A>
<A NAME="IDX297"></A>
When new setuid programs are discovered, a warning is printed, but only
if you are <EM>root</EM>. 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.
<A NAME="IDX298"></A>
<DT><EM><CODE>ChecksumDatabase</CODE></EM>
<DD>
<A NAME="IDX299"></A>
<A NAME="IDX300"></A>
In <CODE>files</CODE> you can set the option <CODE>checksum=md5</CODE> which
which 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.
<A NAME="IDX301"></A>
<DT><EM>Suspicious filenames</EM>
<DD>
Whenever cfengine opens a directory and scans through files
(<CODE>files</CODE>, <CODE>tidy</CODE>, <CODE>copy</CODE>), it is on the lookout for for
suspicious filenames, i.e. files like <TT>`.. .'</TT> 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 <CODE>FileExtensions</CODE>
may be used to detect concealed directories during these searches,
if
users create directories which look like common files.
<A NAME="IDX302"></A>
<DT><EM>Spoofing</EM>
<DD>
Spoofing refers to attempts to masquerade as another host when sending
network transmissions. The <CODE>cfd</CODE> 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)
<A NAME="IDX303"></A>
<A NAME="IDX304"></A>
then cfd will attempt to use it to detect other spoofs too, See section <A HREF="cfengine-Tutorial.html#SEC73">TCP wrappers</A>. If you don't have TCP wrappers, then the only line of
defense is the double reverse lookup.
<DT><EM>Race conditions in file copying</EM>
<DD>
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 <TT>`.cfnew'</TT>) 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.
<A NAME="IDX305"></A>
<A NAME="IDX306"></A>
<A NAME="IDX307"></A>
<DT><EM><CODE>size=</CODE> in copy</EM>
<DD>
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.
<DT><EM><CODE>useshell=</CODE> in shellcommands</EM>
<DD>
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 <SAMP>`/bin/sh -c'</SAMP> 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 <CODE>IFS</CODE>
variable to treat '/' as a separator. You can ask cfengine to start
programs directly, without involving an intermediary shell, by setting
the <CODE>useshell</CODE> variable to false. The disadvantage is that you will
not be able to use shell directives such as <SAMP>`|'</SAMP> and <CODE>></CODE> in
your commands.
<A NAME="IDX308"></A>
<A NAME="IDX309"></A>
<A NAME="IDX310"></A>
<A NAME="IDX311"></A>
<DT><EM><CODE>warnnonusermail</CODE> and <CODE>warnnonownermail</CODE> in control</EM>
<DD>
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.
<A NAME="IDX312"></A>
<A NAME="IDX313"></A>
<A NAME="IDX314"></A>
<DT><EM>Using cfengine to restart daemons</EM>
<DD>
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.
<A NAME="IDX315"></A>
<A NAME="IDX316"></A>
</DL>
<H2><A NAME="SEC76" HREF="cfengine-Tutorial_toc.html#TOC76">Checksum Databases</A></H2>
<P>
<A NAME="IDX317"></A>
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,
<PRE>
control:
ChecksumDatabase = ( /etc/cfengine/cache.db )
files:
/<VAR>filename</VAR> checksum=md5 ....
</PRE>
<P>
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.
<P>
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 <CODE>copy</CODE> 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!
<P>
The control variable <CODE>ChecksumUpdates</CODE> may be switched to <CODE>on</CODE>
in order to force cfengine to update its checksum database after
warning of a change.
<A NAME="IDX318"></A>
<A NAME="IDX319"></A>
The default value of this variable is off for cfengine but on for cfd.
This is because cfd uses a database as a cache, while cfengine uses
it as a security check.
<H2><A NAME="SEC77" HREF="cfengine-Tutorial_toc.html#TOC77">Who do you trust?</A></H2>
<P>
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.
<A NAME="IDX320"></A>
<P>
For example, it would be an extremely foolish idea to copy a binary
program such as <TT>`/bin/ps'</TT> from a host you know nothing about.
This program runs as root. If someone were to replace that version
of <TT>`ps'</TT> with a trojan horse command, you would have effectively
opened your system to attack.
<P>
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 <EM>nobody</EM>.
<P>
Cfengine performs no cryptographic coding of messages at present, so if
you are sending sensitive data via cfengine, it should be coded in
advance.
<H2><A NAME="SEC78" HREF="cfengine-Tutorial_toc.html#TOC78">Firewalls</A></H2>
<P>
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.
<H1><A NAME="SEC79" HREF="cfengine-Tutorial_toc.html#TOC79">Variable Index</A></H1>
<P>
Jump to:
<A HREF="#vindex_!">!</A>
-
<A HREF="#vindex_"">"</A>
-
<A HREF="#vindex_$">$</A>
-
<A HREF="#vindex_'">'</A>
-
<A HREF="#vindex_-">-</A>
-
<A HREF="#vindex_/">/</A>
-
<A HREF="#vindex_`">`</A>
-
<A HREF="#vindex_a">a</A>
-
<A HREF="#vindex_b">b</A>
-
<A HREF="#vindex_c">c</A>
-
<A HREF="#vindex_d">d</A>
-
<A HREF="#vindex_e">e</A>
-
<A HREF="#vindex_f">f</A>
-
<A HREF="#vindex_h">h</A>
-
<A HREF="#vindex_i">i</A>
-
<A HREF="#vindex_m">m</A>
-
<A HREF="#vindex_o">o</A>
-
<A HREF="#vindex_r">r</A>
-
<A HREF="#vindex_s">s</A>
-
<A HREF="#vindex_t">t</A>
-
<A HREF="#vindex_u">u</A>
<P>
<H2><A NAME="vindex_!">!</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX54">!</A>
</DIR>
<H2><A NAME="vindex_"">"</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX161">"</A>
</DIR>
<H2><A NAME="vindex_$">$</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX82">$(arch)</A>
<LI><A HREF="cfengine-Tutorial.html#IDX83">$(binserver)</A>
<LI><A HREF="cfengine-Tutorial.html#IDX84">$(class)</A>
<LI><A HREF="cfengine-Tutorial.html#IDX105">$(cr)</A>
<LI><A HREF="cfengine-Tutorial.html#IDX85">$(date)</A>
<LI><A HREF="cfengine-Tutorial.html#IDX106">$(dblquote)</A>
<LI><A HREF="cfengine-Tutorial.html#IDX107">$(dollar)</A>
<LI><A HREF="cfengine-Tutorial.html#IDX86">$(domain)</A>
<LI><A HREF="cfengine-Tutorial.html#IDX87">$(faculty)</A>
<LI><A HREF="cfengine-Tutorial.html#IDX88">$(fqhost)</A>
<LI><A HREF="cfengine-Tutorial.html#IDX89">$(host)</A>
<LI><A HREF="cfengine-Tutorial.html#IDX90">$(ipaddress)</A>
<LI><A HREF="cfengine-Tutorial.html#IDX108">$(lf)</A>
<LI><A HREF="cfengine-Tutorial.html#IDX109">$(n)</A>
<LI><A HREF="cfengine-Tutorial.html#IDX110">$(quote)</A>
<LI><A HREF="cfengine-Tutorial.html#IDX94">$(site)</A>
<LI><A HREF="cfengine-Tutorial.html#IDX111">$(spc)</A>
<LI><A HREF="cfengine-Tutorial.html#IDX96">$(sysadm)</A>
<LI><A HREF="cfengine-Tutorial.html#IDX112">$(tab)</A>
<LI><A HREF="cfengine-Tutorial.html#IDX97">$(timezone)</A>
<LI><A HREF="cfengine-Tutorial.html#IDX104">$(year)</A>
</DIR>
<H2><A NAME="vindex_'">'</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX162">'</A>
</DIR>
<H2><A NAME="vindex_-">-</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX114">-a option</A>
<LI><A HREF="cfengine-Tutorial.html#IDX50">-D option</A>
<LI><A HREF="cfengine-Tutorial.html#IDX32">-f option</A>, <A HREF="cfengine-Tutorial.html#IDX38">-f option</A>
<LI><A HREF="cfengine-Tutorial.html#IDX36">-h option</A>
<LI><A HREF="cfengine-Tutorial.html#IDX31">-n option</A>
<LI><A HREF="cfengine-Tutorial.html#IDX49">-N option</A>, <A HREF="cfengine-Tutorial.html#IDX129">-N option</A>
<LI><A HREF="cfengine-Tutorial.html#IDX33">-v option</A>
</DIR>
<H2><A NAME="vindex_/">/</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX156">/etc/cfengine/cfengine.log</A>
<LI><A HREF="cfengine-Tutorial.html#IDX177">/etc/exports</A>
</DIR>
<H2><A NAME="vindex_`">`</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX163">`</A>
</DIR>
<H2><A NAME="vindex_a">a</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX219"><CODE>acl</CODE></A>
<LI><A HREF="cfengine-Tutorial.html#IDX126">any</A>
</DIR>
<H2><A NAME="vindex_b">b</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX68">binserver</A>, <A HREF="cfengine-Tutorial.html#IDX195">binserver</A>, <A HREF="cfengine-Tutorial.html#IDX198">binserver</A>
</DIR>
<H2><A NAME="vindex_c">c</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX79">CFALLCLASSES</A>
<LI><A HREF="cfengine-Tutorial.html#IDX300">ChecksumDatabase</A>
<LI><A HREF="cfengine-Tutorial.html#IDX319"><CODE>ChecksumUpdates</CODE></A>
</DIR>
<H2><A NAME="vindex_d">d</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX71">domain</A>
</DIR>
<H2><A NAME="vindex_e">e</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX150"><CODE>exclude=</CODE></A>
<LI><A HREF="cfengine-Tutorial.html#IDX77"><CODE>exec</CODE></A>
</DIR>
<H2><A NAME="vindex_f">f</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX67">faculty</A>
</DIR>
<H2><A NAME="vindex_h">h</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX69">host</A>
</DIR>
<H2><A NAME="vindex_i">i</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX149"><CODE>include=</CODE></A>
</DIR>
<H2><A NAME="vindex_m">m</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX91">MaxCfengines</A>
<LI><A HREF="cfengine-Tutorial.html#IDX125">moduledirectory</A>
</DIR>
<H2><A NAME="vindex_o">o</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX92">OutputPrefix</A>
</DIR>
<H2><A NAME="vindex_r">r</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX93">repchar</A>
</DIR>
<H2><A NAME="vindex_s">s</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX66">site</A>
<LI><A HREF="cfengine-Tutorial.html#IDX95">split</A>, <A HREF="cfengine-Tutorial.html#IDX168">split</A>
<LI><A HREF="cfengine-Tutorial.html#IDX72">sysadm</A>
</DIR>
<H2><A NAME="vindex_t">t</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX70">timezone</A>
</DIR>
<H2><A NAME="vindex_u">u</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX98">underscoreclasses</A>, <A HREF="cfengine-Tutorial.html#IDX103">underscoreclasses</A>
</DIR>
<H1><A NAME="SEC80" HREF="cfengine-Tutorial_toc.html#TOC80">Concept Index</A></H1>
<P>
Jump to:
<A HREF="#cindex_!">!</A>
-
<A HREF="#cindex_-">-</A>
-
<A HREF="#cindex_.">.</A>
-
<A HREF="#cindex_/">/</A>
-
<A HREF="#cindex_a">a</A>
-
<A HREF="#cindex_b">b</A>
-
<A HREF="#cindex_c">c</A>
-
<A HREF="#cindex_d">d</A>
-
<A HREF="#cindex_e">e</A>
-
<A HREF="#cindex_f">f</A>
-
<A HREF="#cindex_g">g</A>
-
<A HREF="#cindex_h">h</A>
-
<A HREF="#cindex_i">i</A>
-
<A HREF="#cindex_l">l</A>
-
<A HREF="#cindex_m">m</A>
-
<A HREF="#cindex_n">n</A>
-
<A HREF="#cindex_o">o</A>
-
<A HREF="#cindex_p">p</A>
-
<A HREF="#cindex_q">q</A>
-
<A HREF="#cindex_r">r</A>
-
<A HREF="#cindex_s">s</A>
-
<A HREF="#cindex_t">t</A>
-
<A HREF="#cindex_u">u</A>
-
<A HREF="#cindex_v">v</A>
-
<A HREF="#cindex_w">w</A>
-
<A HREF="#cindex_y">y</A>
<P>
<H2><A NAME="cindex_!">!</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX55">!</A>
</DIR>
<H2><A NAME="cindex_-">-</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX254">-d option in cfrun</A>
<LI><A HREF="cfengine-Tutorial.html#IDX35">-h option</A>
<LI><A HREF="cfengine-Tutorial.html#IDX130">-N option</A>
<LI><A HREF="cfengine-Tutorial.html#IDX255">-S option in cfrun</A>
</DIR>
<H2><A NAME="cindex_.">.</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX215"><TT>`.cfdisabled'</TT> files</A>
<LI><A HREF="cfengine-Tutorial.html#IDX153">.cfengine.rm</A>
<LI><A HREF="cfengine-Tutorial.html#IDX305">.cfnew</A>
<LI><A HREF="cfengine-Tutorial.html#IDX248"><TT>`.cfnew'</TT> files</A>
<LI><A HREF="cfengine-Tutorial.html#IDX214"><TT>`.cfsaved'</TT> files</A>
</DIR>
<H2><A NAME="cindex_/">/</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX310"><CODE>/bin/sh -c</CODE> problem.</A>
<LI><A HREF="cfengine-Tutorial.html#IDX295"><TT>`/etc/cfengine'</TT></A>
<LI><A HREF="cfengine-Tutorial.html#IDX154">/etc/cfengine/cfengine.log</A>
<LI><A HREF="cfengine-Tutorial.html#IDX209"><TT>`/etc/hosts.equiv'</TT></A>
<LI><A HREF="cfengine-Tutorial.html#IDX245"><TT>`/etc/inetd.conf'</TT> file and cfengine</A>
<LI><A HREF="cfengine-Tutorial.html#IDX206"><TT>`/home'</TT></A>
<LI><A HREF="cfengine-Tutorial.html#IDX207"><TT>`/users'</TT></A>
<LI><A HREF="cfengine-Tutorial.html#IDX210"><TT>`/var/adm/wtmpx'</TT></A>
<LI><A HREF="cfengine-Tutorial.html#IDX296"><TT>`/var/log/cfengine'</TT></A>
<LI><A HREF="cfengine-Tutorial.html#IDX155">/var/log/cfengine/cfengine.log</A>
<LI><A HREF="cfengine-Tutorial.html#IDX211"><TT>`/var/lp/logs/lpsched'</TT></A>
</DIR>
<H2><A NAME="cindex_a">a</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX134">Access control</A>
<LI><A HREF="cfengine-Tutorial.html#IDX288">Access control by directory</A>
<LI><A HREF="cfengine-Tutorial.html#IDX292">Access control in cfd</A>
<LI><A HREF="cfengine-Tutorial.html#IDX216">Access control lists</A>
<LI><A HREF="cfengine-Tutorial.html#IDX220">ACL aliases</A>
<LI><A HREF="cfengine-Tutorial.html#IDX217">ACLs</A>
<LI><A HREF="cfengine-Tutorial.html#IDX222">ACLs, DFS</A>
<LI><A HREF="cfengine-Tutorial.html#IDX221">ACLs, solaris</A>
<LI><A HREF="cfengine-Tutorial.html#IDX20">Actions, order of</A>
<LI><A HREF="cfengine-Tutorial.html#IDX203">AFS</A>
<LI><A HREF="cfengine-Tutorial.html#IDX284"><CODE>AllowConnectionsFrom</CODE> variable</A>
<LI><A HREF="cfengine-Tutorial.html#IDX131">Annulling entries when debugging</A>
<LI><A HREF="cfengine-Tutorial.html#IDX262">Atomic operations in cfengine</A>
<LI><A HREF="cfengine-Tutorial.html#IDX261">Atoms in cfengine</A>
<LI><A HREF="cfengine-Tutorial.html#IDX202"><TT>`auto_direct'</TT></A>
<LI><A HREF="cfengine-Tutorial.html#IDX201"><TT>`auto_master'</TT></A>
<LI><A HREF="cfengine-Tutorial.html#IDX277"><CODE>AutoExecInterval</CODE> variable</A>
<LI><A HREF="cfengine-Tutorial.html#IDX200">automount</A>
</DIR>
<H2><A NAME="cindex_b">b</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX180">Backup policy</A>
<LI><A HREF="cfengine-Tutorial.html#IDX185">Binary server</A>
<LI><A HREF="cfengine-Tutorial.html#IDX196">Binary server, matching</A>
<LI><A HREF="cfengine-Tutorial.html#IDX189">Binary servers, declaring</A>
<LI><A HREF="cfengine-Tutorial.html#IDX197">binserver variable and actionsequence</A>
<LI><A HREF="cfengine-Tutorial.html#IDX258">Broadcasts to the cfengine service.</A>
</DIR>
<H2><A NAME="cindex_c">c</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX293">CERT advisories</A>
<LI><A HREF="cfengine-Tutorial.html#IDX78">CFALLCLASSES</A>
<LI><A HREF="cfengine-Tutorial.html#IDX137">cfd and access keyword</A>
<LI><A HREF="cfengine-Tutorial.html#IDX237"><CODE>cfd</CODE> daemon</A>
<LI><A HREF="cfengine-Tutorial.html#IDX251">cfd dameon</A>
<LI><A HREF="cfengine-Tutorial.html#IDX241"><TT>`cfd.conf'</TT> file</A>, <A HREF="cfengine-Tutorial.html#IDX274"><TT>`cfd.conf'</TT> file</A>
<LI><A HREF="cfengine-Tutorial.html#IDX182">cfengine model</A>
<LI><A HREF="cfengine-Tutorial.html#IDX191">cfengine model, how it works</A>
<LI><A HREF="cfengine-Tutorial.html#IDX27">cfengine, starting</A>
<LI><A HREF="cfengine-Tutorial.html#IDX30"><TT>`cfengine.conf'</TT></A>, <A HREF="cfengine-Tutorial.html#IDX45"><TT>`cfengine.conf'</TT></A>
<LI><A HREF="cfengine-Tutorial.html#IDX240"><TT>`cfengine.conf'</TT> file</A>
<LI><A HREF="cfengine-Tutorial.html#IDX275"><CODE>CFINPUTS</CODE> variable</A>
<LI><A HREF="cfengine-Tutorial.html#IDX39">CFINPUTS variable</A>
<LI><A HREF="cfengine-Tutorial.html#IDX136">cfrun</A>
<LI><A HREF="cfengine-Tutorial.html#IDX238"><CODE>cfrun</CODE> program</A>, <A HREF="cfengine-Tutorial.html#IDX249"><CODE>cfrun</CODE> program</A>
<LI><A HREF="cfengine-Tutorial.html#IDX252">cfrun program</A>
<LI><A HREF="cfengine-Tutorial.html#IDX276"><CODE>cfrunCommand</CODE> variable</A>
<LI><A HREF="cfengine-Tutorial.html#IDX239"><CODE>cfwatcher</CODE> program</A>
<LI><A HREF="cfengine-Tutorial.html#IDX299">ChecksumDatabase</A>
<LI><A HREF="cfengine-Tutorial.html#IDX279"><CODE>ChecksumDatabase</CODE> variable</A>
<LI><A HREF="cfengine-Tutorial.html#IDX318"><CODE>ChecksumUpdates</CODE></A>
<LI><A HREF="cfengine-Tutorial.html#IDX80">Class data and scripts</A>
<LI><A HREF="cfengine-Tutorial.html#IDX128">Class, generic any</A>
<LI><A HREF="cfengine-Tutorial.html#IDX46">Classes</A>
<LI><A HREF="cfengine-Tutorial.html#IDX120">Classes based on shell commands</A>
<LI><A HREF="cfengine-Tutorial.html#IDX48">Classes, compound</A>
<LI><A HREF="cfengine-Tutorial.html#IDX51">Classes, defining and undefining</A>
<LI><A HREF="cfengine-Tutorial.html#IDX247">Clock synchronization during copying</A>
<LI><A HREF="cfengine-Tutorial.html#IDX17">Comments</A>
<LI><A HREF="cfengine-Tutorial.html#IDX47">Compound classes</A>
<LI><A HREF="cfengine-Tutorial.html#IDX294">Computer emergency response team</A>
<LI><A HREF="cfengine-Tutorial.html#IDX29">Config file, default name</A>
<LI><A HREF="cfengine-Tutorial.html#IDX227">Contention during copying under load</A>
<LI><A HREF="cfengine-Tutorial.html#IDX1">Control files</A>
<LI><A HREF="cfengine-Tutorial.html#IDX144"><CODE>copy</CODE>, file sweeps</A>
<LI><A HREF="cfengine-Tutorial.html#IDX181">core files, caution!</A>
<LI><A HREF="cfengine-Tutorial.html#IDX223">Cron jobs, controlling with cfengine</A>
</DIR>
<H2><A NAME="cindex_d">d</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX234">Day of the week</A>
<LI><A HREF="cfengine-Tutorial.html#IDX265">Deadlock protection</A>
<LI><A HREF="cfengine-Tutorial.html#IDX132">Debugging, annulling entries</A>
<LI><A HREF="cfengine-Tutorial.html#IDX28">Default file</A>
<LI><A HREF="cfengine-Tutorial.html#IDX282"><CODE>DenyBadClocks</CODE> variable</A>
<LI><A HREF="cfengine-Tutorial.html#IDX287"><CODE>DenyConnectionsFrom</CODE> variable</A>
<LI><A HREF="cfengine-Tutorial.html#IDX289">Device boundaries and remote copy access</A>
<LI><A HREF="cfengine-Tutorial.html#IDX204">DFS</A>
<LI><A HREF="cfengine-Tutorial.html#IDX139">Directory Names, use of wildcards</A>
<LI><A HREF="cfengine-Tutorial.html#IDX307">Disk full, problems during copying</A>
<LI><A HREF="cfengine-Tutorial.html#IDX9">DNS</A>
<LI><A HREF="cfengine-Tutorial.html#IDX57">Dots in hostnames</A>
</DIR>
<H2><A NAME="cindex_e">e</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX40">Environment variable, CFINPUTS</A>
<LI><A HREF="cfengine-Tutorial.html#IDX65">Environment variables</A>, <A HREF="cfengine-Tutorial.html#IDX75">Environment variables</A>
<LI><A HREF="cfengine-Tutorial.html#IDX315">Environment variables, inheritance</A>
<LI><A HREF="cfengine-Tutorial.html#IDX116">Exceptions</A>
<LI><A HREF="cfengine-Tutorial.html#IDX148"><CODE>exclude=</CODE></A>
<LI><A HREF="cfengine-Tutorial.html#IDX151">exclude=, problems</A>
<LI><A HREF="cfengine-Tutorial.html#IDX117">Excluding actions in a controlled way</A>
<LI><A HREF="cfengine-Tutorial.html#IDX268">ExpireAfter, caution setting to zero!</A>
<LI><A HREF="cfengine-Tutorial.html#IDX178">Exporting filesystems</A>, <A HREF="cfengine-Tutorial.html#IDX199">Exporting filesystems</A>
</DIR>
<H2><A NAME="cindex_f">f</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX41">File search paths</A>
<LI><A HREF="cfengine-Tutorial.html#IDX11">Files, checking permissions</A>
<LI><A HREF="cfengine-Tutorial.html#IDX3">Files, configuration</A>
<LI><A HREF="cfengine-Tutorial.html#IDX2">Files, control</A>
<LI><A HREF="cfengine-Tutorial.html#IDX142"><CODE>files</CODE>, file sweeps</A>
<LI><A HREF="cfengine-Tutorial.html#IDX23">Format</A>
<LI><A HREF="cfengine-Tutorial.html#IDX21">Free format</A>
<LI><A HREF="cfengine-Tutorial.html#IDX56">Fully qualified names</A>
</DIR>
<H2><A NAME="cindex_g">g</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX235">Grouping time values</A>
<LI><A HREF="cfengine-Tutorial.html#IDX236"><CODE>groups</CODE> and time intervals</A>
</DIR>
<H2><A NAME="cindex_h">h</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX102">Hard class name collision</A>
<LI><A HREF="cfengine-Tutorial.html#IDX13">Hard links</A>
<LI><A HREF="cfengine-Tutorial.html#IDX34">Help</A>
<LI><A HREF="cfengine-Tutorial.html#IDX205">Home directories and automount</A>
<LI><A HREF="cfengine-Tutorial.html#IDX186">Home server</A>
<LI><A HREF="cfengine-Tutorial.html#IDX190">Home servers, declaring</A>
<LI><A HREF="cfengine-Tutorial.html#IDX58">Host name gets truncated</A>
<LI><A HREF="cfengine-Tutorial.html#IDX101">Hostname collision</A>
<LI><A HREF="cfengine-Tutorial.html#IDX271">HUP and cfd, don't need to</A>
</DIR>
<H2><A NAME="cindex_i">i</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX4">ifconfig</A>
<LI><A HREF="cfengine-Tutorial.html#IDX267">IfElapsed, caution setting to zero!</A>
<LI><A HREF="cfengine-Tutorial.html#IDX145"><CODE>ignore=</CODE></A>
<LI><A HREF="cfengine-Tutorial.html#IDX146">Ignoring, private lists in files, copy and links</A>
<LI><A HREF="cfengine-Tutorial.html#IDX147"><CODE>include=</CODE></A>
<LI><A HREF="cfengine-Tutorial.html#IDX266">Infinite loops</A>
<LI><A HREF="cfengine-Tutorial.html#IDX25">Invoking cfengine</A>
<LI><A HREF="cfengine-Tutorial.html#IDX166">Iteration over lists</A>
</DIR>
<H2><A NAME="cindex_l">l</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX192">Linking to binservers</A>
<LI><A HREF="cfengine-Tutorial.html#IDX12">Links</A>
<LI><A HREF="cfengine-Tutorial.html#IDX228">Load balancing</A>
<LI><A HREF="cfengine-Tutorial.html#IDX270">localhost and remote copying</A>
<LI><A HREF="cfengine-Tutorial.html#IDX263">Lock files for ordinary users</A>
<LI><A HREF="cfengine-Tutorial.html#IDX152">Log files</A>
<LI><A HREF="cfengine-Tutorial.html#IDX213">Log files, rotating</A>
<LI><A HREF="cfengine-Tutorial.html#IDX53">Logical NOT</A>
</DIR>
<H2><A NAME="cindex_m">m</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX74">Macros</A>
<LI><A HREF="cfengine-Tutorial.html#IDX278"><CODE>MaxConnections</CODE> variable</A>
<LI><A HREF="cfengine-Tutorial.html#IDX124">moduledirectory</A>
<LI><A HREF="cfengine-Tutorial.html#IDX119">Modules, user defined plug-ins</A>
<LI><A HREF="cfengine-Tutorial.html#IDX10">Monitoring important files</A>
<LI><A HREF="cfengine-Tutorial.html#IDX233">Months</A>
<LI><A HREF="cfengine-Tutorial.html#IDX187">Mount points</A>
<LI><A HREF="cfengine-Tutorial.html#IDX170">Multiple package configuration</A>
<LI><A HREF="cfengine-Tutorial.html#IDX14">Musts in cfengine</A>
</DIR>
<H2><A NAME="cindex_n">n</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX100">Name collision</A>
<LI><A HREF="cfengine-Tutorial.html#IDX8">Name server</A>
<LI><A HREF="cfengine-Tutorial.html#IDX188">Naming convention</A>
<LI><A HREF="cfengine-Tutorial.html#IDX175">netgroups</A>
<LI><A HREF="cfengine-Tutorial.html#IDX6">network configuration</A>
<LI><A HREF="cfengine-Tutorial.html#IDX5">network interface</A>
<LI><A HREF="cfengine-Tutorial.html#IDX7">NFS</A>
<LI><A HREF="cfengine-Tutorial.html#IDX183">NFS mounted filesystems</A>
<LI><A HREF="cfengine-Tutorial.html#IDX184">NFS resources</A>
<LI><A HREF="cfengine-Tutorial.html#IDX176">NIS</A>
<LI><A HREF="cfengine-Tutorial.html#IDX52">NOT operator</A>
</DIR>
<H2><A NAME="cindex_o">o</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX59">Operator ordering</A>
<LI><A HREF="cfengine-Tutorial.html#IDX24">Optional features in cfengine</A>
<LI><A HREF="cfengine-Tutorial.html#IDX18">Order of actions</A>
<LI><A HREF="cfengine-Tutorial.html#IDX264">Ordinary users, lock files</A>
</DIR>
<H2><A NAME="cindex_p">p</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX171">Package configuration, multiple</A>
<LI><A HREF="cfengine-Tutorial.html#IDX42">Path to input files</A>
<LI><A HREF="cfengine-Tutorial.html#IDX141">Patterns</A>
<LI><A HREF="cfengine-Tutorial.html#IDX218">Permissions, extended</A>
<LI><A HREF="cfengine-Tutorial.html#IDX44">Piping input into cfengine</A>
<LI><A HREF="cfengine-Tutorial.html#IDX118">Plug-in modules</A>
<LI><A HREF="cfengine-Tutorial.html#IDX174">Policy for running the system</A>
<LI><A HREF="cfengine-Tutorial.html#IDX22">Program format</A>
<LI><A HREF="cfengine-Tutorial.html#IDX15">Program structure</A>
</DIR>
<H2><A NAME="cindex_q">q</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX160">Quoting strings</A>
</DIR>
<H2><A NAME="cindex_r">r</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX306">Race conditions during copying</A>
<LI><A HREF="cfengine-Tutorial.html#IDX242"><CODE>rdist</CODE> program</A>
<LI><A HREF="cfengine-Tutorial.html#IDX243">Remote distribution of files</A>
<LI><A HREF="cfengine-Tutorial.html#IDX244">Remote execution of cfengine</A>, <A HREF="cfengine-Tutorial.html#IDX250">Remote execution of cfengine</A>
<LI><A HREF="cfengine-Tutorial.html#IDX273">Rereading <TT>`cfd.conf'</TT></A>
<LI><A HREF="cfengine-Tutorial.html#IDX272">Restarting cfd</A>
<LI><A HREF="cfengine-Tutorial.html#IDX135">Restricting access</A>
<LI><A HREF="cfengine-Tutorial.html#IDX212">Rotating files</A>
<LI><A HREF="cfengine-Tutorial.html#IDX225"><TT>`run-cfengine'</TT> file.</A>
<LI><A HREF="cfengine-Tutorial.html#IDX259">Running cfengine from a single master host</A>, <A HREF="cfengine-Tutorial.html#IDX260">Running cfengine from a single master host</A>
<LI><A HREF="cfengine-Tutorial.html#IDX253">Running cfengine remotely</A>
<LI><A HREF="cfengine-Tutorial.html#IDX257">Running <CODE>cfrun</CODE></A>
</DIR>
<H2><A NAME="cindex_s">s</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX81">Scripts, passing classes to</A>
<LI><A HREF="cfengine-Tutorial.html#IDX19">Sections, order of</A>
<LI><A HREF="cfengine-Tutorial.html#IDX316">Security and environment variables</A>
<LI><A HREF="cfengine-Tutorial.html#IDX246"><CODE>server=</CODE></A>
<LI><A HREF="cfengine-Tutorial.html#IDX269">server= when copying to localhost</A>
<LI><A HREF="cfengine-Tutorial.html#IDX158">setgid root log</A>
<LI><A HREF="cfengine-Tutorial.html#IDX297">setuid log</A>
<LI><A HREF="cfengine-Tutorial.html#IDX157">setuid root log</A>
<LI><A HREF="cfengine-Tutorial.html#IDX298">setuid root programs</A>
<LI><A HREF="cfengine-Tutorial.html#IDX133">Setuid scripts</A>
<LI><A HREF="cfengine-Tutorial.html#IDX121">Shell commands which define classes</A>
<LI><A HREF="cfengine-Tutorial.html#IDX309">Shell, starting programs</A>
<LI><A HREF="cfengine-Tutorial.html#IDX193">Special variables</A>
<LI><A HREF="cfengine-Tutorial.html#IDX226">Splaying host times</A>
<LI><A HREF="cfengine-Tutorial.html#IDX256">SplayTime in cfrun</A>
<LI><A HREF="cfengine-Tutorial.html#IDX165">split</A>
<LI><A HREF="cfengine-Tutorial.html#IDX304">Spoofing</A>
<LI><A HREF="cfengine-Tutorial.html#IDX26">Starting cfengine</A>
<LI><A HREF="cfengine-Tutorial.html#IDX308">Starting commands without a shell</A>
<LI><A HREF="cfengine-Tutorial.html#IDX43">STDIN, reading from</A>
<LI><A HREF="cfengine-Tutorial.html#IDX159">Strings</A>
<LI><A HREF="cfengine-Tutorial.html#IDX16">Structure of a program</A>
<LI><A HREF="cfengine-Tutorial.html#IDX302">Suspicious filenames</A>
<LI><A HREF="cfengine-Tutorial.html#IDX115">System administrator, name</A>
<LI><A HREF="cfengine-Tutorial.html#IDX173">System policy</A>
</DIR>
<H2><A NAME="cindex_t">t</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX303">TCP wrappers</A>
<LI><A HREF="cfengine-Tutorial.html#IDX143"><CODE>tidy</CODE>, file sweeps</A>
<LI><A HREF="cfengine-Tutorial.html#IDX179">Tidying files</A>
<LI><A HREF="cfengine-Tutorial.html#IDX229">Time classes</A>
<LI><A HREF="cfengine-Tutorial.html#IDX301">Tripwire</A>
<LI><A HREF="cfengine-Tutorial.html#IDX320">Trust model</A>
</DIR>
<H2><A NAME="cindex_u">u</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX99">underscoreclasses</A>
<LI><A HREF="cfengine-Tutorial.html#IDX122">User programs which define classes</A>
<LI><A HREF="cfengine-Tutorial.html#IDX311"><CODE>useshell=</CODE></A>
</DIR>
<H2><A NAME="cindex_v">v</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX62">Variable substitution</A>
<LI><A HREF="cfengine-Tutorial.html#IDX73">Variables and Macros</A>
<LI><A HREF="cfengine-Tutorial.html#IDX64">Variables, cfengine</A>
<LI><A HREF="cfengine-Tutorial.html#IDX194">Variables, cfengine model</A>
<LI><A HREF="cfengine-Tutorial.html#IDX63">Variables, environment</A>
<LI><A HREF="cfengine-Tutorial.html#IDX76">Variables, setting to result of a shell command</A>
<LI><A HREF="cfengine-Tutorial.html#IDX113">Variables, using</A>
<LI><A HREF="cfengine-Tutorial.html#IDX37">Verifying with -n option</A>
</DIR>
<H2><A NAME="cindex_w">w</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX313">warnnonownermail</A>
<LI><A HREF="cfengine-Tutorial.html#IDX312">warnnonusermail</A>
<LI><A HREF="cfengine-Tutorial.html#IDX127">Wildcard, any class</A>
<LI><A HREF="cfengine-Tutorial.html#IDX140">Wildcards</A>
<LI><A HREF="cfengine-Tutorial.html#IDX138">Wildcards, in directory names</A>
</DIR>
<H2><A NAME="cindex_y">y</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX232">Years</A>
</DIR>
<H1><A NAME="SEC81" HREF="cfengine-Tutorial_toc.html#TOC81">FAQ Index</A></H1>
<P>
Jump to:
<A HREF="#mbindex_b">b</A>
-
<A HREF="#mbindex_c">c</A>
-
<A HREF="#mbindex_d">d</A>
-
<A HREF="#mbindex_h">h</A>
-
<A HREF="#mbindex_i">i</A>
-
<A HREF="#mbindex_m">m</A>
-
<A HREF="#mbindex_p">p</A>
-
<A HREF="#mbindex_s">s</A>
-
<A HREF="#mbindex_t">t</A>
-
<A HREF="#mbindex_w">w</A>
<P>
<H2><A NAME="mbindex_b">b</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX60">Brackets (parentheses) in classes.</A>
</DIR>
<H2><A NAME="mbindex_c">c</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX283">Can't stat error when remote copying</A>
<LI><A HREF="cfengine-Tutorial.html#IDX281">Checksums take too long to compute.</A>
<LI><A HREF="cfengine-Tutorial.html#IDX172">Configure multiple packages</A>
</DIR>
<H2><A NAME="mbindex_d">d</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX123">Define classes based on result of user program</A>
<LI><A HREF="cfengine-Tutorial.html#IDX286">Denial of service attacks</A>
</DIR>
<H2><A NAME="mbindex_h">h</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX285">Hanging connections attacks</A>
<LI><A HREF="cfengine-Tutorial.html#IDX230">How can I make complex time intervals using time classes?</A>
<LI><A HREF="cfengine-Tutorial.html#IDX224">How can I use cfengine to make a global cron file?</A>
<LI><A HREF="cfengine-Tutorial.html#IDX164">How do I quote quotes?</A>
<LI><A HREF="cfengine-Tutorial.html#IDX208">How to keep all users in <TT>`/home'</TT></A>
</DIR>
<H2><A NAME="mbindex_i">i</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX167">Iterating over lists</A>
</DIR>
<H2><A NAME="mbindex_m">m</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX314">Mailbox policing</A>
<LI><A HREF="cfengine-Tutorial.html#IDX280">MD5 checksums take a long time to compute.</A>
</DIR>
<H2><A NAME="mbindex_p">p</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX61">Parentheses in classes.</A>
</DIR>
<H2><A NAME="mbindex_s">s</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX169">split, using a space</A>
</DIR>
<H2><A NAME="mbindex_t">t</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX231">Time classes, picking out complex time intervals</A>
<LI><A HREF="cfengine-Tutorial.html#IDX317">Tripwire functionality</A>
</DIR>
<H2><A NAME="mbindex_w">w</A></H2>
<DIR>
<LI><A HREF="cfengine-Tutorial.html#IDX291">Why do I get network access denied to files I have granted access to?</A>
<LI><A HREF="cfengine-Tutorial.html#IDX290">Why does cfd give access to files on a different filesystem?</A>
</DIR>
<P><HR><P>
This document was generated on 16 October 2000 using
<A HREF="http://wwwinfo.cern.ch/dis/texi2html/">texi2html</A> 1.56k.
</BODY>
</HTML>
