shellcommands

Cfengine focuses on fairly simple minded tasks in order to be as general as possible. In many cases you will therefore want to write a script to do something special on your system. You can still take advantage of the classes you have defined by executing these scripts or shell commands from this section.

The syntax is simply to quote the command you wish to be executed.

shellcommands:

  "command-string"  

          timeout=seconds 
          useshell=true/false
          umask=octal number
          owner=uid
          group=gid
          define=class-list
          background=false/true
          chdir=directory
          chroot=directory
          preview=true/false

The user and group ID's of the process can be set to restrict the permissions of the shellcommand to another user only if cfengine is executed by root. If you set the optional timeout string, then cfengine will abort the shellcommand if it exceeds the specified time-limit in seconds. This can be useful for avoiding situations caused by hung network connections etc.

Variable substitution works within the strings. Here are some examples.

shellcommands:

   sun4::

       "/usr/lib/find/updatedb"

   AllHomeServers.Sunday::

       "/dir/noseyparker /$(site)/$(host)/u1 $(sysadm) nomail"

   AllBinaryServers.sun4.Saturday::

      "/usr/etc/catman -w -M /usr/local/man"
      "/usr/etc/catman -w -M /usr/local/X11R5/man"
      "/usr/etc/catman -w -M /usr/man"
      "/usr/etc/catman -w -M /usr/local/gnu/man"

If you need to write more advanced scripts, which make detailed use of the classes defined by cfengine, use the $(allclasses) variable to send a complete list of classes to your script in the format

CFALLCLASSES=class1:class2:class3...

This variable is kept up-to-date at any given time with only the classes which are defined. The command line option `-u' or `--use-env' can be used to define an environment variable which will be inherited by all scripts and contains the same information. This is not the standard approach, since some systems cannot cope with this rapid change of environment and generate a Bus Error.

Commands can be iterated over variable lists, provided there is at least one space between each variable. For example:

control: 

      actionsequence = 
         (
         shellcommands
         )

 var1 = ( a:b:c )
 var2 = ( x:y:z )

shellcommands:

   "/bin/echo $(var1) $(var2)"

This iterates over all values of the list variables. @xref{Iterating over lists,Iterating over lists,Iterating over lists,cfengine-Tutorial}. If you are iterating over a list, the timeout applies to each separate iteration, not to the sum of all the iterations.

The chroot option changes the process root directory of the command, creating a `sandbox' which the process cannot escape from. Best used together with a change of owner, since a root process can break out of such a confinement in principle. The chdir option changes the current working directory of the restarted process.

The preview option means that the shellcommand will also be executed during the --dry-run (-n) options. This allows cfengine to be more aware of the results of scripts which define classes. This option should be used with care. Scripts should conform to the protocol of not executing unnecessary commands when the classes opt_dry_run is defined.

Go to the first, previous, next, last section, table of contents.