In the top-level directory of any storage volume (the directory where the volume is mounted, /media/volume, for instance) a file by the default name of .usbsync may be placed.
Generally, this file supplies the usbsync(1) program with specific information about which files and directories on the storage volume and on arbitrarily many hosts are to be kept synchronized against each other.
In more detail this means that this file allows a user to define certain file and directory correspondences in such a way, that a file or directory on the storage volume always matches one or more other files or directories on one of the hosts given by name and user.
In case you are just interested in seeing some examples of .usbsync files at work you may skip the following two sections and continue reading below in the EXAMPLES section.
The first two sections are file or directory specifications, whereas the last optional section allows for certain advanced settings (see SECTIONS OF A SYNCHRONIZATION ENTRY below).
Blank and comment lines are allowed and are simply skipped. A line is considered a comment if the first printable character encountered on that line is the POUND SIGN '#' character. Comments appended to the end of any other line are not permitted. You may make use of indentations by applying tab and/or white space characters.
This section specifies either one single file or a single directory on the storage volume. The path format given must be a relative path; relative to the top-level directory of the mass storage volume. The format thus looks like the following:
foo/bar/baz
If you intend to synchronize all files and directories on the storage volume with some arbitrary host location, you may specify a PERIOD `.' in this section.
A line of this section defines a file or directory correspondence for a specific host and a specific user on that host by giving a host-user combination (user and host separated by an AT '@') and an absolute path (beginning with a SLASH '/') to a file or a directory (separated by a COLON ':'). The absolute path may alternatively start with a TILDE '~' character to denote the home directory of the user named on the same line. A typical line of this section migh thus look like the following schematic:
user@host:/foo/bar/baz
Dublications in this section are not checked for; although, they make less sense in the applied context and should therefore be avoided.
Giving this section, however, bears the intention of offering advanced options modifying the synchronization process indicated by this particular synchronization entry. Currently, there are only two related features supported. More will be added in subsequent versions of usbsync.
One of the features makes it possible to specify certain file name prefices that should be ignored during the synchronization process of a particual synchronization entry. Analogously, the second features allows to specify certain file name suffices that should be ignored.
The format consists of an identifier keyword followed by a comma-separated list of prefices/suffices given in double quotation marks; identifier and list are separated by a colon.
The keyword for the first feature is ignore_file_prefix, whereas it is ignore_file_suffix, for the second feature. Examples are thus given for both:
ignore_file_prefix: ".", "win_" ignore_file_suffix: ".bat", ".win", ".txt", "sfix", "~"
Arbitrarily many white spaces may be inserted between the identifier, on either side of the colon, and between the commas of the prefix/suffix list.
A suffix always ignored is `.ubs' as it represents the ending of a usbsync backup file.
Since usbsync 0.2 it is possible to append one or more optional section modifiers to Section One of a synchronization entry. Section modifiers should be thought of as optional switches that change how certain data-related tasks are handled.
A section modifier occuppies a whole line and starts with a PLUS '+' character followed by a unique identifier.
The following provides a list of applicable section modifiers. As some section modifiers have an influence over others these should be given first; hence, a strict order must be maintained in some cases.
A few words shall be said about the actual process of synchronizing, that is, how certain scenarios are dealt with by the usbsync program.
Upon invoking the usbsync program with the appropriate command line arguments, at least one of the the components of a file or directory correspondence (the file or directory in Section One OR the file or directory in Section Two ) must needs to exist. In other words, if the file or the directory from Section One does not exist the file or the directory in Section Two must exist and vice versa.
When updating files and directories (essentially copying, creating or updating them) the ownership of a particular file or directory is set to the user id and the primary group id of the user specified in Section Two; that is, to whom the particular file or directory is assigned to belong to on the host given in the same context. Moreover, the permission bits of the more recent file or directory are copied likewise.
It might well be that the file system used on the storage volume does not support the Unix concept of neither file ownership nor permission bits (e.g. vfat). In this case file owner as well as permission bits are assumed to be those assigned to all file and directory objects on the storage volume by the sytem when mounting. If not willingly changed, default file owner and permission bits may vary on different system and according to the circumstances; they can however be generally obtained by inspecting the /etc/mtab (see mtab(5) for details) file.
If no permission bits could be retrieved at all, all newly created files and directories are masked with whatever is set in the current shell environment by the umask(1) command which in most shells defaults to 0022.
It is furthermore noteworthy that only the modification time (mtime) plays the crucial role in deciding how to synchronize; the access time (atime) is neglected as it only describes when a file was last accessed, not when any changes were made to it.
If a file was given in Section One (see Section One above), Section Two is required to also specify the path to one or more corresponding files of the same or of a different file name.
It should have been made clear in the sections prior, that, in case of a file given in Section One, specifying multiple lines of file correspondences in Section Two is intended for matching the single file of Section One with another file on each of the hosts specified in Section Two. These are then kept synchronized when running usbsync.
If a directory was specified in Section One of a synchronization entry (see Section One above), Section Two must also specify at least one or more directories of the same or of a different name.
The synchronization of a directory is handled in two distinct stages: The first stage essentially bears the significance of simply creating a directory if it did not exist before; whereas, the second stage means to "update" the directory. The latter task is performed at the very end of a synchronization session (a run of the usbsync program) and implies to set the the update time (modification time), permission bits, and the owner of the directory in question.
Directories are recursively kept synchronized with their counterparts on the storage volume or on one of the hosts given.
Consequently, this means that the entire directory tree with all its files and sub-directories will be fully maintained on both, the mass storage volume as well as on the hosts specified in Section Two. All original sub-directory names as well as any file name within the directory that is being synchronized will remain unaltered; this holds true for any sub-directory level or depth.
If you would like to only synchronize the directory tree up to a certain sub-directory level you may use the `-d` option of the usbsync progam (see usbsync(1) for details).
Concludingly, it is to be kept in mind that synchronizing the mere object of a directory, that is, not taking into account any of its contents at any sub-level, is for one thing equivalent to creating the directory in case it should not exist, and for another thing equivalent to setting the directory's modification time to that of its more recent counterpart against which it is to be synchronized.
... ## Sample synchronization entry ## ## Storage volume synchronization file or directory: # Directory or file to be kept synchronized on storage volume. # Path is relative to `.usbsync', that is, to the top-level # directory of the storage volume. directory_on_volume/subdirectory ## Associative file or directory on local machine # Directory or file to be kept synchronized on volume # Path is absolute or prefixed with `~'. The latter one # denotes the home directory of the user given on the # same line. user1@host1:/home/user1/some_directory user2@host1:/home/user2/some_directory user1@host2:/usr/share/somedir/other_dir ## Optional section # This optional section specifies which file pre- and/or # suffices should be ignored when synchronizing. ignore_file_prefix: ".", "test_" ignore_file_suffix: ".win", ".bat", ".txt", ".bak", "~" ## End of sample synchronization entry ## ...
A more real-world example shall be given next. It illustrates the use of multiple synchronization entries in a single .usbsync file. For the purpose of clarity, it is generally recommended to mark the beginning of each synchronization entry through the use of appropriate comments.
Imagine someone by the name of Mark who employs a carry-around usb flash drive with the purpose of having all of his most recent data always with him. He chooses to use usbsync(1) to easily accomplish the task and thereby have all his data with him at the various hosts he might happen to work at.
Mark's .usbsync file in his storage volume's top-level directory might thus look like the following:
... ## Mark's personal documents mark/docs mark@home:~/documents/personal mark@office:~/docs/personal ignore_file_suffix: ".doc", ".xls", ".ppt" ## Mark's picture of his girlfriend Marry pics/mylove.jpg mark@home:~/pictures/september_08/dcm2412.jpg marry@computer:~/data/images/general/me.jpg ## Mark's current work project named "project1" ## The project data is compressed in order to save volume space projects/project1 +zlib_compression +tape_archive mark@home:~/projects/project1 mark@office:/usr/share/projects/mark/project1 frank@other:~/projects/project1/mark ignore_file_prefix: "test_", "backup_" ignore_file_suffix: "~", ".bak" ## Mark's promotional letter promotional_letter.odt mark@home:~/documents/work/promotional_letter.odt ...
Now Mark is able to simply invoke usbsync at each of the hosts he happens to be at - presuming it is installed there. By simply passing his usb flash drive's mount point to usbsync on the command line it will take care of properly exchanging the most recent data and thereby keeping everything in synchronization.
The examples given above should sufficiently satisfy the purpose of summarizing the key concepts described in this manual.