move docs from gh-pages into src folder to keep it easier in sync

stable-2.2
Daniel Poelzleithner 7 months ago
parent 2841ef8528
commit 0de678ab3c

3
.gitignore vendored

@ -23,3 +23,6 @@ defaults.c
runner.c
result
tests/ssh
# docs cache
.jekyll-cache

@ -85,10 +85,18 @@ add_custom_command( OUTPUT defaults.out
# the manpage
add_custom_target( manpage
COMMAND ${CMAKE_COMMAND} -E echo "Updating the manpage"
COMMAND a2x --format=manpage doc/manpage/lsyncd.1.txt
DEPENDS doc/manpage/lsyncd.1.txt
COMMAND a2x --format=manpage docs/manpage/lsyncd.1.txt
DEPENDS docs/manpage/lsyncd.1.txt
)
# the html documention
add_custom_target( docs-html
COMMAND ${CMAKE_COMMAND} -E echo "Generate html documentation"
COMMAND jekyll build -s ${CMAKE_SOURCE_DIR}/docs/ -d html
DEPENDS ${CMAKE_SOURCE_DIR}/docs
)
# create_symlink( ${CMAKE_SOURCE_DIR}/tests tests)
ADD_CUSTOM_TARGET(prepare_tests ALL
COMMAND ${CMAKE_COMMAND} -E create_symlink ${CMAKE_SOURCE_DIR}/tests tests
@ -118,6 +126,6 @@ add_executable( lsyncd ${LSYNCD_SRC} )
target_link_libraries( lsyncd ${LUA_LIBRARIES} )
install( TARGETS lsyncd RUNTIME DESTINATION bin )
install( FILES doc/manpage/lsyncd.1 DESTINATION ${CMAKE_INSTALL_MANDIR}/man1 COMPONENT man )
install( FILES docs/manpage/lsyncd.1 DESTINATION ${CMAKE_INSTALL_MANDIR}/man1 COMPONENT man )
install( DIRECTORY examples DESTINATION doc )
install( DIRECTORY html DESTINATION doc OPTIONAL)

1
docs/.gitignore vendored

@ -0,0 +1 @@
_site/

@ -0,0 +1,4 @@
name: Lsyncd
markdown: kramdown
url : /lsyncd
baseurl : /lsyncd

@ -0,0 +1,19 @@
- title: Lsyncd
docs:
- /
- /download
- /help
- title: Manual
docs:
- /manual/building
- /manual/invoking
- /manual/config/file
- /manual/config/layer4
- /manual/config/layer3
- /manual/config/layer2
- /manual/config/layer1
- /manual/examples
- title: Appendices
docs:
- /faq
- /appendices/devdocs

@ -0,0 +1,77 @@
<!DOCTYPE html>
<html>
<head>
{% if page.url != "/" %}
<title>Lsyncd - {{ page.title }}</title>
{% else %}
<title>{{ page.title }}</title>
{% endif %}
<!-- link to main stylesheet -->
<link rel="stylesheet" type="text/css" href="{{ site.url }}/css/main.css">
<link rel="stylesheet" type="text/css" href="{{ site.url }}/css/syntax.css">
</head>
<body>
<div id="pillar">
<nav>
<div id="menu">
{% for section in site.data.docs %}
<h4>{{section.title}}</h4>
<ul>
{% for doc in section.docs %}
{% assign doc_url = doc %}
{% if doc_url != "/" %}
{% assign doc_url = doc | append: "/" %}
{% endif %}
{% assign p = site.pages | where:"url", doc_url | first %}
{% if page.tab %}
{% assign tab = page.tab | prepend:"/" | append:"/" %}
{% endif %}
{% if p.short %}
{% assign title = p.short %}
{% else %}
{% assign title = p.title %}
{% endif %}
<li><a {% if doc_url == page.url or doc_url == tab %}class="current"{% endif %} href="{{ site.url | append: p.url }}">{{ title }}</a></li>
{% endfor %}
</ul>
{% endfor %}
<div id="menufooter"></div>
</div>
<div id="ribbonwrap"><a href="https://github.com/axkibe/lsyncd" id="ribbon"></a></div>
</nav>
<div id="container">
<a href="https://github.com/axkibe/lsyncd/edit/gh-pages{{ page.url }}index.md" id="improvethis"></a>
<h1>{{ page.title }}</h1>
{{ content }}
{% assign docs = site.data.docs | map: 'docs' | join: ',' | split: ',' %}
{% for doc in docs %}
{% assign doc_url = doc %}
{% if doc_url != "/" %}
{% assign doc_url = doc_url | append: "/" %}
{% endif %}
{% if doc_url == page.url %}
<div id="footnav" class="prenext">
{% if forloop.first %}
{% else %}
{% assign previous = forloop.index0 | minus: 1 %}
{% assign previous_page = docs[previous] %}
<a href="{{ site.url | append: previous_page }}" class="prev"></a>
{% endif %}
{% if forloop.last %}
{% else %}
{% assign next = forloop.index0 | plus: 1 %}
{% assign next_page = docs[next] %}
<a href="{{ site.url | append: next_page }}" class="next"></a>
{% endif %}
</div>
<div class="clear"></div>
{% break %}
{% endif %}
{% endfor %}
</div>
</div>
</body>
</html>

@ -0,0 +1,78 @@
<!DOCTYPE html>
<html>
<head>
{% if page.url != "/" %}
<title>Lsyncd - {{ page.title }}</title>
{% else %}
<title>{{ page.title }}</title>
{% endif %}
<!-- link to main stylesheet -->
<link rel="stylesheet" type="text/css" href="{{ site.url }}/css/main.css">
<link rel="stylesheet" type="text/css" href="{{ site.url }}/css/syntax.css">
</head>
<body>
<div id="note3"><b>Note, this manual is for upcoming Lsyncd 3 and currently in development.</b></div>
<div id="pillar">
<nav>
<div id="menu">
{% for section in site.data.docs %}
<h4>{{section.title}}</h4>
<ul>
{% for doc in section.docs %}
{% assign doc_url = doc %}
{% if doc_url != "/" %}
{% assign doc_url = doc | append: "/" %}
{% endif %}
{% assign p = site.pages | where:"url", doc_url | first %}
{% if page.tab %}
{% assign tab = page.tab | prepend:"/" | append:"/" %}
{% endif %}
{% if p.short %}
{% assign title = p.short %}
{% else %}
{% assign title = p.title %}
{% endif %}
<li><a {% if doc_url == page.url or doc_url == tab %}class="current"{% endif %} href="{{ site.url | append: p.url }}">{{ title }}</a></li>
{% endfor %}
</ul>
{% endfor %}
<div id="menufooter"></div>
</div>
<div id="ribbonwrap"><a href="https://github.com/axkibe/lsyncd" id="ribbon"></a></div>
</nav>
<div id="container">
<a href="https://github.com/axkibe/lsyncd/edit/gh-pages{{ page.url }}index.md" id="improvethis"></a>
<h1>{{ page.title }}</h1>
{{ content }}
{% assign docs = site.data.docs | map: 'docs' | join: ',' | split: ',' %}
{% for doc in docs %}
{% assign doc_url = doc %}
{% if doc_url != "/" %}
{% assign doc_url = doc_url | append: "/" %}
{% endif %}
{% if doc_url == page.url %}
<div id="footnav" class="prenext">
{% if forloop.first %}
{% else %}
{% assign previous = forloop.index0 | minus: 1 %}
{% assign previous_page = docs[previous] %}
<a href="{{ site.url | append: previous_page }}" class="prev"></a>
{% endif %}
{% if forloop.last %}
{% else %}
{% assign next = forloop.index0 | plus: 1 %}
{% assign next_page = docs[next] %}
<a href="{{ site.url | append: next_page }}" class="next"></a>
{% endif %}
</div>
<div class="clear"></div>
{% break %}
{% endif %}
{% endfor %}
</div>
</div>
</body>
</html>

@ -0,0 +1,46 @@
---
layout: default
title: Developer Docs
short: Developer Docs
---
Code structure / Style guide
----------------------------
At large, Lsyncd's documentation contained in source code comments is well developed - at least compared to many other software projects. Here thus only a few outlining words.
Lsyncd 2 is partially written in C, partially written in Lua. For some code pieces it is a free decision in which it could be coded, but for most one of the two was more appropriate. Generally the goal was if there was no good reason to code something in C do it in Lua. The C core thus does all the stuff close to the operating system:
* inotify interface
* process management, zombie collection
* signals
* pipes
* logging (also in the core, so it can log itself comfortably)
* alarms (Lsyncd uses kernel jiffies as alarms, thus it should be year Y2K38 safe (2038 is the year in which an often used time measurement - seconds since 1970 - will overflow.)
Everything else is done in lsyncd.lua.
While Lua is not an object oriented language itself, it supplies a set of features which can emulate its features quite nicely. Shortly spoken, it supports prototyping. Lsyncd makes use of local function scoping to create blocks of code which are loosely connected with each other. A major feature of object oriented language.
A typical "class" in Lsyncd looks like this.
```Lua
MyClass = (function()
local private = "only visible here"
local function new()
return {foo="bar"}
end
-- public interface
return { new = new }
end)()
```
In plain interpretation this creates a global variable called "MyClass". It defines an unnamed function with internal variables and subfunctions. This functions returns a table of all functions that should be visible from the outside. Then the unnamed function is immediately called on the global definition of "MyClass" and the public interface table stored in "MyClass". {{{MyClass.new()}}} is then used to create objects of this class. Or if it is a "Singelton", it has no new function, but other functions, that would be considered "static" in an object oriented language.
Lua has developed a culture for personal adaption - "power patches". To not throw a stick into any package maintainer Lsyncd uses standard from the stock Lua (5.1).
One note about the style of sync{} configs. As you can see in Layer 4 configuration the configuration is selected by merely adding the configuration table as parameter. In the implementation it does nothing else than to take any value with a number as key and which has a table as value and copy all of its key/value entries that are not there already. This even works recursively if that config again imports another config.
Why Lua and not ...?
--------------------
Lua has been chosen for Lsyncd 2 much out of the same reasons why C was chosen for Lsyncd 1.x. Lsyncd should be small and fast and should come with as few as possible dependencies.
The move from a pure C implementation as in Lsyncd 1.x to using Lua was motivated by enhancing the configuration file format. XML was starting to get clunky for the requirements of Lsyncd. When used Lua bindings already for config file parsing, there was little reason not to move large parts of Lsyncd internal logic into Lua as well. With its garbage collector, memory management became much easier, and with its highly optimized tables as dictionaries, some things even become faster, as Lsyncd 1.x linearly traversed a lot of lists, while Lsyncd 2 uses Lua tables as hash tables everywhere.
Lua was chosen over other script languages not because I think Lua is the greatest thing on earth - like many coders think about their favorite language, but because it is considered to be a appropriate tool for this task. Many coders like [X] so much, they want to do everything with it, also because after a while they know [X] very well, and are of course faster in solving an issue than learning [Y]. I on the other hand didn't know Lua before Lsyncd 2 at all, and decided explicitly for it out of pragmatic reasons. First it is said have originated out of the need for configuration files for C applications. Much the use case Lsyncd needs. So the C interface is handy and fast. Since Lsyncd has its parts close to the system still coded in C this interfacing makes things easier. Lua is very fast. Without affronting other script languages one can say it is at least in the top tier regarding speed. It may be the fastest scripting language there is, but this statement might raise debates. But not without reason it got quite some attention from the gaming industry. It gets even faster with LuaJIT and it gets into the range of JavaJIT (which is a compiled and not a script language). Lua has also a very slim standard library, while this is a stopper for people just wanting to quickly write some script this plays into the hands of Lsyncd. It comes with little requirements on the machine to be installed and Lsyncd comes with its own custom core functionally anyway. And although the Lua syntax looks a bit dirty at first - like implicit on the fly creation of globals - with a little configuration this can be banned. Like Lsyncd does in normal operation modes.

@ -0,0 +1,257 @@
html {
height: 100%;
overflow-y: scroll;
}
body {
background-color: rgb( 245, 245, 245 );
font: 13px/1.4 Helvetica, arial, nimbussansl, liberationsans, freesans, clean, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
height: 100%;
margin: 0;
}
#pillar {
position: relative;
margin: 0 auto;
max-width: 70em;
min-height: 100%;
overflow: auto;
background-color: white;
padding: 0;
}
a:link, a:visited {
color: blue;
text-decoration: inherit;
}
a:hover {
text-decoration: underline;
}
nav {
background-color: rgb( 200, 200, 200 );
position : absolute;
right : 0;
padding: 0;
width: 11.1em;
bottom: 0;
top: 0;
margin: 0;
}
#menu {
background-color: rgba( 200, 200, 200, 0.95 );
z-index: 20;
position: relative;
margin: 0;
padding: 0;
width: 11.1em;
}
#menufooter {
position: absolute;
bottom: -2em;
height: 2em;
width: 11.1em;
background-color: transparent;
background-image: linear-gradient(to bottom, rgba(200, 200, 200, 0.95), rgba(200, 200, 200, 0));
pointer-events: none;
}
nav h4 {
border-bottom: 1px solid black;
padding-left: 1em;
margin-right: 1em;
font-size: 15px;
}
nav a {
display : block;
position : relative;
margin-left: 1em;
padding: 0.2em 0 0.2em 0;
font-size: 14px;
}
nav a.current {
background-color: rgb( 220, 220, 220 );
padding-left: 1em;
margin-left: 0;
margin-right: 1em;
border-top-right-radius: 0.8em;
border-bottom-right-radius: 0.8em;
}
nav a.current::before {
content : "";
border-color : white;
border-width : 1em;
border-style : solid;
border-radius : 1em;
position : absolute;
left: -1.5em;
height : 0;
top : -0.12em;
width: 0;
z-index: 100;
}
nav ul {
list-style-type: none;
padding : 0;
}
#container {
margin: 0 13em 0 2em;
}
table {
padding : 0;
margin : 0;
border-spacing : 0;
}
tr:nth-child( even ) {
background-color: rgb( 240, 240, 240 );
}
tr:first-child td {
border-top : 1px solid rgb( 220, 220, 220 )
}
tr td:first-child, tr th:first-child {
border-left : 1px solid rgb( 220, 220, 220 )
}
thead::after {
line-height: 0.4em;
content: "\200C";
display:block;
}
th {
background-color: rgb( 230, 230, 230 );
border-top : 1px solid rgb( 210, 210, 210 );
border-bottom : 1px solid rgb( 210, 210, 210 );
border-right : 1px solid rgb( 210, 210, 210 );
padding : 0.8em 1em;
margin : 0;
font-weight: bold;
}
th:first-child {
border-top-left-radius: 1em;
border-bottom-left-radius: 1em;
}
th:last-child {
border-top-right-radius: 1em;
border-bottom-right-radius: 1em;
}
td {
border-bottom : 1px solid rgb( 220, 220, 220 );
border-right : 1px solid rgb( 220, 220, 220 );
padding : 1em;
margin : 0;
}
tr:first-child td:first-child { border-top-left-radius: 1em; }
tr:first-child td:last-child { border-top-right-radius: 1em; }
tr:last-child td:first-child { border-bottom-left-radius: 1em; }
tr:last-child td:last-child { border-bottom-right-radius: 1em; }
#ribbonwrap {
position: absolute;
right: 14.1em;
z-index: 10;
}
#ribbon {
position: fixed;
bottom: 0;
width: 12.1em;
height: 12.1em;
overflow: hidden;
}
#ribbon::before, #ribbon::after {
display: block;
position: absolute;
transform: rotate(-45deg);
top: auto;
bottom: 3.15em;
height: 1.54em;
width: 15.38em;
right: -3.23em;
}
#ribbon::before {
content: "";
background-color: #666;
background-image: linear-gradient(to bottom, rgba(0, 0, 0, 0), rgba(0, 0, 0, 0.15));
padding: 0.38em 0;
box-shadow: 0 .15em .23em 0 rgba(0, 0, 0, 0.5);
}
#ribbon::after {
content: "Fork me on Github";
color: white;
font: 700 1em "Helvetica Neue", Helvetica, Arial, sans-serif;
line-height: 1.54em;
padding: 0.15em 0;
margin: 0.15em 0;
text-indent: 0;
text-align: center;
border-color: rgba(255, 255, 255, 0.7);
border-style: dotted;
border-width: 0.08em 0;
}
#footnav {
}
.prenext {
}
.prenext a:hover::before {
text-decoration: underline;
}
.prenext .prev::before, .prenext .next:before {
background-color: rgb( 240, 240, 240 );
padding: 0.2em 0.8em;
border-radius: 0.8em;
margin: 1em 0 1em 0;
}
.prenext .prev::before {
content : "\2039\2039\00a0prev";
float: left;
}
.prenext .next::before {
content : "next\00a0\203A\203A";
float: right;
}
#improvethis {
float: right;
color: #bbb;
margin: 1em 0 0 0;
}
#improvethis::before {
content : "\270E\00a0Improve\00a0this\00a0page";
}
.highlighter-rouge {
background-color: #f8f8f8;
border-radius: 0.4em;
padding: 0.1em 0.2em;
}

