www.delorie.com/gnu/docs/cfengine/cfengine-Reference_84.html   search  
Buy GNU books!

GNU cfengine

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.10 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:



                        repository=backup directory

                        size=size limits




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. The recurse option is required to copy the contents of subdirectories.

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

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.

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

If you are working on an ipv6 enabled pair of hosts, cfengine will normally select ipv6 for communication between them. If you wish to force the use of ipv4 for some reason, set this option to true.

If set to `true', this option causes files or links which block the creation of directories, during recursive copying, to be moved aside forcably. A single non-supressable warning is given when this occurs; the file is moved to filename`.cf-moved'.

If the backup option is set to "false", cfengine will not make a backup copy of the file before copying.

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.

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.

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.

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.

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 3.8.30 LinkCopies.

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.

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.

If the purge option is used in copying, then the include option has the effect of the excluding files from the purge, i.e. include means `keep' the named files.

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 3.8.23 ExcludeLink.

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.

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 cfservd daemon, and you must make sure that you have defined the variable domain in the control section of the `cfagent.conf' file. If you don't define a domain you will probably receive an error of the form `cfengine: Hey! cannot stat file'.

If a file copy fails due to an error, the classes in this assignment will become active, allowing failover rules to become active.

If this is true, cfengine uses the old protocol specification for temporary compatibility with early version 2 alphas.

This option defaults to 'no' or 'false'. If set to true, cfagent will accept a public key from a server whose public key is presently unknown to the agent, on trust. This option should be used to bootstrap public key transfer between hosts. Once a public key has been accepted, it will not be replaced automatically. Dated public keys must be removed by hand.

Has an effect only when used in conjuction with copy from a remote file server. This causes cfengine to use encryption and one-time keys on transferred data. (This requires RSA keys to be installed on both client and server hosts, and provides strong authentication and encryption, using random session keys.) The preferred algorithm is Blowfish, with a 128 bit key. Generally speaking the only case in which this function makes sense is in transferring shadow password files. Encrypting the transfer of system binaries makes little sense. Note: the encryption keys required to get files from cfservd are those for the user under which cfservd is running (normally root).

If verify is true, cfagent attempts to verify the integrity of a remote file transfer before the new file is installed. This takes time, since an MD5 computation and transaction must take place.

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:

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

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.

Controls whether cfengine allows files of one type to overwrite files of another type, i.e. switches on/off errors if source and existing destination files do not match in type, e.g. if a file would overwrite a directory or link. The default is on for safety reasons.

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).

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. Included files are not purged. 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. If we specify purge, then the following options will also be set and cannot be altered: forcedirs=true, typecheck=false, since other defaults could be very destructive.



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


      /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:


   /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.

3.10.1 Hard links in copying  
3.10.2 Too many open files  

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

  webmaster   donations   bookstore     delorie software   privacy  
  Copyright 2003   by The Free Software Foundation     Updated Jun 2003