Next: , Previous: classes, Up: Command reference


1.7 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. Caution should be exercised in copying files which change rapidly in size. This can lead to file corruption, if the size changes during copying. Cfengine attempts to prevent this during remote copies.

The syntax summary is: 

     
     copy:
     
        class::
     
           master-file
                             dest=destination-file
                             mode=mode
                             owner=owner
                             group=group
                             action=silent/fix
                             backup=true/false
                             repository=backup directory
                             stealth=true/on/false/off
                             timestamps=preserve/keep
                             symlink=pattern
                             include=pattern
                             exclude=pattern
                             ignore=pattern
                             filter=filteralias
                             recurse=number/inf/0
                             type=ctime/mtime/checksum/sum/byte/binary
                             linktype=absolute/symbolic/relative/hard/none/copy
                             typecheck=true/on/false/off
                             define=class-list(,:.)
                             elsedefine=class-list(,:.)
     
                             force=true/on/false/off
                             size=size limits
                             server=server-host
                             secure=true/false
                             purge=true/false
                             syslog=true/on/false/off
                             inform=true/on/false/off

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 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.
repository
This allows a local override of the Repository variable, on an item by item basis. If set to "off" or "none" it cancels the value of a global repository.

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.

stealth
If set to `on' causes cfengine to preserve atime and mtime on source files during local file copies. File times cannot be preserved on remote copies. This option should normally only be used together with a checksum copy, since preserving atime and mtime implies changing ctime which will force continual copying. This is a weakness in the Unix file system. Ctime cannot be preserved. Before version 1.5.0, there was a typo which made this option active on many file copies.
timestamps
If this is set to `preserve' or `keep', the times of the source files are kept by the destination files during copying. This is like the `p' option of the tar command.
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 linkcopies.
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.
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 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. An mtime comparison does not take into account changes of file permissions, only modifications to the contents of the files.
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'.
secure
Has an effect only when used in conjuction with copy from a remote file server. This causes cfengine to use 3DES key encryption and one-time keys on transferred data. This provides good enough privacy for the purposes of system adminstration, but it is not meant to be a super-secure means of encryption. Generally speaking the only case in which this function makes sense is in transferring shadow password files. If you are encrypting the transfer of system binaries, you need your head examining. When encrypt is specified, an md5 checksum is always used to verify the file. Note: the encryption keys required to get files from cfd are those for the user under which cfd is running (normally root). Cfd will not switch keys for other users, so encrypted transfer will not work for all users. If a file requires encrypted transfer (secure flag in cfd) then normal users will not be able to collect it.
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. If this value is set to copy or none, symbolic links will be replaced by actual copies of the files they point to. Note that for directories, this option is ignored.
typecheck
Switches on/off error messages if source and existing destination files do not match in type, e.g. if a file would overwrite a directory or link.
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. Note that if the copy command has includes or excludes or ignored files, cfengine will purge only those files on the client machine which are also on the server. This means that some files (such as system specific work files) can be excluded from copies without them being destroyed. Note that purging is disallowed if contant with a remote server fails. This means that local files will not be destroyed by a denial of service attack. You should not use this option to synchronize NFS mounted file systems. If the NFS server goes down, cfengine cannot then tell the difference between a valid empty directory and a missing NFS file system. If you use purge, use a remote copy also.

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.