
About csync2
============

Csync2 is a cluster synchronization tool. It can be used to keep files on
multiple hosts in a cluster in sync. Csync2 can handle complex setups with
much more than just 2 hosts, handle file deletions and can detect conflicts.

It is expedient for HA-clusters, HPC-clusters, COWs and server farms. If
you are looking for a tool to sync your laptop with your workstation, you
better have a look at Unison (http://www.cis.upenn.edu/~bcpierce/unison/)
too.

See http://oss.linbit.com/ for more information on csync2. The csync2
subversion tree can be found at http://svn.clifford.at/csync2/.


Copyright
=========

csync2 - cluster synchronization tool, 2nd generation
LINBIT Information Technologies GmbH <http://www.linbit.com>
Copyright (C) 2004, 2005  Clifford Wolf <clifford@clifford.at>

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


Installing csync2
=================

Requirements:

	- A linux system (or more/less compatible os)
	- The librsync package (incl. dev headers, at least version 0.9.5)
	- The sqlite package (incl. dev headers, at least version 2.8.13)

Build and install the binaries using:

	./configure
	make install

Create and install an OpenSSL private key and certificate:

	make cert

Add the csync2 port to your /etc/services file:

	csync2	30865/tcp

Add csync2 to your /etc/inetd.conf file:

	csync2 stream tcp nowait root /usr/local/sbin/csync2 csync2 -i

Create your /etc/csync2.cfg and restart inetd.

Maybe you also want to add csync2_locheck.sh to your /root/.bash_logout
file to make sure that you never logout without syncing your changes.


csync2.cfg syntax
=================

The config file contains the definitions for all the synchronization
groups in the cluster:

--snip--

group mygroup
{
	host host1 host2 host3;
	host (host4@host4-eth2);

	key /etc/csync2.key_mygroup;

	include /etc/apache;
	include %homedir%/bob;
	exclude %homedir%/bob/temp;
	exclude *~ .*;

	action {
		pattern /etc/apache/httpd.conf;
		pattern /etc/apache/sites-available/*;
		exec "/usr/sbin/apache2ctl graceful";
		logfile "/var/log/csync2_action.log";
		do-local;
	}

	auto none;
}

prefix homedir
{
	on host[12]:
		/users;
	on *:
		/home;
}

nossl host2 host3;
nossl host3 host2;

config /etc/csync2.cfg_anotherone;
config /etc/csync2.cfg_foo /etc/csync2.cfg_bar;

--snap--

The host statement adds the hosts. Note that the names used here must
equal to the output of "hostname". If the hostname used for communication
is different from the output of the "hostname" command (e.g. if a
crossover cable with other IP addresses should be used), the syntax
"hostname@hostname-for-communication" can be used.

Hosts in parenthesis are slave hosts. They accept updates from the other hosts
but are not allowed to send updates themself.

The key statement must be used exactly once in each group and defines
the file containing shared secret for that group. The keyfile can be
created using "csync2 -k keyfilename".

The include and exclude pattern are a bit more complex. There are two
kind of patterns: pathname-patterns starting with a slash character and
basename patterns which do not.

The last matching pattern for each of both categories is choosen. If
both categories match, the file will be synchonized.

The config keyword can be used to include another config file in this one.

Additionally a group can have action sections. Each action section has a
list of patterns and a list of commands. If any of the patterns do match
an updated file, the commands will be executed. On default, the ouput of
the commands is sent to /dev/null, however: A logfile can be specified. If
the keyword "do-local" is present in the action section, the command will
also be executed on the machine where the change has happened locally. If
the special token "%%" is present in the command text, it will be replaced
by a list of the updated files.

When different directories should be synced (e.g. /home and /users), a prefix
must be used. The syntax "%prefixname%" can be used in include and exclude
rules to refer to a prefix section. The real path for each host is then
specified in the seperate prefix section.

Usually the hosts are communicating using ssl. The nossl statement can be used
to force a communication tunnel between two hosts to be unencrypted. The 1st
(left) parameter is a shell pattern which must match the client (initiator)
hostname and the 2nd (right) parameter a shell pattern which must match the
server (responder) interfacename. If all communication should be unencrypted,
a simple "nossl * *;" is sufficient. If e.g. all interfaces for direct links
between hosts do have the suffix "-x", the statement "nossl * *-x;" will cause
all communication on such interfaces to be unencrypted.

If a file is modified on more than one host, a conflict is detected and an
administrator must resolve this conflist manually using 'csync2 -f'.  The
'auto' keyword can be used to enable an automatic conflict resolving algorithm.
The available algorithms are: 'none' (the default behavior), 'first' (the host
on which 'csync2' is executed first wins), 'younger' and 'older' (the younger
or older file wins), 'bigger' and 'smaller' (the bigger or smaller file wins),
'left' and 'right' (the host on the left side or the right side in the host
list wins). The 'younger', 'older', 'bigger' and 'smaller' test also fail if
the file has been removed on the local side.

You might want to run "csync2 -R" after excluding files or hosts from the
config file. This will check the database and remove the old entries which are
not matched by the config file anymore. Without that, those database entries
would ligger around forever.

It is also possible to have multiple configurations in parallel. A
configuration named 'foobar' may be stored in /etc/csync2_foobar.cfg and is
used whenever csync2 is called with the option "-C foobar". Each configuration
has it's own backend database. So splitting up the setups into various small
configurations can speed up operation and avoid problems with database locks.

In some situations it is not wanted to sync file permissions. The gloabal
config file statements "ignore uid;", "ignore gid;" and "ignore mod;" may
be used to tell csync2 to not care about those file properties.


The synchronization method
==========================

Csync2 manages a database on evert host which holds some state information
about this hosts filesystem. Whenever a file is changed, the check run (-c)
will compare the local filesystem with this database. Changes is the local
filesystem are detected and scheduled for beeing pushed to the peer nodes.

In the update run (-u) all locally scheduled files are beeing synced to the
peers using an rsync-like protocol. If the file has also been modified on the
peer, csync2 will detect this synchronization conflict and output an error
message, leaving it to the administrator to resolve the conflict.


Using csync2
============

Simply calling csync2 without any parameters prints out a brief usage
info. Running "csync2 -x" will sync local changes to the other hosts.

If not instructed otherwise, the default configuration, /etc/csync2.cfg
is used. If csync2 is called with "-C foo", the configuration file
/etc/csync2_foo.cfg is used instead.

On default all groups in the active configuration are processed. This can
be changed using the -G option. Simply pass -G a comma-seperated list of
group names and all other groups will be ignored.

Csync2 has three main modes:

* Hint Mode (-h)

	The hint mode does nothing impressive. It simply adds it's file
	parameters to the hint database which is later on processed by -c.

	This is usefull for environments where "csync2 -c" and "csync2 -u"
	are automatically run by a cron job.

* Check Mode (-c)

	Checks for local changes and queues them for later updating on remote
	hosts. If calles without file parameters, the entries from the hint
	database are used. Otherwise the given files and directories are
	checked.

* Update Mode (-u)

	Actually runs the updates on the peer nodes.

Sorry, the rest of this section still needs to be written.


The database backend
====================

Sometimes it is neccessary to connect to the database backend. The
sqlite command-line tool is needed to open the database:

	# sqlite /var/lib/csync2/$HOSTNAME.db

This opens up an SQL shell where you can access the database using
standard SQL queries. Over time the database may get fragmented or
have big holes in it if many records are removed. This may slow down
the database and can be fixed by running the VACUUM command on the
database:

	# sqlite /var/lib/csync2/$HOSTNAME.db vacuum

The VACUUM command cleans the database by copying its contents to a
temporary database file and reloading the original database file from
the copy.

Especially consider running the VACUUM command after removing many files
from a config (after you did run "csync2 -R").


Bootstrapping large setups
==========================

Usually when you are running csync2 the first time after adding files
to the configuration, csync2 will detect that files as new and add them
to the dirty database. When running the first update, those files are
silently removed from the dirty DB if they exist already on the peer.

In large setups this is a significant overhead. So you might instead
choose to sync the files somehow else (e.g. using rsync) in the first
place and then just add them to the local database without adding them
to the dirty table. This can be done by running "csyncs2 -crI /".

But use the -I option with care! If the files on the machines are not
in sync, they won't be synced atomatically by csync2 because they are
not mentioned in the dirty table!

The test mode -T also supports the -I modifier - But here it has the
opposite effect. While -T is usually only good for diagnostic purposes,
it automatically creates entries in the dirty DB for unsynced files when
running with the -I modifier.

Sometimes it is usefull to disable the entire csync2 system on a node (e.g.
for preparing new files for a cluster-wide update). This can be done by
creating a file /etc/csync2.lock. When such a file exists, csync2 will
simply refuse to start.

