lsyncd/manual/config/layer4/index.md

layout	title	short
default	Config Layer 4: Default Config	Config Layer 4

You can simply choose from a set of three default implementations which are: rsync, rsyncssh and direct.

To sync a local directory using the default rsync behavior, just add this to a config file:

{% highlight lua %} sync { default.rsync, source = "DIRNAME", target = "DIRNAME" } {% endhighlight %}

The order of the arguments is of no importance. If target is a local directory, take care that it is an absolute pathname. You can add multiple syncs that way. The source directories may be identical or differ without problems. source is an universal parameter that must be given for every sync. All other sync parameters can differ depending on the behavior selected. Optionally you can override the default or settings values maxDelays or maxProcesses per Sync.

One can also skip the initial rsync process by setting the default init function to false:

{% highlight lua %} sync { default.rsync, source = "DIRNAME", target = "DIRNAME", init = false } {% endhighlight %}

This is an optimization which can be dangerous; so, please use it only if you are sure that source and target are synchronized when Lsyncd is started.

The default behaviors you can select from are following:

default.rsync

The default rsync configuration will aggregate events up to delay seconds or 1000 separate uncollapsible events, which ever happens first. Then it will spawn one Rsync with a filter of all files that changed. The filter list is transmitted to Rsync trough a pipe. A call from Lsyncd to Rsync will thus look like this:

{% highlight shell %} /usr/bin/rsync -ltsd --delete --include-from=- --exclude=* SOURCE TARGET {% endhighlight %}

You can change the options Rsync is called and the Rsync binary that is call with the rsync parameter.

Example:

{% highlight lua %} sync { default.rsync, source = "/home/user/src/", target = "foohost.com:~/trg/", delay = 15, rsync = { binary = "/usr/local/bin/rsync", archive = true, compress = true } } {% endhighlight %}

Below is a table of options for the rsync parameter. Please have a look at the Rsync documentation for an in depth explanation.

acls	=	true
binary	=	FILENAME	Lsyncd calls this binary as rsync (default: /usr/bin/rsync)
checksum	=	true
chown	=	USER:GROUP	(Lsyncd >= 2.1.7)
compress	=	true
copy_dirlinks	=	true	(Lsyncd >= 2.1.7)
copy_links	=	true
cvs_exclude	=	true
dry_run	=	true
exclude	=	PATTERN	TABLE of PATTERNs also allowed
excludeFrom	=	FILENAME
executability	=	true
existing	=	true	(Lsyncd >= 2.1.7)
hard_links	=	true
ignore_times	=	true
inplace	=	true	(Lsyncd >= 2.1.6)
ipv4	=	true
ipv6	=	true
links	=	true	(set by Lsyncd by default)
one_file_system	=	true
owner	=	true
password_file	=	FILENAME	(Lsyncd >= 2.1.2)
perms	=	true
protect_args	=	true	(set by Lsyncd by default)
prune_empty_dirs	=	true
quiet	=	true
rsh	=	COMMAND
rsync_path	=	PATH	(path to rsync on remote host)
sparse	=	true
temp_dir	=	DIR
times	=	true	(set by Lsyncd by default)
update	=	true
verbose	=	true
whole_file	=	true
xattrs	=	true
_extra	=	TABLE of STRINGS.	If absolutely needed, additional arguments can be specified as a TABLE of STRINGS(example: { "--omit-dir-times", "--omit-link-times" }). Note that the underscore highlights this as workaround. If you need something that is not covered by the above options, please request it via a feature request on the project website. Most notably, do not add -r for recursive or -a which implies recursive, since Lsyncd will handle that by itself. Additionally do not add -R for relative, which will ruin Lsyncd <-> Rsync communication.

default.rsyncssh

This configuration differs from the standard rsync configuration in that it uses ssh commands to move files or directories locally at the target host instead of deleting and transferring again. This configuration does spawn Rsync processes like default.rsync but additionally will spawn /usr/bin/ssh HOST mv ORIGIN DESTINATION commands.