@ -0,0 +1,212 @@
.highlight table td { padding: 5px; }
.highlight table pre { margin: 0; }
.highlight .cm {
color: #999988;
font-style: italic;
}
.highlight .cp {
color: #999999;
font-weight: bold;
}
.highlight .c1 {
color: #999988;
font-style: italic;
}
.highlight .cs {
color: #999999;
font-weight: bold;
font-style: italic;
}
.highlight .c, .highlight .cd {
color: #999988;
font-style: italic;
}
.highlight .err {
color: #a61717;
background-color: #e3d2d2;
}
.highlight .gd {
color: #000000;
background-color: #ffdddd;
}
.highlight .ge {
color: #000000;
font-style: italic;
}
.highlight .gr {
color: #aa0000;
}
.highlight .gh {
color: #999999;
}
.highlight .gi {
color: #000000;
background-color: #ddffdd;
}
.highlight .go {
color: #888888;
}
.highlight .gp {
color: #555555;
}
.highlight .gs {
font-weight: bold;
}
.highlight .gu {
color: #aaaaaa;
}
.highlight .gt {
color: #aa0000;
}
.highlight .kc {
color: #000000;
font-weight: bold;
}
.highlight .kd {
color: #000000;
font-weight: bold;
}
.highlight .kn {
color: #000000;
font-weight: bold;
}
.highlight .kp {
color: #000000;
font-weight: bold;
}
.highlight .kr {
color: #000000;
font-weight: bold;
}
.highlight .kt {
color: #445588;
font-weight: bold;
}
.highlight .k, .highlight .kv {
color: #000000;
font-weight: bold;
}
.highlight .mf {
color: #009999;
}
.highlight .mh {
color: #009999;
}
.highlight .il {
color: #009999;
}
.highlight .mi {
color: #009999;
}
.highlight .mo {
color: #009999;
}
.highlight .m, .highlight .mb, .highlight .mx {
color: #009999;
}
.highlight .sb {
color: #d14;
}
.highlight .sc {
color: #d14;
}
.highlight .sd {
color: #d14;
}
.highlight .s2 {
color: #d14;
}
.highlight .se {
color: #d14;
}
.highlight .sh {
color: #d14;
}
.highlight .si {
color: #d14;
}
.highlight .sx {
color: #d14;
}
.highlight .sr {
color: #009926;
}
.highlight .s1 {
color: #d14;
}
.highlight .ss {
color: #990073;
}
.highlight .s {
color: #d14;
}
.highlight .na {
color: #008080;
}
.highlight .bp {
color: #999999;
}
.highlight .nb {
color: #0086B3;
}
.highlight .nc {
color: #445588;
font-weight: bold;
}
.highlight .no {
color: #008080;
}
.highlight .nd {
color: #3c5d5d;
font-weight: bold;
}
.highlight .ni {
color: #800080;
}
.highlight .ne {
color: #990000;
font-weight: bold;
}
.highlight .nf {
color: #990000;
font-weight: bold;
}
.highlight .nl {
color: #990000;
font-weight: bold;
}
.highlight .nn {
color: #555555;
}
.highlight .nt {
color: #000080;
}
.highlight .vc {
color: #008080;
}
.highlight .vg {
color: #008080;
}
.highlight .vi {
color: #008080;
}
.highlight .nv {
color: #008080;
}
.highlight .ow {
color: #000000;
font-weight: bold;
}
.highlight .o {
color: #000000;
font-weight: bold;
}
.highlight .w {
color: #bbbbbb;
}
.highlight {
background-color: #f8f8f8;
border-radius: 1em;
padding: 0.1em 1em;
margin: 0;
}

