USBSYNC

Section: User commands (1)
Updated: 01-05-2009

NAME

usbsync - A synchronization utility for mass storage volumes

SYNOPSIS

usbsync [-f usbsyncfile] [-p|-g|-c] [-s] [-d] [-l] [-o] [-e] MOUNTPOINT

DESCRIPTION

Easily keeping files, directories as well as entire directory trees up-to-date between various hosts with or without multiple users.

Functionally, a simple text file, usually named .usbsync is placed into the top level directory of a storage volume. This file allows a user to define certain file and directory correspondences in such a way that a file or directory on the storage medium always matches one or more other files or directories on one of the hosts given by name.

See usbsync(5) for the expected format of this file.

OPTIONS

-f FILE, --usbsync-file FILE: Specify to use FILE instead of the default file usbsync in the mass storage volume's mount point directory to read synchronization information (file and directory correspondences) from.
-p, --prompt: Display a prompt before updating (creating/replacing) any file or directory. This prompt does also offer the possibility of replacing a more recent version of a file with an older one, to obtain additional information, or to delete a single file without counterpart.
-g, --single: When synchronizing, stop at each file or directory without counterpart on the synchronization partner and prompt if this file should be either copied, removed, or skipped.
-c, --check-only: No synchronization tasks will be performed; only print which files or directories need to be updated.
-s, --save-sync: For each updated file there will a back-up copy according to the naming convention `.<filename>.ubs' be present in the same directory.
-d DEPTH, --dir-recursion DEPTH: When synchronizing directories, specifies at which recusive sub-directory level (tree depth) the program should stop. 0 means only files in the top-level directory.
-l, --symlinks: Copy symbolic links themselves rather than the files they point to; do not follow or dereference.
-o, --ignore-owner: Enable this option if you neither want to have any particual user and group ownership nor any file permission bits set for the objects synchronized onto the storage volume. This can come in handy in connection with certain file system that do not support the concept of file/directory ownership or of file permission bits (like, for instance, vfat).
-m GRAN, --granularity GRAN: Set the granularity/resolution for modification times in seconds. This value defaults to 1. Modification time incongruity depends on the file system and the operating system used; Linux, for instance, is able to limit this value to 1 second, hence the default here.
-e, --no-error: Suppress all error messages.
-v LEVEL, --verbose LEVEL: Verbose output, whereby verbosity level: 0 < LEVEL < 4
-q, --quiet: Do not output anything.
-h, --help: Print a help message.
--version: Print program information

RETURN VALUE

Upon successful completion usbsync returns a value of 0 to the calling shell. If a fatal error occurred during the execution of the usbsync program an error code is returned and an error message is output as appropriate (see DIAGNOSTICS below).

DIAGNOSTICS

The ubsync program conceptually distinguishes between three types of errors, that is, fatal errors, parsing errors, and normal errors.

Fatal errors cause the program to immediately abort as some crucial part of the program failed to execute. Normal and parsing errors denote that some operation failed; that without any severe consequences for subsequent program execution steps. Parsing errors generally point out an error that occurred while scanning the .usbsync file. They ought to be fixed by editing the .usbsync file accordingly.

If an error occurs that is likely to occur multiple times (e. g. an error on a common file operation), it is stored and output after the synchronization process has finished.

The following list elaborates on a set of specially selected errors and gives reasons for the fault that occurred as much as possible.

Error codes are given on the left, descriptions on the right.

Fatal errors

3: Memory allocation failed; check if your system has still free heap memory space available.
4: See fatal error 3 above.
6: A file stream has become invalid while an operation was taking place. This could mean that your .usbsync file is broken.
7: A file descriptor has become invalid while an operation was taking place. This could mean that your .usbsync file is broken.
8: A segementation fault occurred while trying to access an invalid memory address. This error is probably caused by a bug in the application. Please refer to the BUGS section below.
9: Parsing the .usbsync file failed. This fatal error could have either occurred because a wrong mount point for the storage volume was specified on the command line, or because there is no .usbsync file present in the volume's top-level directory (check if the `-f' option would help).

Normal errors

201: The lstat system call failed. This can only be because the file is not available anymore or became invalid; calling lstat itself does not require user access priviliges.
203: No mountpoint was set; please specify on the command line.
204: Options were set which are logically not feasible to be set together. See the OPTIONS section above.
212: Flushing is necessary in order to ensure that any data that was modified, copied, or changed by usbync does not remain stored in subsequent buffers but will rather be written to the underlying device. You may see to the problem that occurred here by invoking sync manually (see sync(1) for details).
246: This error usually occurs when scanning the directories given in one synchronization entry in the .usbsync file yielded no results. Make sure there are objects present in the directories you specified for synchronization.
248: A file or directory path that exceeds the maximum length limit was encountered. The usual path length assumed by usbsync is 4096 characters and therewith adhers to the conventions of some of the most common Unices.

