.\"                                      Hey, EMACS: -*- nroff -*-
.TH fcopy 8 "18 November 2014" "FAI 4"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.SH NAME
fcopy \- copy files using classes
.SH SYNOPSIS
.B fcopy
.RI [ options ] " SOURCE" ...
.SH DESCRIPTION
Copy a file from SOURCE to its target using classes.
It also sets permission modes, owner and group.
Each SOURCE argument is a directory which contains one or more
template files for the source file to copy.  Depending on the list of
defined classes, one file of the source directory is selected and
copied to the target.  The target filename is the name of the source
directory.

The exit code returned by fcopy is 0 if all files are copied
successfully and >0 if an error occurs.  For every successfully copied
file, a log message is printed to standard output.
.SH OPTIONS
.TP
Options \-c, \-s, \-t and a SOURCE are required. Usually \-c, \-s and \-t
are set via variables in FAI.
.TP
.B \-B
Remove backup files with suffix .pre_fcopy. You can also set the
environment variable FCOPY_NOBACKUP to 1.
.TP
.BI "\-b " dir
Don't copy files to file.pre_fcopy, but use hierarchy under "dir" instead.
The same effect is achieved by setting environment variable FAI_BACKUPDIR.
.TP
.BI "\-c " class[,class]
Define classes.  Multiple classes must be comma separated.  If not
specified, use the shell environment variable $classes (space
separated).  The first class has lowest priority.
.TP
.BI "\-C " file
Read classes from \fIfile\fR.  Lines can contain multiple classes which
are space separated.  Lines starting with # are comments.
.TP
.BI \-d
Delete target file if no class applies.
.TP
.B \-D
Create debugging output.
.TP
.BI "\-F " file
Read list of sources from \fIfile\fR.  One SOURCE per line.
.TP
.B \-h
Show help, version and summary of options.
.TP
.B \-H
If source is a symbolic link, make destination a symbolic link too.
.TP
.B \-i
Ignore warnings about no matching class and always exit with 0.
.TP
.BI "\-I " dir[,dir]
Override list of ignored directories when recursing. If not given, it is
taken from $FCOPY_IGNOREDIRS and as a last chance an internal list of known
revision control system's metadata is used (CVS, .cvs, {arch}, .arch\-ids).
.TP
.B \-l
Do not copy if destination is a symbolic link
.TP
.BI "\-L " file
Log SOURCE and used class to \fIfile\fR.  Output format is
.br
SOURCE CLASS COMMENT
.br
where COMMENT gives some information about why the file has been
preserved. If not specified and $LOGDIR is set, use $LOGDIR/fcopy.log.
.TP
.BI "\-m " user,group,mode
Set user, group and mode for all copied files (mode as octal number, user and
group numeric id or name).  If not specified, use file file-modes or data of source file.
.TP
.BI "\-M "
Use default values for user, group and mode.  This is equal to \-m root,root,0644
.TP
.BI "\-n "
Print the commands, but do not execute them. This is like \-\-dry-run in
other programs. You can enable it for all calls of fcopy by setting
the environment variable $FCOPY_DRYRUN.
.TP
.B \-r
Copy recursively (traverse down the tree).  Copy all files below
SOURCE.  These are all subdirectory leaves in the SOURCE tree.  Ignore
"ignored" directories (see "\-I" for details).
.TP
.BI "\-s " source_dir
Look for SOURCE files relative to \fIsource_dir\fR.  Use $FAI/files if
not specified.
.TP
.BI "\-t " target_dir
Copy files relative to \fItarget_dir\fR.  Use $FAI_ROOT if not specified.
.TP
.B \-U
If in softupdate mode skip this entire fcopy command.
.TP
.B \-v
Create verbose output.

.SH SCRIPTS
.TP
.B preinst
If a file 'preinst' exists and is executable, it is used in the following way:
.RS
.IP 1. 3
a temporary copy of the file for the used class is created
.IP 2. 3
preinst is called with the used class and the full pathname to this
temporary copy (you can do in-place substitutions or other modifications on this
copy)
.IP 3. 3
the copy is compared to the destination and replaces it only if there are
any differences and if the preinst scripts has a exit code zero.
.RE

.TP
.B postinst
If a file 'postinst' exists and is executable, it is called after
successfully having copied the file. It is called with two parameters,
the class being used and the full pathname to the target file. The
variable ROOTCMD is set, so you can prepend it to commands which
should be executed in the newly installed system.

.SH EXAMPLES
.br
Suppose the source directory /files/etc/X11/xorg.conf consists of the
following files:

CAD   DEFAULT   LAB   MACH64   server1   ant04   postinst

Each file is an instance of a xorg.conf file for a different
Xserver configuration.  The command

    # fcopy \-s /files \-t /target /etc/X11/xorg.conf

copies one of these files from the directory /files/etc/X11/xorg.conf to
the file /target/etc/xorg.conf.  For all defined classes, fcopy looks if a
corresponding file exists.  The class with the highest priority that
matches an existing file name will be used
for copying. Here are examples of defined classes for different hosts and the
file which will be copied by fcopy.

.IP "   Host belongs to the classes" 20v
File used for copy
.\"

.IP "   DEFAULT,LAB,server3" 20v
LAB
.IP "   DEFAULT,CAD,server1" 20v
server1
.IP "   DEFAULT,MACH64,ant01" 20v
MACH64
.IP "   DEFAULT,TFT,ant13" 20v
DEFAULT
server1


.fi
.PP

In FAI the list of defined classes starts with DEFAULT and the
last class is the hostname.  So DEFAULT is only used when no file for
another class exists.  If a file is equal to the hostname, this
will be used, since hostname should always be the last class.

User, group and permissions for the files can be defined in several
ways.  Option \-m has the highest priority and will be used for all
files, if specified.  The file file-modes in the source directory can
contain one line for each class.  The space separated parameters are:

owner group mode class

where owner and group can be specified by numeric id or by name.  The
file permissions are defined by mode, which must be octal.  If class is
missing, the data is used for all other classes, for which no data is
defined.  If neither \-m or file-modes data is available, the user,
group and mode of the source file will be used for the target file.

Missing subdirectories for the target file are created with mode
0755.  If the destination file already exists and is different from the
source file, the suffix .pre_fcopy is appended to the old version of
the target file.  If source and target files are equal, no copy is performed.
A copied file gets the same access and modification time as the source file, not
the time of the copy.  If also the file postinst exists, it will be
executed after the file was copied.

.SH NOTES
Do not create a file DEFAULT if no reasonable default configuration file can be
used.  It's better to exit with an error than to copy a wrong
configuration file.

This command can also be used to maintain your configuration files on
a huge number of hosts.
.SH SEE ALSO
.PD 0
\fIftar\fP(8)
.br

This program is part of FAI (Fully Automatic Installation).  See the FAI manual
for more information on how to use fcopy.  The FAI homepage is http://fai-project.org.

.SH AUTHOR
Thomas Lange <lange@informatik.uni-koeln.de>
.br
Henning Glawe <glaweh@physik.fu-berlin.de>