Beratung und Softwareentwicklung aus einer Hand




 ssync - synchronize two or more sites and report conflicts.

NAME

ssync - synchronize two or more sites and report conflicts.

SYNOPSIS

    ssync [options] [command] [args...]
     Options:
       --help               brief help message
       --verbose            increase verbosity level
       --quiet              no verbosity output (level = 0)
       --version            print version and exit
       --dry-run            only print what will be done.
       --safe-run           make a dry-run first. If sucessfull, 
                            then really do it without dry-run.
     Commands:
       setup                prepare the current directory as a site
       clone <parent>       create a new clone of the parent
       sync                 synchronize this site with parent
       pull                 pull changes from server into this site
       push                 push this site to parent
       remove-stale-lock    remove a stale lock on the parent
       delete-unwanted      delete all unwanted files in all subdirectories

OPTIONS

--help
Print a brief help message and exits.

--verbose
Increase the verbosity level. You can give this multiple times for more log messages.

--quiet
Suppress any log messages.

--version
Print version and exit.

--dry-run
Only print, what will be done. Change nothing on parent or local.

--dir=directory
Will use ``directory'' as the base directory of the site.

--safe-run
Make a first with ``--dry-run''. If this runs without any errors, then repeat the whole operation without dry-run. If the first run encounters an error, then don't make a second run.

Commands

setup
This will prepare the current directory as a site which could be used for synchronisation. This will basically only create a few files inside the subdirectory ``SSYNC''. Use this when starting a new site.

clone parent
Create a new site by cloning from the given master repository.

sync
Synchronize this directory with the master repository by first doing a ``pull'' and then doing a ``push''.

pull
Pull all changes from the master repository into this directory and look for conflicts.

push
Push the current directory to the master.

remove-stale-lock
Remove a stale lock still locking the parent. Use with care!

delete-unwanted
Delete all unwanted files in the current directory and all subdirectories. Unwanted files are files ending with ``~'' or empty directories.

Special modes

options
Options for the program can be stored in SSYNC/options.

If you insert ``tar.gz'' in that file, then ssync will store a huge ssync.tar.gz on the parent instead of the many single files. The advantage is, that you can save some disk space on the parent but network transports will probably be slower, because rsync will see many changes, because of the compression.

If you insert ``mirror-of-parent-dir=ABSDIRECTORY'' then the mirror directory will not be put at the default location but at the given location (Win: ``mirror-of-parent-dir=c:\temp'', Unix: ``mirror-of-parent-dir=/tmp''). ABSDIRECTORY must be an absolute directory.

DESCRIPTION

ssync will synchronize the content of a directory between one or more ``sites'' by using rsync as the basic transport mechanism. This is similar to an rsync update to and from the second site, but ssync will be able to detect conflicts resulting from changes occuring on both sites.

A site is a single computer system containing the full set of files of the directory to be synchronized. With ssync you will be able to change, delete or create files at every site without the need to have a permanent network connection in order to synchronize the sites immediately. Instead one or more persons would work in parallel at one or more sites and they would call ssync to synchronize the contents of these various sites.

Each site has exactly one parent site with which this site is synchronized. A parent site has normallty many children sites, so that all children synchronize to a common parent directory. You can use build arbitrary relations between sites as long as each site has only a single parent.

A common approach would be to have a master parent site (M) and many children sites (A, B, C...), which all synchronize to this master site.

Changes from each child site (e.g. A) would be synchronized to M with a call to ssync. Also, all changes which other sites have already synchronized to M would be synchronized to A. If the next site (e.g. B) will call ssync then the content of M will be sent to B and therefore the changes of A will be transfered to B.

In contrast to rsync, we will be able to detect conflicts and report them to the user. A conflict would be if two users changed the same file or one user changed a file and another user deleted it. There are more potential conflicts.

If no conflicts occur, then all changes of the local site will be transfered to the parent site and all changes found on the parent site will be incorporated into this site.

Whenever a conflict is detected during synchronisation a message will be printed to inform the user of the type of conflict. E.g. a conflict could occur because a file is changed on both sides and afterwards doing a synchronisation. Another case is deleting a file on one side and changing it on the other side.

Howto start using ssync

First create an directory containing some files which will build site ``M''.

    shell% cd $HOME
    shell% mkdir site-m
    shell% cd site-m
    shell% echo hallo > file1
    shell% ssync setup

Synchonizing through the filesystem

We start by synchronizing two sites residing on the same computer. Therefore we don not need to use a rsync server. The sites may be stored on a network file system like NFS but this is transparent to the application.

Start by making a clone of the original site ``M'':

    shell% cd $HOME
    shell% mkdir site-a
    shell% cd site-a
    shell% ssync clone $HOME/site-m
    shell% ls
    SSYNC  file1
    shell% cat file1
    hallo
    shell%

You will see the new site ``A'' which is a clone of ``M''. Whenever something inside ``A'' or ``M'' will be changed, it will be synchonized. Let's change something inside ``A'':

    shell% echo world > file2

And start a synchonisation with:

    shell% ssync
    Syncing with parent site, please don't abort....
    PUSH(NEW) file2
    no conflicts found.
    shell%

The newly created file2 is sent to the parent site ``M'' and vice versa.

Let's change something inside ``M'':

    shell% cd $HOME/site-m
    shell% echo goodbye > file1

And start a synchonisation (in ``A''!) with:

    shell% cd $HOME/site-a
    shell% ssync
    Syncing with parent site, please don't abort....
    PULL      file1
    no conflicts found.
    shell%

