FSYNC(1)

NAME
fsync - synchronize files on remote machines

SYNOPSIS
fsync [OPTIONS]... [FILES | DIRECTORIES]...
fsync -s [-v[#]]

DESCRIPTION

Fsync is a Perl script which allows for file mirroring and synchronization. Since it is a single Perl script, setting up file synchronization on a new machine is simple. The perl script acts as both the client which the user interacts with and as a remote server, which is started manually or by the client, using a mechanism such as rsh or ssh. The program was written with slow modem connections in mind. Also, fsync supports the concept of merging differences from local/remote with hooks for tools to merge the trees. The first version is the usual client invocation. The optional file/directory arguments specify entities to be synchronized, overriding the @fileList array variable. The second invocation starts fsync in server mode. The server is usually automagically started on the remote host by the client. However, it can be started manually if desired. Normal use usually involves setting up a .fsyncrc file defining $remhost, @excludeList and @fileList. Most simple problems can be diagnosed by setting $verbose=1 and looking at fsyncd.log file. Large files are copied efficiently- if a file has its end changed (or is partially copied), only the new parts are copied. If fsync receives the INT signal (often ctrl-C) while it is copying a file, it tries to gracefully shut down (it will gracelessly abort on receiving three such signals). In the shutdown process, the partially copied file has its timestamp changed to 0 (Dec. 31, 1969) so that the -n flag will get the correct file during the next invocation of fsync. The only inherently Unix-specific aspect (which I can currently think of) is the forward-slash file separator character. Thus, porting to other operating systems should not be too difficult-- if there is interest in this. The optional command-line file/directory arguments are either interpreted relative to the PWD environment variable or should be fully qualified (have a leading /). The entries in the rc file are interpreted relative to $rootdir.

  Options:

-bd  dir
    specify the directory to hold previous versions of all files which are copied over. This sets the name on both the local and remote machines. If this string is "" no backup is made. Default: ~/.fsync-save

-c  Copy all files which exist on only one machine. However, fsync will still prompt the user for files larger than $promptFilesize.

-del
    When mirroring (using the -L or -R flags), specifying this option causes path specifications (files, dirs, etc) which do not exist on the source host/filesystem to be deleted. Thus, specifying this flag leads to true mirroring. When specified with the -c flag, this option causes deletion of files on one host which have been removed on the other since the previous fsync invocation. This behavior is currently only supported for files (doesn't work for directories or symlinks).

-f  file
    evaluate file as the rc file (instead of ~/.fsyncrc).

-fs,
    follow symbolic links (copy objects that symlinks point to, not the symlinks themselves).

-ft,
    follow top-level symbolic links explicitly specified on the command line or in fileList. Convenient if there are a only few symlinks you wish to follow.

-hf  file
    specify the file which contains hash-save info. This sets the name on both the local and remote machines. See the documentation for the $hashSaveFile variable below for information on multi-host syncing. Default: ~/.fsync-hashsave

-L, mirror the local side to the remote. This option adds and updates files, directories, hard and soft links on the remote machine such that they are identical to those on the local machine. When mirroring it may be desirable to set -bd "".

-l  user
    specify user name on the remote host.

-m  run the merge command on all files which differ. The merge command is specified by the $mergeCmd variable. Default: emacs --eval '(ediff \"Lfile\" \"Rfile\")', where Lfile and Rfile are replaced by the names of the local and remote files.

-n  Overwrite older files with their newer counterpart. Fsync checks whether the older file has been modified since the previous time fsync was run and, if so, prompts for user intervention instead of performing the copy.

-nd Do not set the date/time when a file is copied. i.e. make the time value that corresponding to when fsync copied the file.

-np Do not change permissions when a file is overwritten.

-ns Do not stop server when quitting client. The connection information (host, port, password) are stored in a file with name given by $passcodeFilename. When starting, the client looks for this file and attempts to use this connection if the host and port match.

-own
    Synchronize the uid and gid of files and directories. Does not yet work for symlinks.

-p  port,
    specify the port used for fsync communications. A value of 0 causes fsync to use the underlying rsh (or ssh) connection for communication.

-ph  proxy host,
    specify proxy host used, for instance, for certain encrypted connections.

-pp  proxy port,
    specify proxy port used.

-R, mirror the remote side to the local.

-r  root dir,
    specify the root directory used on the local machine. -rh host specify the name of the remote machine. This overrides any entry in the rc file.

-rr  root dir,
    specify the root directory used on the remote machine.

-S  set Skip Mode. It this is specified, no interactive prompts will be issued- the default option will always be taken. So, if -S appears alone on the command line, fsync will copy no files, but will report differences. On the other hand, if the command line has -S -n -c, all files smaller than $promptFilesize and whose older versions have not been modified will be copied.

-V  display version

-v[digit],
    Verbose. Print informational messages. If no digit is specified, verbosity is set to 1, larger numbers result in more output.

  User configurable variables
These can be set in the rc file. The default value is bracketed.

$Slogfile
    name of the log file containing error and informational messages from processeson running the server. [ ".fsyncd.log" ]

$verbose
    the verbosity level. [ 0 ]

$port
    The port which fsync uses. This should be set to something not in use. A value of 0 will cause fsync to use the the rsh (or ssh) connection for communication. [ 9005 ]

$rsh
    The name of the program used by the client to start up the server. Instances of the strings REMHOST, PROXYHOST, PORT, and PROXYPORT are replaced by the name of the remote host, the name of the proxy host, the remote port and the proxy port, respectively. If you manually start the server, set $rsh to "". [ "rsh -l $remuser REMHOST" ]

$mergeCmd
    command to run to merge files which differ. [ "emacs --eval '(ediff \"Lfile\" \"Rfile\")'" ]

$diffCmd
    command to run to display the differences between files which differ. [ "diff Lfile Rfile" ]

$progname
    command to execute on the remote host to fire up the server (the -s argument is added). [ "bin/fsync" ]

$rem_rootdir
    name of the root directory on the remote host. [ ~ ]

$remhost
    name of the remote host.

$proxyhost
    name of the proxyhost.

$proxyport
    port number for the proxy connection.

$rootdir
    name of the root directory on the local host. [ ~ ]

$hashSaveFile
    name of the hash-save file on the local host. [ "~/.fsync-hashsave" ] If you are synchronizing filesystems between multiple hosts (more than two), it is suggested that multiple hash-save files be used (so that fsync understands whether a file has been modified). To aid in this, fsync can employ a filesystem unique id (fsuid): if you include the substring "FSUID" in $hashSaveFile, it is replaced by the fsuid. Hence, setting $hashSaveFile= ".fsync-hashsave-FSUID", will result in safe fsyncing with -n flag between multiple hosts.

$rHashSaveFile
    name of the hash-save file on the remote host. If this is not set, it defaults to that on the local host.

$backupDir
    name of the backup directory on the local host. See the entry for the -bd option.

$rBackupDir
    name of the backup directory on the remote host. If it is not set, it defaults to the value of $backupDir.

$checkSumProg
    name of the external checksum program. It is highly suggested that this program be in the user's path - or specified absolutely. If fsync finds this program and verifies that it works, it will greatly speed the initial recursion of directory hierarchies. Note that it must use the algorithm of the standard Unix cksum program. [ cksum ]

$promptFilesize
    size in bytes above which the user is prompted before a copy occurs. This helps prevent inadvertent copying of huge files. [ 1024*1024 ]

$copyBufferSize
    size (in bytes) of in-memory file buffer used for copying files. [ 100000 ]

$clientRetries
    the number of attempts the client makes to connect to the server. [ 50 ]

$retryInterval
    The interval in seconds between connection attempts. [ 2 ]

@fileList
    an array of entries (directories, symlinks, and files, including hard links) to synchronize. These are specified relative to $rootDir on the local machine and relative to $rem_rootdir on the remote machine.

@excludeList
    an array of regular expressions to exclude from the synchronization. [ ('^..?$' , '^bin.') ]

$skipFilename
    name of the per-directory skip file. This file contains regular expressions which are appended to the name of the current directory. Members of the current directory which match the regular expression(s) are not synchronized to any remote host. For example, the entry .*\.log$ in ~/bin/.fsync-skip will cause all files ending in .log in directory ~/bin to be skipped. Setting the variable $rem_skipFilename in the rc file allows one to specify a different name on the remote machine. [ .fsync-skip ]

$followSymlinks
    whether to follow symbolic links (see -fs above) [0].

$followTopLinks
    whether to follow top-level symbolic links (see -ft above) [0].

BUGS
The tilde abbreviation for matching home directories is not implemented for entries in the rc file. As a workaround for $f = "~/blah"; use: $f = $ENV{"HOME"} . "/blah";
Signal handling does not work correctly with $port=0.
Misbehavior if a symlink is followed outside of the rootDir hierarchy: symlinks to directories will not be created. However, synchronization of files and directories should work properly.

AUTHOR
Written by <Charles@Schwieters.org>
communication over the rsh/ssh medium and -ns functionality contributed by Patrick Ohly <Patrick.Ohly@pallas.com>.
-fs functionality contributed by Alexey Nogin <ayn2@cornell.edu>.
-own functionality from Jon Hittner <jhittner@vindigo.com>.
rpm spec file from David Slimp <rock808@DavidSlimp.com>.
News, updates and documentation: visit http://schwieters.org/fsync/

COPYRIGHT
Copyright © 1999-2002 Charles D. Schwieters
This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.