@ -0,0 +1,13 @@
---
layout: default
title: "Download"
---
Release 2.1.6 (current)
=======================
Source Tar Ball: [release-2.1.6.tar.gz](https://github.com/axkibe/lsyncd/archive/release-2.1.6.tar.gz)
HEAD Development
================
{% highlight shell %}
git clone https://github.com/axkibe/lsyncd.git
{% endhighlight %}

@ -0,0 +1,8 @@
---
layout: default
title: Frequently Asked Questions
short: FAQ
---
* [How can I call a script after each rsync operation?](postscript)
* [How can I sync from one source to multiple targets?](multiple-targets)
* [The startup sync works but after that Lsyncd doesn't do anything!](nothing-after-startup)

@ -0,0 +1,32 @@
---
layout: default
title: "FAQ: How can I sync from one source to multiple targets?"
---
If you got multiple targets, you simple specify the sync command multiple times.
{% highlight lua %}
sync{ default.rsync, source='/sourcedir', target='targethost1:/targetdir' }
sync{ default.rsync, source='/sourcedir', target='targethost2:/targetdir' }
sync{ default.rsync, source='/sourcedir', target='targethost3:/targetdir' }
{% endhighlight %}
Lsyncd will notice multiple uses of the same source directory or the use of a subdirectory of an already used source directory and creates only watch per subdirectoy watched in any sync.
To remedy the multiplication of the same configuration you can even use a loop to configure multiple targets.
This is the same configuration as before using a loop:
{% highlight lua %}
targets = {
'targethost1:/targetdir',
'targethost2:/targetdir',
'targethost3:/targetdir',
}
for _, target in ipairs( targets )
do
sync{ default.rsync, source='/sourcedir', target=target }
end
{% endhighlight %}
## [ back to FAQ index](../)

@ -0,0 +1,11 @@
---
layout: default
title: "FAQ: The startup sync works but after that Lsyncd doesn't do anything!"
---
This almost always caused by the fact you specified a network mounted directory as source.
Lsyncd requires the kernels inotify or fsevents interface to get noted of file changes. No known network filesystem (known to Lsyncd authors) supports forwarding file notifcations events.
Thus Lsyncd needs to run on the system where the files are located physically.
## [ back to FAQ index](../)

@ -0,0 +1,42 @@
---
layout: default
title: "FAQ: How can I call a script before or after each rsync operation?"
---
The issue with this quite frequent request is, by itself it complicates error handling a lot. What should Lsyncd do, when the script fails that it ought to run after each rsync call? If it should recall the post script it would require a new state for each rsync event which would complicate Lsyncd code quite a bit.
The easiest way to get around this, is by replacing the rsync binary Lsyncd calls by a script from you, that calls rsync and does whatever you want to do, when rsync completes. The only thing to take care is that Lsyncd communicates with rsync using stdin/out/err-pipes and thus better not interfere with these.
Also take care the script properly forwards the exit code rsync returned.
This is an example bash script to wrap around rsync:
{% highlight shell %}
#!/bin/bash
/usr/bin/rsync "$@"
result=$?
(
if [ $result -eq 0 ]; then
echo "my commands";
fi
) >/dev/null 2>/dev/null </dev/null
exit $result
{% endhighlight %}
It does not do error handling for post commands. If you need this, you'll have to code them here fitting your requirements.
Above script can be used as rsync wrapper replacement like this:
{% highlight lua %}
sync {
default.rsync,
source = "/path/to/source",
target = "targethost::targetdir",
rsync = {
binary = "/path/to/bash/handler.sh"
}
}
{% endhighlight %}
## [ back to FAQ index](../)

@ -0,0 +1,22 @@
---
layout: default
title: "Getting and Giving Help"
short: "Help"
---
Discussion Group
----------------
There is a [discussion group to all things related Lsyncd](https://groups.google.com/forum/#!forum/lsyncd/join)
Issues
------
For cases Lsyncd is missbehaving there are [Issues](https://github.com/axkibe/lsyncd/issues) on Github.
Please check:
* This isn't a usage error.
* Your running the latest Lsyncd version.
* You include all things needed to reproduce the error, like complete configuration scripts.
Source & Improvement
--------------------
[Fork Lsyncd at Github](https://github.com/axkibe/lsyncd)

@ -0,0 +1,47 @@
---
layout: default
title: "Lsyncd - Live Syncing (Mirror) Daemon"
short: "Welcome"
---
Description
-----------
Lsyncd uses a filesystem event interface (inotify or fsevents) to watch for changes to local files and directories. Lsyncd collates these events for several seconds and then spawns one or more processes to synchronize the changes to a remote filesystem. The default synchronization method is [rsync](http://rsync.samba.org/). Thus, Lsyncd is a light-weight live mirror solution. Lsyncd is comparatively easy to install and does not require new filesystems or block devices. Lysncd does not hamper local filesystem performance.
As an alternative to rsync, Lsyncd can also push changes via rsync+ssh. Rsync+ssh allows for much more efficient synchronization when a file or direcotry is renamed or moved to a new location in the local tree. (In contrast, plain rsync performs a move by deleting the old file and then retransmitting the whole file.)
Fine-grained customization can be achieved through the config file. Custom action configs can even be written from scratch in cascading layers ranging from shell scripts to code written in the [Lua language](http://www.lua.org/). Thus, simple, powerful and flexible configurations are possible.
Lsyncd 2.2.1 requires rsync >= 3.1 on all source and target machines.
License: [GPLv2](http://www.fsf.org/licensing/licenses/info/GPLv2.html) or any later GPL version.
When to use
-----------
Lsyncd is designed to synchronize a slowly changing local directory tree to a remote mirror. Lsyncd is especially useful to sync data from a secure area to a not-so-secure area.
Other synchronization tools
------------------------
[DRBD](http://www.drbd.org) operates on block device level. This makes it useful for synchronizing systems that are under heavy load. Lsyncd on the other hand does not require you to change block devices and/or mount points, allows you to change uid/gid of the transferred files, separates the receiver through the one-way nature of rsync. DRBD is likely the better option if you are syncing databases.
[GlusterFS](http://www.gluster.org) and [BindFS](http://bindfs.org/) use a FUSE-Filesystem to interject kernel/userspace filesystem events.
[Mirror](https://github.com/stephenh/mirror) is an asynchronous synchronisation tool that takes use of the inotify notifications much like Lsyncd. The main differences are: it is developed specifically for master-master use, thus running on a daemon on both systems, uses its own transportation layer instead of rsync and is Java instead of Lsyncd's C core with Lua scripting.
Lsyncd usage examples
---------------------
{% highlight shell %}
lsyncd -rsync /home remotehost.org::share/
{% endhighlight %}
This watches and rsyncs the local directory /home with all sub-directories and
transfers them to 'remotehost' using the rsync-share 'share'.
{% highlight shell %}
lsyncd -rsyncssh /home remotehost.org backup-home/
{% endhighlight %}
This will also rsync/watch '/home', but it uses a ssh connection to make moves local on the remotehost instead of re-transmitting the moved file over the wire.
Disclaimer
----------
Besides the usual disclaimer in the license, we want to specifically emphasize that neither the authors, nor any organization associated with the authors, can or will be held responsible for data-loss caused by possible malfunctions of Lsyncd.

@ -0,0 +1,26 @@
---
layout: default
title: Building
---
## Requirements
### Lua >= 5.2
Lsyncd depends on Lua 5.2 or greater; that is 5.2 or 5.3. For most distributions you need to install the liblua??, the liblua??-dev and the lua?? package, with ?? being the respective Lua version.
### cmake >= 2.8
To configure Lsyncd to your system, cmake >= 2.8 is required
### rsync >= 3.1
During runtime Lsyncd needs rsync > 3.1 installed both on source and target systems.
## Compiling
With these requirements fulfilled building Lsyncd should be a straight forward process. Unpack the downloaded tar.gz file and run:
{% highlight shell %}
cmake .
make
sudo make install
{% endhighlight %}

@ -0,0 +1,99 @@
---
layout: default
title: "The Configuration File"
short: "Config File"
---
Lsyncd configuration files are valid [Lua syntax](http://www.lua.org/). It is designed to be simple yet potent. While rich configuration and simplicity are not opposites by themselves, some trade-offs are inevitable. To achieve both goals as far as possible, Lsyncd configuration can be done at different layers. Lower layers add adaptability while the interface becomes more engaging.
Settings
--------
For scripts of all layers, the ```settings``` call can be used to alter daemon-wide configurations.
For example, the following code will instruct Lsyncd to log into ```/tmp/lsyncd.log```, periodically update the file ```/tmp/lsyncd.status``` with its status and to not detach as a daemon.
{% highlight lua %}
settings {
logfile = "/tmp/lsyncd.log",
statusFile = "/tmp/lsyncd.status",
nodaemon = true,
}
{% endhighlight %}
**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 `{`.
Valid keys for settings are:
<table>
<tr><td> logfile
</td><td> =
</td><td> FILENAME
</td><td> logs into this file
</td></tr>
<tr><td> pidfile
</td><td> =
</td><td> FILENAME
</td><td> logs PID into this file
</td></tr>
<tr><td> nodaemon
</td><td> =
</td><td> BOOL
</td><td> does not detach
</td></tr>
<tr><td> statusFile
</td><td> =
</td><td> FILENAME
</td><td> periodically writes a status report to this file
</td></tr>
<tr><td> statusInterval
</td><td> =
</td><td> NUMBER
</td><td> writes the status file at shortest after this number of seconds has passed (default: 10)
</td></tr>
<tr><td> logfacility
</td><td> =
</td><td> STRING
</td><td> syslog facility, default "user"
</td></tr>
<tr><td> logident
</td><td> =
</td><td> STRING
</td><td> syslog identification (tag), default "lsyncd"
</td></tr>
<tr><td> insist
</td><td> =
</td><td> BOOL
</td><td> keep running at startup although one or more targets failed due to not being reachable.
</td></tr>
<tr><td> inotifyMode
</td><td> =
</td><td> STRING
</td><td> Specifies on inotify systems what kind of changes to listen to. Can be "Modify", "CloseWrite" (default) or "CloseWrite or Modify".
</td></tr>
<tr><td> maxProcesses
</td><td> =
</td><td> NUMBER
</td><td> Lysncd will not spawn more than these number of processes. This adds across all sync{}s.
</td></tr>
</table>
Additionally some parameters can be configured, which are inherited by all _Syncs_ (see Layer 3)
<table>
<tr><td> maxDelays
</td><td> =
</td><td> NUMBER
</td><td> When this amount of delayed events is queued, actions will be spawned, even below the delay timer.
</td></tr>
</table>

@ -0,0 +1,182 @@
---
layout: default
title: "Config Layer 1: Inlets"
short: "Config Layer 1"
---
Layer 2 allows you to create one process per one event. However, as with default rsync behavior you might want to call one process for several events. This can be done with inlets. When any event becomes ready Lsyncd calls the ```action``` entry with ```inlet``` as parameter. The ```inlet``` can be used to grab ready single events or event lists.
For example this is the action used by default.rsync:
{% highlight lua %}
action = function( inlet )
local elist = inlet.getEvents( )
local config = inlet.getConfig( )
local paths = elist.getPaths( )
log( "Normal", "rsyncing list\n", table.concat( paths, '\n' ) )
spawn(elist, '/usr/bin/rsync',
'<', table.concat( paths, '\000' ),
'--delete',
config.rsync._computed,
'--from0',
'--include-from=-',
'--exclude=*',
config.source,
config.target
)
end
{% endhighlight %}
Inlet functions are:
| Function | Description |
|:---------|:------------|
| inlet.getEvent() | Retrieves the next `event` as in Layer 2 configuration. Multiple calls to getEvent() will return the same event unless it has spawn{}ed an action. |
| inlet.getEvents(test) | Returns a list of all events that are ready. `test` is optional for a function that will be called for every event to test if it should be included in the list. It has one parameter the `event` and returns true if an event should be included. If nil every ready event will be included in the list |
| inlet.discardEvent() | Discards an event. The next call to getEvent will thus receive another event, even if no action has been spawned for this event |
| inlet.getConfig() | returns the same as `event.config`. The configuration of the sync{} |
| inlet.addExclude() | adds an exclusion pattern to this sync (see Exclusions) |
| inlet.rmExclude() | removes an exclusion pattern from this sync |
| inlet.createBlanketEvent() | puts an `event` on the top of the Delay FIFO that blocks all events and is blocked by all events. This is used for onStartup. |
The list returned by getEvents can be handed to spawn{} as _agent_ just as well as singular events.
Lists have following functions
| Function | Description |
|:----------|:------------|
| elist.getPaths(delimiter) | returns a string of the paths (as in `event.path` separated by `delimiter`. By default \n is used as delimiter. |
| elist.getSourcePaths(delimiter) | returns a string of the sourcePaths (as in `event.sourcePath` separated by `delimiter`. By default \n is used as delimiter. |
Take care calling getEvents() and its function since depending on the amount of events, they will cause quite some CPU load.
Layer 2 functions is nothing else than following layer 1 action loaded by the default if the user script did not provide one itself.
{% highlight lua %}
-----
-- Default action calls user scripts on**** functions.
--
action = function( inlet )
-- in case of moves getEvent returns the origin and destination of the move
local event, event2 = inlet.getEvent( )
local config = inlet.getConfig( )
local func = config[ 'on'.. event.etype ]
if func
then
func( event, event2 )
end
-- if function didnt change the wait status its not interested
-- in this event -> drop it.
if event.status == "wait"
then
inlet.discardEvent( event )
end
end,
{% endhighlight %}
Lsyncd will automatically split Move events into Create and Delete events if no "onMove" field is found in the config. When handling moves in layer 1 `action` function, simply set "onMove" to be "true".
Other than `action` Lsyncd calls `init` for each sync{} on initialization. This is the default init function which is loaded if the user script does not have one. It provides the onStartup() functionality for layer 2 and 3.
{% highlight lua %}
-----
-- called on (re)initalizing of lsyncd.
--
init = function( inlet )
local config = inlet.getConfig( )
-- calls a startup if provided by user script.
if type( config.onStartup ) == "function"
then
local event = inlet.createBlanketEvent( )
config.onStartup( event )
if event.status == 'wait'
then
-- user script did not spawn anything
-- thus the blanket event is deleted again.
inlet.discardEvent( event )
end
end
end,
{% endhighlight %}
As another example this is the init of `default.rsync`. As specialty it changes the configuration in that it adds a slash to target if not there already.
{% highlight lua %}
-----
-- Spawns the recursive startup sync
--
init = function( inlet )
local config = inlet.getConfig( )
local event = inlet.createBlanketEvent( )
if string.sub(config.target, -1) ~= "/"
then
config.target = config.target .. "/"
end
log("Normal", "recursive startup rsync: ", config.source,
" -> ", config.target)
spawn(event,
"/usr/bin/rsync",
"--delete",
config.rsync._computed .. "r",
config.source,
config.target
)
end,
{% endhighlight %}
When child processes are finished and their zombie processes are collected, Lsyncd calls the function of the `collect` entry. When collect return "again" the status of the agent (an event or an event list) will be set on "wait" again, and will become ready in `delay` seconds (or 1 second if smaller).
The default collect function looks in the exitcodes[] table for an entry of the exit code. Otherwise most of the unfortunately longer code below does nothing but making nice log message.
{% highlight lua %}
-----
-- Called when collecting a finished child process
--
collect = function(agent, exitcode)
local config = agent.config
if not agent.isList and agent.etype == "Blanket" then
if exitcode == 0
then
log("Normal", "Startup of '",agent.source,"' finished.")
elseif config.exitcodes and
config.exitcodes[exitcode] == "again"
then
log("Normal",
"Retrying startup of '",agent.source,"'.")
return "again"
else
log("Error", "Failure on startup of '",agent.source,"'.")
terminate(-1) -- ERRNO
end
return
end
local rc = config.exitcodes and config.exitcodes[exitcode]
if rc == "die"
then
return rc
end
if agent.isList
then
if rc == "again"
then
log("Normal", "Retrying a list on exitcode = ",exitcode)
else
log("Normal", "Finished a list = ",exitcode)
end
else
if rc == "again"
then
log("Normal", "Retrying ",agent.etype,
" on ",agent.sourcePath," = ",exitcode)
else
log("Normal", "Finished ",agent.etype,
" on ",agent.sourcePath," = ",exitcode)
end
end
return rc
end,
{% endhighlight %}

@ -0,0 +1,94 @@
---
layout: default
title: "Config Layer 2: Advanced onAction"
short: "Config Layer 2"
---
While Layer 4 and 3 feel like normal configuration files, Layer 2 and 1 enter the realm of coding. It is thus supposed you have some coding knowledge when using Layer 2 or 1.
Instead of designating actions as strings as in Layer 3 Lua functions can used to do some small scripts right within Lsyncd.
This example will convert any file with the suffix ".ps" created in a directory into a PDF.
{% highlight lua %}
autopdf = {
onCreate = function(event)
log("Normal", "got an onCreate Event")
if string.ends(event.pathname, ".ps") then
spawn(event, "/usr/bin/ps2pdf", event.sourcePath)
end
end
}
{% endhighlight %}
The function can take any valid Lua code.
Lsyncd provides you a set of functions to be used in user scripts.
log(Category, ...)
------------------
Logs a message into file/stdout/syslog. The first parameter is the logging category all others are strings to be logged. A logging category must start with a capital letter. "Normal" and "Error" are standard categories for log messages. All others are categories for debugging.
spawn(Event, Binary, ...)
--------------------------
Spawns a new process associated with the event (or event list, see below) as first parameter. The second parameter specifies a binary to call. All others are arguments for the binary.
If the third parameter is "<", then along with fourth parameter they will not be passed as arguments to the binary. The fourth parameter is a string that will piped through stdin to the binary.
Do not use Lua's ```os.execute``` as opposed to Lsyncd's ```spawn()``` it will block and thus block the whole Lsyncd daemon until the command is completed. Lsyncd's ```spawn``` on the other hand returns immediately while the child process runs.
spawnShell(Event, Command, ... )
--------------------------------
The same as spawn(), only it will invoke a shell. Any parameters are referred as $1, $2, $3 and so on in the command.
By the way, this is the simple implementation of spawnShell:
{% highlight lua %}
function spawnShell(agent, command, ...)
return spawn(agent, "/bin/sh", "-c", command, "/bin/sh", ...)
end
{% endhighlight %}
terminate(exitcode)
-------------------
Lets Lsyncd terminate with ```exitcode```.
event
-----
Variables of the actions are given by the _event_ field. It has following fields.
|Field|Meaning|
|:----|:----|
| event.config | the configuration as called with sync{} |
| event.inlet | see [layer 1](../layer1/) about inlets |
| event.etype | the event type. Can be 'ATTRIB', 'CREATE', 'MODIFY', 'DELETE', 'MOVE' |
| event.status | the status of the event. 'wait' when it is ready to be spawned and 'active' if there is a process running associated with this event |
| event.isdir | true if the event relates to a directory |
| event.name | the filename, directories end with a slash |
| event.basename | the filename, directories do not end with a slash |
| event.path | see ^path of [Layer 3](../layer3/#all-possible-variables) |
| event.pathname | see ^pathname of [Layer 3](../layer3/#all-possible-variables) |
| event.source | see ^source of [Layer 3](../layer3/#all-possible-variables) |
| event.sourcePath | see ^sourcePath of [Layer 3](../layer3/#all-possible-variables) |
| event.sourcePathname | see ^sourcePathname of [Layer 3](../layer3/#all-possible-variables) |
| event.target | see ^target of [Layer 3](../layer3/#all-possible-variables) |
| event.targetPath | see ^targetPath of [Layer 3](../layer3/#all-possible-variables) |
| event.targetPathname | see ^targetPathname of [Layer 3](../layer3/#all-possible-variables) |
onMove actions have two events as parameter, the origin and the destination of the move.
This example will tattle about all moves within the observed directory tree.
{% highlight lua %}
tattleMove = {
onMove = function(oEvent, dEvent)
log("Normal", "A moved happened from ",
oEvent.pathname, " to ", dEvent.pathname)
end,
}
{% endhighlight %}
Action functions have to be short and fast. They are running right within Lsyncd's one and only main thread. If you have to do any more time consuming calculations _spawn{}_ a child process instead.
There can only be one child process associated to a event.
Layer 3 is nothing else than Lsyncd automatically write Layer 2 functions for you on initialization. Start Lsyncd with ```-log FWrite``` on a Layer 3 configuration to see what functions it dynamically writes and loads for you. Thus Layer 3 and 2 can also be be mixed at will.

@ -0,0 +1,175 @@
---
layout: default
title: "Config Layer 3: Simple onAction"
short: "Config Layer 3"
---
Simple onAction
---------------
In this layer, custom configurations can be created. This example will use bash commands to keep a local directory in sync.
{% highlight lua %}
bash = {
delay = 5,
maxProcesses = 3,
onCreate = "cp -r ^sourcePathname ^targetPathname",
onModify = "cp -r ^sourcePathname ^targetPathname",
onDelete = "rm -rf ^targetPathname",
onMove = "mv ^o.targetPathname ^d.targetPathname",
onStartup = '[[ if [ "$(ls -A ^source)" ]; then cp -r ^source* ^target; fi]]',
}
{% endhighlight %}
The example explained step by step. Technically, any Lsyncd configuration is a Lua table with a set of keys filled out. Thus it starts by creating a variable called ```bash``` and assigns it a table with = { ... }.
{% highlight lua %}
bash = {
...
}
{% endhighlight %}
Now the table is filled with entries. Every entry having a key left of the equal sign and its value right of it. If no delay is specified, this means immediate actions for Lsyncd. This example wants to aggregate changes for 5 seconds thus the next entry is:
{% highlight lua %}
delay = 5,
{% endhighlight %}
And a comma is needed since to mark the end of an entry.
Actions
-------
Actions are specified by the 6 keys:
<table>
<tr><td> onAttrib
</td><td> called when only attributes changed
</td></tr>
<tr><td> onCreate
</td><td> called on a new file or directory
</td></tr>
<tr><td> onModify
</td><td> called when a file has changed
</td></tr>
<tr><td> onDelete
</td><td> called when a file or directory has been deleted
</td></tr>
<tr><td> onMove
</td><td> called when a file or directory has been moved within the observed directory tree
</td></tr>
<tr><td> onStartup
</td><td> called on the start of Lsyncd
</td></tr>
</table>
When there is no ```onMove``` or the move goes into or out of the observed directory tree, it is split into an ```onDelete``` of the move origin and an ```onCreate``` of the move destination. That is if either is within the observed directory tree. ```onStartup``` will always block all other actions for this _Sync_ until completed.
The action to be taken is specified as a Lua string. Thus actions can be delimited with anything Lua allows, these are 'TEXT', "TEXT", or '[[TEXT]] as used in ```onStartup``` in the example above.
Any action starting with a "/" instructs Lsyncd to directly call the binary file at the beginning instead of spawning an additional shell. For example
{% highlight lua %}
onCreate = "/usr/bin/zip /usr/var/all.zip ^sourcePath"
onModify = "/usr/bin/zip /usr/var/all.zip ^sourcePath"
{% endhighlight %}
will add any newly created and modified files to /usr/var/all.zip using absolute path names. Any action not starting with a "/" will result in Lsyncd spawning a shell to execute the action as command.
Variables
---------
Variable arguments are specified with the caret symbol ^. It has been chosen over $ or other symbols to be less conflicting with standard shell conventions.
Note that variables will always be implicitly quoted in double quotes, so if you want them to be a part of another double-quoted string, you will have to go one layer deeper, e.g.
{% highlight lua %}
onCreate = '[[ su user -c "/usr/bin/zip /usr/var/all.zip ^o.sourcePath " ]],
{% endhighlight %}
will expand to ```su user -c "/usr/bin/zip /usr/var/all.zip "source""``` which is incorrect and will break. You have to rewrite the above statement one layer deeper as
{% highlight lua %}
onCreate = function(event)
spawnShell('[[ su user -c "/usr/bin/zip /usr/var/all.zip \"$1\"" ]], event.sourcePath)
end
{% endhighlight %}
All possible variables
----------------------
<table>
<tr><td> ^source
</td><td> the absolute path of the observed source directory
</td></tr>
<tr><td> ^target
</td><td> the "target" attribute of the config
</td></tr>
<tr><td> ^path
</td><td> the relative path of the file or directory to the observed directory; directories have a slash at the end.
</td></tr>
<tr><td> ^pathname
</td><td> the relative path of the file or directory to the observed directory; directories have no slash at the end.
</td></tr>
<tr><td> ^sourcePath
</td><td> the absolute path of the observed source directory and the relative path of the file or directory; this equals the absolute local path of the file or directory. Directories have a slash at the end.
</td></tr>
<tr><td> ^sourcePathname
</td><td> same as ^sourcePath, but directories have no slash at the end.
</td></tr>
<tr><td> ^targetPath
</td><td> The "target" attributed of the config appended by the relative path of the file or directory. Directories have a slash at the end.
</td></tr>
<tr><td> ^targetPathname
</td><td> same as ^targetPath, but directories have no slash at the end.
</td></tr>
</table>
For ```onMoves``` a _o._ and or _d._ can be prepended to path, pathname, sourcePath sourcePathname, targetPath and targetPathname to specify the move origin or destination. Without neither the variables refers to the move origin.
From the example above, it moves the file or directory in the target directory.
{% highlight lua %}
onMove = "mv ^o.targetPathname ^d.targetPathname",
{% endhighlight %}
Execution control (exit codes)
------------------------------
A few words on the startup of the example. It looks a little more complicated, but it is just some bash scripting, nothing Lsyncd specific. It simply does a recursive copy of the source to the target, but first tests if there is anything in the source file. Otherwise the command returns a non-zero error code.
{% highlight lua %}
onStartup = '[[if [ "$(ls -A ^source)" ]; then cp -r ^source* ^target; fi]],
{% endhighlight %}
By default Lsyncd ignores all exit codes except onStartup which must return 0 for it to continue. You can change this behavior by adding a ```exitcodes``` table.
{% highlight lua %}
exitcodes = {[0] = "ok", [1] = "again", [2] = "die"}
{% endhighlight %}
The keys specify for the exit code the string of the desired action.
<table>
<tr><td> again
</td><td> respawns the action after {{delay}} seconds, or 1 second if delay is immediate
</td></tr>
<tr><td> die
</td><td> lets Lsyncd terminate.
</td></tr>
</table>
All other values let Lsyncd continue normally.

@ -0,0 +1,591 @@
---
layout: default
title: "Config Layer 4: Default Config"
short: "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.
<table>
<tr><td> <b>parameter</b>
</td><td> <b>=</b>
</td><td>