Variable substitution

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

• Environment variables from the shell
• Special variables used in cfengine features
• General macro-string substitution.

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

control:

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

...

links:

  $(myvar) -> /another/directory

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

control:

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

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

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

AllClasses

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

arch

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

binserver

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

class

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

domain

The currently defined domain.

faculty

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

fqhost

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

host

The hostname of the machine running the program.

MaxCfengines

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

OutputPrefix

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

  OutputPrefix = ( "cfengine:$(host):")

RepChar

The character value of the string used by the file repository in constructing unique filenames from path names. This is the character which replaces `/' See section RepChar.

site

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

split

The character on which list variables are split See section Split.

sysadm

The name or mail address of the system administrator.

timezone

The current timezone as defined in control.

UnderscoreClasses

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

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

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

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

cr

Expands to the carriage-return character.

dblquote

Expands to a double quote "

dollar

Expands to `$'.

lf

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

n

Expands to a newline character.

quote

Expands to a single quote '.

spc

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

tab

Expands to a single tab character.

You can use variables in the following places:

• In any directory name. The $(binserver) variable is not always appropriate in this context. For instance

links:

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

• In any quoted string. See section shellcommands.

shellcommands:

  any::

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

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

• To define the values of options passed to various actions, in the form option=$(variable).

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

control:

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

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

control:

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

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

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