Different to default.rsync it does not take an uniform target parameter, but needs host and targetdir separated.

Rsync's options can be changed with the rsync parameter like in default.rsync described above.

Additional to that ssh can be configured via the ssh parameter.

binary	=	FILENAME	Lsyncd calls this binary as ssh (default: /usr/bin/ssh)
port	=	PORT	Adds --port=PORT to the ssh call.
_extra	=	STRING TABLE	Similar to rsync._extra this can be used as quick workaround if absolutely needed.

Example:

{% highlight lua %} settings { logfile = "/var/log/lsyncd.log", statusFile = "/var/log/lsyncd-status.log", statusInterval = 20 }

sync { default.rsyncssh, source="/srcdir", host="remotehost", excludeFrom="/etc/lsyncd.exclude", targetdir="/dstdir", rsync = { archive = true, compress = false, whole_file = false }, ssh = { port = 1234 } } {% endhighlight %}

Please note the comma between the rsync parameter set and the ssh parameter set.

Caution If you are upgrading from 2.0.x, please notice that settings became a function from a variable, so you MUST delete the equal sign '=' between settings and the {.

Lsyncd will call xargs on the remote host to handle multiple tasks in a single connection. Xargs options can be specified by, just guessed it, the xargs parameter.

binary	=	FILENAME	Lsyncd calls this binary as xargs on the remote host (default: /usr/bin/xargs)
delimiter	=	DELIMITER	delimiting character to separate filenames. By default the 0 character is used. Very old holds may need newline instead.
_extra	=	STRING TABLE	By default { '-0', 'rm -rf' }. Remove the -0 if you chose newline delimiter instead. Otherwise leave it as is.

Example:

{% highlight lua %} sync { default.rsyncssh, source = "/home/user/src/", host = "foohost.com", targetdir = "~/trg/", } {% endhighlight %}

default.direct

Default.direct can be used to keep two local directories in sync with better performance than using default.rsync. Default.direct uses (just like default.rsync) rsync on startup to initially synchronize the target directory with the source directory. However, during normal operation default.direct uses /bin/cp, /bin/rm and /bin/mv to keep the synchronization. All parameters are just like default.rsync.

Example:

{% highlight lua %} sync { default.direct, source = "/home/user/src/", target = "/home/user/trg/" } {% endhighlight %}

Exclusions

Two additional parameters can be specified to sync{}:

excludeFrom	=	FILENAME	loads exclusion rules from this file, on rule per line
exclude	=	LIST	loads exclusion rules from this list of strings

Exclusion rules are modeled after rsync's exclusion patterns but are a bit simpler. Lsyncd supports these features:

• Generally if any part of the pathname (see below Layer 3) of an event matches the text, it is excluded. E.g. the file "/bin/foo/bar" matches the rule "foo".
• If the rule starts with a slash, it will only be matched at the beginning of the pathname
• If the rule ends with a slash, it will only be matched at the end of a pathname
• ? matches any character that is not a slash.
• * matches zero or more characters that are not a slash
• ** matches zero or more characters, this can be slashes.

Example:

{% highlight lua %} sync { default.rsync, source = "/home/user/src/", targetdir = "/home/user/dst/", exclude = { '.bak' , '.tmp' } } {% endhighlight %}

Deletions

By default Lsyncd will delete files on the target that are not present at the source since this is a fundamental part of the idea of keeping the target in sync with the source. However, many users requested exceptions for this, for various reasons, so all default implementations take delete as an additional parameter.

Valid values for delete are:

delete	=	true	Default. Lsyncd will delete on the target whatever is not in the source. At startup and what's being deleted during normal operation.
delete	=	false	Lsyncd will not delete any files on the target. Not on startup nor on normal operation. (Overwrites are possible though)
delete	=	'startup'	Lsyncd will delete files on the target when it starts up but not on normal operation.
delete	=	'running'	Lsyncd will not delete files on the target when it starts up but will delete those that are removed during normal operation.