EXAMPLES

In all the examples, a hypothetical storage volume mounted at /media/medium is assumed to contain a properly set up .usbsync file (see usbsync(5) for more details).

usbsync -c /media/medium: Check the mass storage volume mounted at /media/medium for files and directories to be synchronized; no actual synchronization tasks of any kind, that is any kind of file or directory modification, is going to be performed.
usbsync -g -s -l /media/medium: When synchronizing, stop at files and directories that do not have a counterpart at the synchronization partner; prompt for what action is to be taken. Furthermore, save synchronization is opted for, which means that back-up copies of any file updated will be made in advance. Also, `-l' is given which results in usbsync copying symbolic links rather than the targets they point to.
usbsync -d 5 -o -p /media/medium: Stop at a subdirectory depth of 5, do not set file ownerships, and enable the interactive prompt for each file or directory to be synchronized.
usbsync -f .myusbsync -v 3 /media/medium: A different name for the .usbsync file on the mass storage volume is chosen and usbsync is run in the highest verbosity mode (level 3 of 3).

CAVEATS

Altough usbsync(1) greatly simplifies the process of backing up certain sensitive data as a whole, general care is to be taken in order to avoid suffering from data loss.

It is always highly recommended that, if you are uncertain about running usbsync for a certain device, to check files and directories that need updating in advance by passing the `-c' option to the usbsync program on the commmand line.

Also, the built-in feature of enabling an interactive synchronization process, using the `-p' option, may be utilized to have certain advanced just-in-time options for file and directory synchronizations available.

Moreover, if you intend to be really careful, you may also enable the feature of save synchronization by passing the `-s' option on the command line. Now, for each file that gets updated (overwritten with a newer version), a back-up copy is made (see OPTIONS above).

RESTRICTIONS

Certain file systems like vfat are neither aware of the Unix concept of file and directory ownership nor of the concept of permission bits. This does only turn out to be a minor problem as it can be remedied giving the `-o' command line option.

Another issue is that, when not running with sufficient privileges, the usbsync program might not be able to set certain file and directory ownership and permisson bits neither. Hence, it is recommended (if possible) to run as root (see sudo(8) for details); the appropriate owner of a file or directory will then be set in any case.

If root access is not one of the options and if the file system of your mass storage volume is unsupportive of file ownerships, pass the `-o` option on the command line.

NOTES

In the case of synchronizing symbolic links you should take care to predict the right behavior of usbsync. Some things, therefore, should be noted by the mindful user:

The usual behaviour of usbsync when copying symbolic links is that it resolves soft links by default. This means that generally, a symbolink link's name is preserved and a new file with the same file name as the symbolic link will appear on the target side. This file, however, will have the contents of the file the symbolic link on the source side was referencing.

In case the symbolic link points to a directory, the symbolic link is exactly treated as if it were the directory itself.

If, in the two aforementioned cases, the symbolic link on the source side should be a dangling link (a symbolic link whose link target does not exists) the copying process for this (non found) file or directory will be skipped.

To change the default behaviour when handling symbolic links you may specify the `-l, --symlink' option, which indicates usbsync that it should copy the symbolic link itself rather than file it refers to.

If you opted for giving the `-l' command line argument, care is to be taken, too. If a mere symbolic link at the source side is found to be more recent than any other file on the target side (regardless of whether the target file is a symbolic link or not) it will be overwritten with the symbolic link copied from the source side.

If you are uncertain as to what exactly to do or if you are afraid of data loss use the `-p' option and make sure that no important files get supplanted with faulty version.

Generally, and for data safety, it always appears to be a good idea to have the `-l' option set on the command line, unless, of course, you really don't want to have symbolic links copied.

Finally, it shall be mentioned that hard links, as they always refer to another file's inode by concept, are, as of this usbsync version, perceived as the file itself. Future releases will support hard link preservation also.

FILES

.usbsync: File on storage volume that gives the usbsync program information about file or directory correspondences. See usbsync(5) for further details.

BUGS

There might be certain scenarious in which usbsync as a program yields an unexpected result or behaves strangely. According to the paradigm of constantly improving this piece of software you may hereby be highly encouraged to report any bug you encounter to the AUTHOR.

A bug report should simply contain a short description that points out in which particual situation the bug occurred and how it can be reproduced. Please do also including the concering termincal output if possible. Furthermore, if usbsync exits with an error code, this should also be given.

AUTHOR

GNU usbsync as well as this manual page have been written by
Soeren Wellhoefer <soeren.wellhoefer@gmx.net>

HISTORY

Usbsync, as the program name suggests, has been intentionally written to be used in connection with some sort of usb flash drive in order to have a permanent and portable data device to synchronized data with; although, any other mass storage device would equally fit its purpose.

This document was created by man2html, using the manual pages.
Time: 20:39:03 GMT, May 29, 2009