Single links

To define a single link, you create an entry of the following form:

links:

  class::

     linkname -> object_to_link_to
     linkname -> ./relative_link
     linkname -> ../relative_link

If links exists and point to their intended destinations then no action is taken. If a link exists but points incorrectly then a warning is issued, unless the pling operator `!' is given, in which case the correct value is forced. If the link exists and points to a file which does not exist a warning is issued unless the command line option -L is used, in which case the link is deleted. See section Runtime Options.

Here is an example of some valid link statements.

links:

  Physics.sun4::
 
   /usr/local       -> /$(site)/$(host)/local
   /home            -> /$(site)/$(host)/u1
   /etc/sendmail.cf -> /usr/local/mail/etc/global-sendmail.cf

   /usr/lib/sendmail ->! /local/lib/sendmail 

cfengine makes any directories which are required leading up to the link name on the left hand side of the arrow automatically. In the last example the `pling' forces cfengine to make the link even if a file for link exists previously. Plain files are saved by appending `.cfsaved' to the filename, or by moving to a repository, whereas old links are removed. The same effect can be enforced globally using the -E option, but only if the program is run interactively. (In this case a prompt is issued to make sure that you wish to use such a big hammer on your system!)

The link operation accepts a number of parameters

type=hard/relative/absolute

If the link type is hard, a hard link is created See section Hard Links. Symbolic links may specify two special types. If relative is selected, and the `to' object is an absolute path name, the link name will be rewritten as a pathname relative to the source file, using `.' and `..' to move relative to the current directory. For instance, a link from `/usr/local/file' to `/usr/file' would be linked as `./../file'. If the `to' object is already relative, this has no effect. If absolute is specified, cfengine will try to resolve the true path location of the `to' object, expanding any symbolic links or dots in the path name, up to a maximum of four levels of symbolic links.

copy=pattern

This option can be repeated any number of times to build up a list of filenames or wildcards which are to be copied rather than linked symbolically. The copy is made on an age-comparison basis. A global variable may also be set to invoke this feature See section CopyLinks. Directories cannot be copied in this way.

copytype=checksum/ctime

This specifies the basis for deciding whether to update a file which is to be copied instead of linked See section copy.

nofile=kill/force

This decides what happens to links which point to non-existent files. The default action is to remove such links, or refuse to create them. By setting the force option you can force cfengine to make symbolic links to files which do not exist. This is useful for setting up links to filesystems which are not permanently mounted.

exclude=pattern

This option can be repeated any number of times to build up a list of filenames or wildcards which are to be excluded from the linking process. A global variable may also be set to invoke this feature See section ExcludeLinks.

ignore

This works like the global ignore directive but here you may provide a private list of ignorable directories and files. Unlike include, exclude this affects the way cfengine parses directory trees.

recurse=number/inf

This option can only be used with multiple link operations See section Multiple Links. If this option is specified, cfengine links only non-directory objects. Directories are instead created and links within those directories are also created. The value of this option specifies the maximum number of levels to which cfengine should recursively descend a link tree. inf means infinite recursion. Cfengine also ignores files and directories in the ignore list See section ignore.

define=classlist

If a link is created or replaced, the colon, comma or dot separated list of classes becomes defined.

The final feature of the links facility is connected to the use of the cfengine model for mounting NFS filesystems. In particular it concerns the variable $(binserver). The easiest way to understand this feature is to illustrate a couple of examples. Consider the following:

links:

   any::

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

The result of this command is quite different depending on which host is executing it. The variable $(site) clearly has a fixed value, but the variable $(binserver) might expand to any valid binary server for the host executing the program. See section binservers. The procedure cfengine adopts is to go through its list of mountables, keeping only those mountable resources which belong to defined binary servers for the current host. It then attempts to match a filesystem by substituting $(binserver) with each of its valid binservers in turn and it matches the first one binary server which yields an existing file.

Note that every host is a binary server for itself, so that the value of $(binserver) which has absolute priority is alway the same as the value of $(host). This ensures that the link will always be made to a local filesystem if the rules of the model are upheld.

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