copy

Cfengine copies files between locally mounted filesystems and via the network from registered servers. The copy algorithm avoids race-conditions which can occur due to network and system latencies by copying first to a file called `file.cfnew' on the local filesystem, and then renaming this quickly into place. The aim of this roundabout procedure is to avoid situations where the direct rewriting of a file is interrupted midway, leaving a partially written file to be read by other processes. Cfengine attempts to preserve hard links to non-directory file-objects, but see the caution below. The syntax summary is:

copy:

   class::

      master-file 
                        dest=destination-file 
                        mode=mode
                        owner=owner 
                        group=group 
                        action=silent/fix
                        backup=true/false
                        symlink=pattern
                        include=pattern
                        exclude=pattern 
                        recurse=number/inf/0
                        type=ctime/checksum/sum/byte/binary
                        linktype=absolute/symbolic/relative/hard
                        define=class-list(,:.) 
                        force=true/on/false/off
                        size=size limits
                        server=server-host
                        purge=true/false

dest

The destination file is the only obligatory item. This must be the name of an object which matches the type of the master object i.e. if the master is a plain file, the destination must also be the explicit name of a plain file. An implicit `copy file to directory' syntax is not allowed. Symbolic links are copied as symbolic links, plain files are copied as plain files and special files are copied as special files. If the master and image are directories then all of the child files which are not directories are copied from source to destination.

mode, owner, group

The file mode, owner and group of the images are specified as in the files function See section files.

action

The action may take the values warn or silent. The default action is fix, i.e. copy files. If warn is specified, only a warning is issued about files which require updating. If silent is given, then cfengine will copy the files but not report the fact.

force

If set to `true', this option causes cfengine to copy files regardless of whether it is up to date.

backup

If the backup option is set to "false", cfengine will not make a backup copy of the file before copying. Copy makes a literal image of the master file at the destination, checking whether the master is newer than the image. If the image needs updating it is copied. Existing files are saved by appending .cfsaved to the filename.

recurse

Specifies the depth of recursion when copying whole file-trees recursively. The value may be a number or the keyword inf. Cfengine crosses device boundaries or mounted filesystems when descending recursively through file trees. To prevent this it is simplest to specify a maximum level of recursion.

symlink

This option may be repeated a number of times to specify the names of files, or wildcards which match files which are to be symbolically linked instead of copied. A global list of patterns can also be defined in the control section of the program See section LinkCopies.

include

This option may be repeated a number of times to specify the names of files, or wildcards which match files which are to be included in a copy operation. Specifying one of these automatically excludes everything else except further include patterns. A global list of patterns can also be defined in the control section of the program.

exclude

This option may be repeated a number of times to specify the names of files, or wildcards which match files which are to be excluded from a copy operation. A global list of patterns can also be defined in the control section of the program `excludes' override `includes'. See section ExcludeLinks.

type

Normally cfengine uses the ctime date-stamps on files to determine whether a file needs to be copied: a file is only copied if the master is newer than the copy or if the copy doesn't exist. If the type is set to `checksum' or `sum', then a secure MD5 checksum is used to determine whether the source and destination files are identical. If `byte' or `binary' is specified, a byte by byte comparison is initiated.

server

If you want to copy a file remotely from a server, you specify the name of the server here. This must be the name of a host which is running the cfd daemon, and you must make sure that you have defined the variable domain in the control section of the `cfengine.conf' file. If you don't define a domain you will probably receive an error of the form `cfengine: Hey! cannot stat file'.

size

With this option you can specify that a file is only to be copied if the source file meets a size critereon. This could be used to avoid installing a corrupted file (the copying of an empty password file, for instance). Sizes are in bytes by default, but may also be quoted in kilobytes or megabytes using the notation:

numberbytes
numberkbytes
numbermbytes

Only the first characters of these strings are significant, so they may be written however is convenient: e.g. 14kB, 14k, 14kilobytes etc. Examples are:

   size=<400  # copy if file size is < 400 bytes
   size=400   # copy if file size is equal to 400 bytes
   size=>400  # copy if file size > 400 bytes

linktype

This option determines the type of link used to make links. This only applies if the file is linked rather than copied because it matches a pattern set by symlink. The default type is a direct symbolic link. The values `relative' or `absolute' may be used, but hard links may not be created in place of copied files, since hard links must normally reside on the same filesystem as their files, and it is assumed that most links will be between filesystems.

define

This option is followed by a list of classes which are to be `switched on' if and only if the named file was copied. In multiple (recursive) copy operations the classes become defined if any of the files in the file tree were copied. This feature is useful for switching on other actions which are to be performed after the installation of key files (e.g. package installation scripts etc).

purge

If this option is set to true, cfengine will remove files in the destination directory which are not also in the source directory. This allows exact images of filesystems to be mantained.

Example:

copy:

      /local/etc/aliases dest=/etc/aliases m=644 o=root g=other
      /local/backup-etc  dest=/etc

   solaris::

      /local/etc/nsswitch.conf dest=/etc/nsswitch.conf

In the first example, a global aliases file is copied from the master site file `/local/etc/aliases' to `/etc/aliases', setting the owner and protection as specified. The file gets installed if `/etc/aliases' doesn't exist and updated if `/local/etc/aliases' is newer than `/etc/aliases'. In the second example, `backup-etc' is a directory containing master configuration files (for instance, `services', `aliases', `passwd'...). Each of the files in `backup-etc' is installed or updated under `/etc'. Finally, a global `nsswitch.conf' file is kept up to date for solaris systems.

The home directive can be used as a destination, in which case cfengine will copy files to every user on the system. This is handy for distributing setup files and keeping them updated:

copy:

   /local/masterfiles/.cshrc  dest=home/.cshrc mode=0600

You can force the copying of files, regardless of the date stamps by setting the option force=true or force=on. The default is force=false or force=off.

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