The changes in file1 are pulled from the parent site ``M''.

Resolving conflicts

Now let's see what happens, if a file is changed in both sites at the same time.

    shell% cd $HOME/site-m
    shell% echo cruel world > file2
    shell% cd $HOME/site-a
    shell% echo happy world > file2
    shell% ssync
    Syncing with parent site, please don't abort....
    CONFLICT: The file "file2" has been changed on the parent (Thu Mar 17
    14:12:23 2005) and has been changed by you (Thu Mar 17 14:12:32 2005).
    1 conflicts found (details in ./SSYNC/conflicts.log).
    Please fix all conflicts and do "ssync push" afterwards.

Now you have to manually decide which version is correct by looking at both files. The file of the site ``A'' is found in ``site-a/file2'' whereas the conflicting file from the parent site is found in ``site-a/SSYNC/file2-from-parent-changed-by-both''. Put the correct file to ``site-a/file2'' and make

    shell% ssync push

Synchronizing through a rsync server over a slow network

If two sites are connected through a slow network then use the rsync program as the underlying transport. Theoretically you could use a network file system but this is very slow over slow links.

To use this method, you must setup an rsync server for a particular directory which will be used as a parent site. e.g. enter the following into /etc/rsyncd.conf

    [site]
        path = /home/user/site-m
        comment = ssync site "M"

Then you could make an arbitrary number of clones of this master site by using the command ``clone'' and giving the name of the master site ``M'':

ssync clone localhost::site

After working in the cloned directory. You could use the command ``sync'' to synchronize your work with the master repository:

ssync

Difference to other synchronization methods.

The approach of ssync has advantages and disadvantages. This section will compare ssync to other synchronization methods.

Version Control Systems (CVS, BitKeeper,...)

A version control system (VCS) has the ability to record the history of changes of each file. Apart from that it is able to synchronize many parallel changes by either serializing them (strict locking) or merging changes.

All VCS are normally used to program source codes and could handle text files quite efficient. However, they have big problems handling binary files where no automatic merge is possible. They also need to know which files to manage and which not. For a large number of files in many directories this could be quite hard.

Only a few VCSs (CVS, BitKeeper) have the ability to work with various sites which share no common filesystem. While CVS is free, it has several disadvantages mainly in command handling, network usage, and using binary files. BitKeeper is better than CVS, but is still complicated when dealing with many files and it is quite expensive.

ssync has no history of changes associated with each file. It does not merge text or binary files during conflicts. Instead it shows the file from the parent site together with the file of the local site. It is up to the user to choose which file to use. But ssync is very efficient in terms of network usage (fast on slow links). It does not need the user to tell the system which files to synchronize. Instead it takes the given directory and synchronizes each file in the directory with the parent site (and vice versa).

Network file systems

Using a network file system in which all users work would be an alternative to using ssync. But in many cases this is not an available option especially when syncing distributed sites.

Groupware

Some groupware tools offer to exchange files between distributed sites. When used through a web interface, they could be widely used but are very unhandy. Special groupware (like Lotus Notes) is generally not available.

When to use ssync?

You probably want to use ssync for managing distributed sites connected with a slow and only temporary network. There is no need to stay connected in order to work with the managed files.

If you need the history of changes, then you probably want to use a VCS, like CVS or BitKeeper. If you only need the most current version then ssync would probably be ok.

If you work mostly with binary files, then using a version control could be quite inefficient. In this cases you may want to use ssync.

Examples of usage

Use ssync to synchronize your web pages to your internet service provider (ISP). You are able to change the pages there and synchronize them back.

Use ssync to synchronize a bunch of office documents between various sites. E.g. if you write some documents at work and at home but you want them to synchronize then ssync could be of help.

Supported Platforms

ssync is known to work on Windows NT 4, XP and Linux. But it is expected to run on any platform supporting perl 5.

Windows problems

ssync uses two important external programs: gzip and rsync version 2.5.2 or newer. These programs can be found on any newer Linux distribution but are hard to get for Windows. At the time of writing (2005-02-28) I tried several rsync programs for Windows but only http://www.tiarnan.phlegethon.org/rsyncntdoc.html worked. I was unsucessfull with cwRsync (http://www.itefix.no/cwrsync) and various other cygwin based rsyncs. There seems to be a major breakdown described at http://sources.redhat.com/ml/cygwin/2002-09/msg01155.html.

You can find the working copy of this rsync program in the contrib subdirectory of ssync.

Gzip is best taken from http://prdownloads.sourceforge.net/gnuwin32/gzip-1.3.5-bin.zip

Tar is best taken from http://prdownloads.sourceforge.net/gnuwin32/tar-1.13-1-bin.zip

If you encounter a ``failed to set permissions on LOCKS : Permission denied'' then set the environment variable ``SET CYGWIN=nontsec''

Download

You can download ssync from http://www.reinform.de/download

License

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

Copyright

Copyright (C) 2002,2003 Tilmann Bubeck.

Dr. Tilmann Bubeck, Widmaierstr. 58, 70567 Stuttgart, GERMANY

t.bubeck@reinform.de

 ssync - synchronize two or more sites and report conflicts.


reinform medien- und informationstechnologie AG
Löffelstrasse 40, 70597 Stuttgart, Germany
Fon: +49 (711) 75 86 56-10
Fax: +49 (711) 75 86 56-29