octoleo
/
lsyncd
mirror of https://github.com/octoleo/lsyncd.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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

This commit is contained in:
Daniel Poelzleithner 2022-04-20 19:20:52 +02:00
parent 2841ef8528
commit 0de678ab3c
30 changed files with 2540 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
.gitignore vendored
View File

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

16
CMakeLists.txt
View File

@ -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 Normal file
View File

@ -0,0 +1 @@
_site/

4
docs/_config.yml Normal file
View File

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

19
docs/_data/docs.yml Normal file
View File

@ -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

77
docs/_layouts/default.html Normal file
View File

@ -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>

78
docs/_layouts/default3.html Normal file
View File

@ -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>

46
docs/appendices/devdocs/index.md Normal file
View File

@ -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.

257
docs/css/main.css Normal file
View File

@ -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;
}

212
docs/css/syntax.css Normal file
View File

@ -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;
}

13
docs/download/index.md Normal file
View File

@ -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 %}

8
docs/faq/index.md Normal file
View File

@ -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)

32
docs/faq/multiple-targets/index.md Normal file
View File

@ -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](../)

11
docs/faq/nothing-after-startup/index.md Normal file
View File

@ -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](../)

42
docs/faq/postscript/index.md Normal file
View File

@ -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](../)

22
docs/help/index.md Normal file
View File

@ -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)

47
docs/index.md Normal file
View File

@ -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
doc/manpage/lsyncd.1 → docs/manpage/lsyncd.1
View File

0
doc/manpage/lsyncd.1.txt → docs/manpage/lsyncd.1.txt
View File

26
docs/manual/building/index.md Normal file
View File

@ -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 %}

99
docs/manual/config/file/index.md Normal file
View File

@ -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>

182
docs/manual/config/layer1/index.md Normal file
View File

@ -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 %}

94
docs/manual/config/layer2/index.md Normal file
View File

@ -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.

175
docs/manual/config/layer3/index.md Normal file
View File

@ -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.

591
docs/manual/config/layer4/index.md Normal file
View File

@ -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> <b>TYPE</b>
</td><td> <b>default value</b>
</td><td> <b>comment</b>
</td></tr>
<tr><td> acls
</td><td> =
</td><td> BOOL
</td><td> false
</td><td>
</td></tr>
<tr><td> append
</td><td> =
</td><td> BOOL
</td><td> false
</td><td> (Lsyncd >= 2.2.0)
</td></tr>
<tr><td> append-verify
</td><td> =
</td><td> BOOL
</td><td> false
</td><td> (Lsyncd >= 2.2.0)
</td></tr>
<tr><td> archive
</td><td> =
</td><td> BOOL
</td><td> false
</td><td>
</td></tr>
<tr><td> backup
</td><td> =
</td><td> BOOL
</td><td> false
</td><td> (Lsyncd >= 2.2.0)
</td></tr>
<tr><td> backup_dir
</td><td> =
</td><td> DIR
</td><td> false
</td><td> (Lsyncd >= 2.2.0)
</td></tr>
<tr><td> binary
</td><td> =
</td><td> FILENAME
</td><td> "/usr/bin/rsync"
</td><td> Lsyncd calls this binary as rsync
</td></tr>
<tr><td> checksum
</td><td> =
</td><td> BOOL
</td><td> false
</td><td>
</td></tr>
<tr><td> chmod
</td><td> =
</td><td> STRING
</td><td>
</td><td> (Lsyncd >= 2.2.0)
</td></tr>
<tr><td> chown
</td><td> =
</td><td> USER:GROUP
</td><td>
</td><td> (Lsyncd >= 2.2.0)
</td></tr>
<tr><td> compress
</td><td> =
</td><td> BOOL
</td><td> false
</td><td>
</td></tr>
<tr><td> copy_dirlinks
</td><td> =
</td><td> BOOL
</td><td> false
</td><td> (Lsyncd >= 2.2.0)
</td></tr>
<tr><td> copy_links
</td><td> =
</td><td> BOOL
</td><td> false
</td><td>
</td></tr>
<tr><td> cvs_exclude
</td><td> =
</td><td> BOOL
</td><td>
</td></tr>
<tr><td> dry_run
</td><td> =
</td><td> BOOL
</td><td> false
</td><td>
</td></tr>
<tr><td> exclude
</td><td> =
</td><td> PATTERN
</td><td>
</td><td> TABLE of PATTERNs also allowed
</td></tr>
<tr><td> excludeFrom
</td><td> =
</td><td> FILENAME
</td><td>
</td><td>
</td></tr>
<tr><td> executability
</td><td> =
</td><td> BOOL
</td><td> false
</td><td>
</td></tr>
<tr><td> existing
</td><td> =
</td><td> BOOL
</td><td> false
</td><td> (Lsyncd >= 2.2.0)
</td></tr>
<tr><td> group
</td><td> =
</td><td> BOOL
</td><td> false
</td><td>
</td></tr>
<tr><td> groupmap
</td><td> =
</td><td> STRING
</td><td>
</td><td> (Lsyncd >= 2.2.0)
</td></tr>
<tr><td> hard_links
</td><td> =
</td><td> BOOL
</td><td> false
</td><td>
</td></tr>
<tr><td> ignore_times
</td><td> =
</td><td> BOOL
</td><td> false
</td><td>
</td></tr>
<tr><td> inplace
</td><td> =
</td><td> BOOL
</td><td> false
</td><td> (Lsyncd >= 2.1.6)
</td></tr>
<tr><td> ipv4
</td><td> =
</td><td> BOOL
</td><td> false
</td><td>
</td></tr>
<tr><td> ipv6
</td><td> =
</td><td> BOOL
</td><td> false
</td><td>
</td></tr>
<tr><td> links
</td><td> =
</td><td> BOOL
</td><td> true
</td><td>
</td></tr>
<tr><td> one_file_system
</td><td> =
</td><td> BOOL
</td><td> false
</td><td>
</td></tr>
<tr><td> owner
</td><td> =
</td><td> BOOL
</td><td> false
</td><td>
</td></tr>
<tr><td> password_file
</td><td> =
</td><td> FILENAME
</td><td>
</td><td> (Lsyncd >= 2.1.2)
</td></tr>
<tr><td> perms
</td><td> =
</td><td> BOOL
</td><td> false
</td><td>
</td></tr>
<tr><td> protect_args
</td><td> =
</td><td> BOOL
</td><td> true
</td><td>
</td></tr>
<tr><td> prune_empty_dirs
</td><td> =
</td><td> BOOL
</td><td> false
</td><td>
</td></tr>
<tr><td> quiet
</td><td> =
</td><td> BOOL
</td><td> false
</td><td>
</td></tr>
<tr><td> rsh
</td><td> =
</td><td> COMMAND
</td><td>
</td><td>
</td></tr>
<tr><td> rsync_path
</td><td> =
</td><td> PATH
</td><td>
</td><td> (path to rsync on remote host)
</td></tr>
<tr><td> sparse
</td><td> =
</td><td> BOOL
</td><td> false
</td><td>
</td></tr>
<tr><td> suffix
</td><td> =
</td><td> SUFFIX
</td><td>
</td><td> (Lsyncd >= 2.2.0)
</td></tr>
<tr><td> temp_dir
</td><td> =
</td><td> DIR
</td><td>
</td><td>
</td></tr>
<tr><td> times
</td><td> =
</td><td> BOOL
</td><td> true
</td><td>
</td></tr>
<tr><td> update
</td><td> =
</td><td> BOOL
</td><td> false
</td><td>
</td></tr>
<tr><td> usermap
</td><td> =
</td><td> STRING
</td><td>
</td><td> (Lsyncd >= 2.2.0)
</td></tr>
<tr><td> verbose
</td><td> =
</td><td> BOOL
</td><td> false
</td><td>
</td></tr>
<tr><td> whole_file
</td><td> =
</td><td> BOOL
</td><td> false
</td><td>
</td></tr>
<tr><td> xattrs
</td><td> =
</td><td> BOOL
</td><td> false
</td><td>
</td></tr>
<tr><td> _extra
</td><td> =
</td><td> TABLE of STRINGS.
</td><td>
</td><td> If absolutely needed, additional arguments can be specified as a TABLE of STRINGS(example: <tt>{ "--omit-dir-times", "--omit-link-times" }</tt>). 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 &lt;-&gt; Rsync communication.
</td></tr>
</table>
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.
<table>
<tr><td> binary
</td><td> =
</td><td> FILENAME
</td><td> Lsyncd calls this binary as ssh (default: /usr/bin/ssh)
</td></tr>
<tr><td> identityFile
</td><td> =
</td><td> FILE
</td><td> Uses this file to identify for public key authentication.
</td></tr>
<tr><td> options
</td><td> =
</td><td> TABLE
</td><td> A table of addition extended options to pass to ssh's -o option.
</td></tr>
<tr><td> port
</td><td> =
</td><td> PORT
</td><td> Adds --port=PORT to the ssh call.
</td></tr>
<tr><td> _extra
</td><td> =
</td><td> STRING TABLE
</td><td> Similar to rsync._extra this can be used as quick workaround if absolutely needed.
</td></tr>
</table>
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 the xargs parameter.
<table>
<tr><td> binary
</td><td> =
</td><td> FILENAME
</td><td> Lsyncd calls this binary as xargs on the remote host (default: /usr/bin/xargs)
</td></tr>
<tr><td> delimiter
</td><td> =
</td><td> DELIMITER
</td><td> delimiting character to separate filenames. By default the 0 character is used. Very old holds may need newline instead.
</td></tr>
<tr><td> _extra
</td><td> =
</td><td> STRING TABLE
</td><td> By default { '-0', 'rm -rf' }. Remove the -0 if you chose newline delimiter instead. Otherwise leave it as is.
</td></tr>
</table>
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{}:
<table>
<tr><td> excludeFrom
</td><td> =
</td><td> FILENAME
</td><td> loads exclusion rules from this file, on rule per line
</td></tr>
<tr><td> exclude
</td><td> =
</td><td> LIST
</td><td> loads exclusion rules from this list of strings
</td></tr>
</table>
Exclusion rules are modeled after rsync's exclusion patterns but are a bit simpler. Lsyncd supports these features:
* Generally if any segment 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:
<table>
<tr><td> delete
</td><td> =
</td><td> true
</td><td> Default. Lsyncd will delete on the target whatever is not in the source. At startup and what's being deleted during normal operation.
</td></tr>
<tr><td> delete
</td><td> =
</td><td> false
</td><td> Lsyncd will not delete any files on the target. Not on startup nor on normal operation. (Overwrites are possible though)
</td></tr>
<tr><td> delete
</td><td> =
</td><td> 'startup'
</td><td> Lsyncd will delete files on the target when it starts up but not on normal operation.
</td></tr>
<tr><td> delete
</td><td> =
</td><td> 'running'
</td><td> Lsyncd will not delete files on the target when it starts up but will delete those that are removed during normal operation.
</td></tr>
</table>

283
docs/manual/examples/auto-image-magic/index.md Normal file
View File

@ -0,0 +1,283 @@
---
layout: default
title: "Example: Auto-Image-Magic"
tab: "manual/examples"
---
This [example](..) is a layer 1 script to make a special "magic" directory in which image files will be converted automatically therein.
The full script:
{% highlight lua %}
local formats = { jpg = true, gif = true, png = true }
convert = {
delay = 0,
maxProcesses = 99,
action = function(inlet)
local event = inlet.getEvent()
if event.isdir then
-- ignores events on dirs
inlet.discardEvent(event)
return
end
-- extract extension and basefilename
local p = event.pathname
local ext = string.match(p, ".*%.([^.]+)$")
local base = string.match(p, "(.*)%.[^.]+$")
if not formats[ext] then
-- an unknown extenion
log("Normal", "not doing something on ."..ext)
inlet.discardEvent(event)
return
end
-- autoconvert on create and modify
if event.etype == "Create" or event.etype == "Modify" then
-- builds one bash command
local cmd = ""
-- do for all other extensions
for k, _ in pairs(formats) do
if k ~= ext then
-- excludes files to be created, so no
-- followup actions will occur
inlet.addExclude(base..'.'..k)
if cmd ~= "" then
cmd = cmd .. " && "
end
cmd = cmd..
'/usr/bin/convert "'..
event.source..p..'" "'..
event.source..base..'.'..k..
'" || /bin/true'
end
end
log("Normal", "Converting "..p)
spawnShell(event, cmd)
return
end
-- deletes all formats if you delete one
if event.etype == "Delete" then
-- builds one bash command
local cmd = ""
-- do for all other extensions
for k, _ in pairs(formats) do
if k ~= ext then
-- excludes files to be deleted, so no
-- followup actions will occur
inlet.addExclude(base..'.'..k)
if cmd ~= "" then
cmd = cmd .. " && "
end
cmd = cmd..
'rm "'..event.source..base..'.'..k..
'" || /bin/true'
end
end
log("Normal", "Deleting all "..p)
spawnShell(event, cmd)
return
end
-- ignores other events.
inlet.discardEvent(event)
end,
-----
-- Removes excludes when convertions are finished
--
collect = function(event, exitcode)
local p = event.pathname
local ext = string.match(p, ".*%.([^.]+)$")
local base = string.match(p, "(.*)%.[^.]+$")
local inlet = event.inlet
if event.etype == "Create" or
event.etype == "Modify" or
event.etype == "Delete"
then
for k, _ in pairs(formats) do
inlet.rmExclude(base..'.'..k)
end
end
end,
}
sync{convert, source="magicdir", recursive=false}
{% endhighlight %}
This creates a local table of all supported file formats. The file formats are used as keys.
{% highlight lua %}
local formats = { jpg=true, gif=true, png=true, }
{% endhighlight %}
Configures actions to be instant and there is unlimits the amount the conversion to be done at once. Well not unlimited but set the limit pretty high.
{% highlight lua %}
convert = {
delay = 0,
maxProcesses = 99,
{% endhighlight %}
This script uses the _layer 1_ inlet interface altough it greps only single events and not lists. It does this instead of _layer 2_ as it needs to do common operations for all kind of events.
{% highlight lua %}
action = function(inlet)
local event = inlet.getEvent()
{% endhighlight %}
Ignores directories. As using _layer 1_ it has to explicitly discard events it does not spawn actions for.
{% highlight lua %}
if event.isdir then
-- ignores events on dirs
inlet.discardEvent(event)
return
end
{% endhighlight %}
Uses Lua string patterns to extract the file extension from the rest - here called base.
{% highlight lua %}
-- extract extension and basefilename
local p = event.pathname
local ext = string.match(p, ".*%.([^.]+)$")
local base = string.match(p, "(.*)%.[^.]+$")
{% endhighlight %}
Looks the extension up in the formats table. This can be done, since formats are keys in that table. If not an image format it bails out.
{% highlight lua %}
if not formats[ext] then
-- an unknown extenion
log("Normal", "not doing something on ."..ext)
inlet.discardEvent(event)
return
end
{% endhighlight %}
Following actions will done on "Create" and "Modify" events.
{% highlight lua %}
-- autoconvert on create and modify
if event.etype == "Create" or event.etype == "Modify" then
{% endhighlight %}
This script builds a bash command using a string.
{% highlight lua %}
-- builds one bash command
local cmd = ""
{% endhighlight %}
It iterates for all image formats and excludes the one which is the source image.
{% highlight lua %}
-- do for all other extensions
for k, _ in pairs(formats) do
if k ~= ext then
{% endhighlight %}
This is a little trick. It creates Exclusions for the converted images. As this images are not placed in a target directory but right next to the source image in the source directory they would otherwise trigger Create actions as well.
{% highlight lua %}
-- excludes files to be created, so no
-- followup actions will occur
inlet.addExclude(base..'.'..k)
{% endhighlight %}
And for every image to be converted adds the calls to the arguments. It uses ```" || /bin/true "``` to let the shell continue if one conversion fails. In that it chains the conversion with '&&' they will be called sequentially.
{% highlight lua %}
if cmd ~= "" then
cmd = cmd .. " && "
end
cmd = cmd..
'/usr/bin/convert "'..
event.source..p..'" "'..
event.source..base..'.'..k..
'" || /bin/true'
{% endhighlight %}
And eventually it spawns the shell doing the conversions and is finished.
{% highlight lua %}
end
end
log("Normal", "Converting "..p)
spawnShell(event, cmd)
return
end
{% endhighlight %}
For deletions it does technically something similar, but it deletes all other file formats of the image.
{% highlight lua %}
-- deletes all formats if you delete one
if event.etype == "Delete" then
-- builds one bash command
local cmd = ""
-- do for all other extensions
for k, _ in pairs(formats) do
if k ~= ext then
-- excludes files to be deleted, so no
-- followup actions will occur
inlet.addExclude(base..'.'..k)
if cmd ~= "" then
cmd = cmd .. " && "
end
cmd = cmd..
'rm "'..event.source..base..'.'..k..
'" || /bin/true'
end
end
log("Normal", "Deleting all "..p)
spawnShell(event, cmd)
return
end
{% endhighlight %}
and not to forget to nicely discard all other events.
{% highlight lua %}
-- ignores other events.
inlet.discardEvent(event)
end,
{% endhighlight %}
collect is called when the conversions finished. It will remove the temporary excludes again.
{% highlight lua %}
-----
-- Removes excludes when convertions are finished
--
collect = function(event, exitcode)
local p = event.pathname
local ext = string.match(p, ".*%.([^.]+)$")
local base = string.match(p, "(.*)%.[^.]+$")
local inlet = event.inlet
if event.etype == "Create" or
event.etype == "Modify" or
event.etype == "Delete"
then
for k, _ in pairs(formats) do
inlet.rmExclude(base..'.'..k)
end
end
end,
{% endhighlight %}
And finally use the configuration to watch "magicdir".
{% highlight lua %}
sync{convert, source="magicdir", recursive=false}
{% endhighlight %}

90
docs/manual/examples/gforce/index.md Normal file
View File

@ -0,0 +1,90 @@
---
layout: default
title: "Example: GForce"
tab: "manual/examples"
---
A Layer 3 [example](..) that forces a directory tree to be read/writeable by a group.
{% highlight lua %}
-----
-- User configuration file for lsyncd.
--
-- This example refers to a common problem in unix.
--
-- You have a shared directory for a set of users and you want
-- to ensure all users have read and write permissions on all
-- files in there. Unfortunally sometimes users mess with their
-- umask, and create files in there that are not read/write/deleteable
-- by others. Usually this involves frequent handfixes by a sysadmin,
-- or a cron job that recursively chmods/chowns the whole directory.
--
-- This is another approach to use lsyncd to continously fix permissions.
--
-- One second after a file is created/modified it checks for its permissions
-- and forces group permissions on it.
--
-- This example regards more the handcraft of bash scripting than lsyncd.
-- An alternative to this would be to load a Lua-Posix library and do the
-- permission changes right within the onAction handlers.
----
-- forces this group.
--
fgroup = "staff"
-----
-- script for all changes.
--
command =
-- checks if the group is the one enforced and sets them if not
'[[
perm=`stat -c %A ^sourcePathname`
if test `stat -c %G ^sourcePathname` != ]]..fgroup..'[[; then
/bin/chgrp ]]..fgroup..'[[ ^sourcePathname || /bin/true;
fi
]] ..
-- checks if the group permissions are rw and sets them
'[[
if test `expr match $perm "....rw"` = 0; then
/bin/chmod g+rw ^sourcePathname || /bin/true;
fi
]] ..
-- and forces the executable bit for directories.
'[[
if test -d ^sourcePathname; then
if test `expr match $perm "......x"` -eq 0; then
/bin/chmod g+x ^^sourcePathname || /bin/true;
fi
fi
]]
-- on startup recursively sets all group ownerships
-- all group permissions are set to 'rw'
-- and to executable flag for directories
--
-- the hash in the first line is important, otherwise due to the starting
-- slash, Lsyncd would think it is a call to the binary /bin/chgrp only
-- and would optimize the shell call away.
--
startup =
'[[#
/bin/chgrp -R ]]..fgroup..'[[ ^source || /bin/true &&
/bin/chmod -R g+rw ^source || /bin/true &&
/usr/bin/find ^source -type d | xargs chmod g+x
]]
gforce = {
maxProcesses = 99,
delay = 1,
onStartup = startup,
onAttrib = command,
onCreate = command,
onModify = command,
-- does nothing on moves, they won't change permissions
onMove = true,
}
sync{gforce, source="/path/to/share"}
{% endhighlight %}

39
docs/manual/examples/index.md Normal file
View File

@ -0,0 +1,39 @@
---
layout: default
title: "Examples"
---
Layer 4 Examples
----------------
bash sync:
<pre>
sync{bash, source="/home/lonewolf/teste1", target="/home/lonewolf/teste2"}
</pre>
rsyncssh option:
<pre>
sync{default.rsyncssh,
source="/var/www/live_site_resources",
host="192.168.129.90",
targetdir="/var/www/live_site_resources",
delete="running",
exclude={ ".*", "*.tmp" },
rsync = {
compress = false,
checksums = false,
_extra = {"--bwlimit=50000"},
}
}
</pre>
Layer 3 Examples
----------------
* [GForce](gforce): forces a local directory tree to be read/writable by a group.
Layer 2 Examples
----------------
Layer 1 Examples
----------------
* [Auto Image Magic](auto-image-magic): creates a "magic" directory in which all images placed into will be converted to other file formats

76
docs/manual/invoking/index.md Normal file
View File

@ -0,0 +1,76 @@
---
layout: default
title: Invoking
---
As most Unix tools, Lsyncd will print a synopsis of its command line options when called with --help.
{% highlight shell %}
lsyncd --help
lsyncd -help
{% endhighlight %}
The two hyphens are redundant for Lsyncd. It has no short one letter options and one hyphen will always result into the same as specifying two.
Also like most Unix tools, ```--version``` or ```-version``` will let Lsyncd print its version number.
{% highlight shell %}
lsyncd -version
{% endhighlight %}
Lsyncd 2.1 is designed to be predominantly configured through a config file (see below). The config file can thus be the only command line option.
{% highlight shell %}
lsyncd CONFIGFILE
{% endhighlight %}
Although for standard use or quick testing it can be cursorily configured by command line options. The following will keep a local source and destination directory in sync using rsync:
{% highlight shell %}
lsyncd -rsync /home/USER/src /home/USER/dst
{% endhighlight %}
The target can here be anything that Rsync recognizes.
{% highlight shell %}
lsyncd -rsync /home/USER/src remotehost:dst
{% endhighlight %}
Two (or more) targets are configured by calling -rsync twice (or several times).
{% highlight shell %}
lsyncd -rsync /home/USER/src remotehost1:dst -rsync /home/USER/src remotehost2:dst
{% endhighlight %}
A disadvantage with Rsync synchronization is that normally directory and file moves result in a deletion of the move origin and a retransfer of the move destination of the wire. However, Lsyncd 2 can use ssh commands to move the directories and files locally on the target. To use this use ```-rsyncssh``` followed by the local source directory, the remote host and the target directory there. The REMOTEHOST can include a user like ```me@remotehost.com```.
{% highlight shell %}
lsyncd -rsyncssh /home/USER/src REMOTEHOST TARGETDIR
{% endhighlight %}
When testing Lsyncd configurations ```-nodaemon``` is a pretty handy flag. With this option, Lsyncd will not detach and will not become a daemon. All log messages are additionally to the configured logging facilities printed on the console (_stdout_ and _stderr_).
{% highlight shell %}
lsyncd -nodaemon CONFIGFILE
{% endhighlight %}
There is a difference in behaviour when running with -nodaemon. Lsyncd will not change its working directory to ```/```, as it does when becoming a daemon. Thus relative targets like ```./target``` will work with ```-nodaemon``` but must be specified to absolute paths to work in daemon mode. The source directories will also be turned into absolute paths by Lsyncd. The reason targets are not resolved to absolute paths while sources are is because Lsyncd itself does not care about the format of the target specifier which can also be remote hosts, rsyncd modules, etc. It is opaquely handed to rsync. It cares about the observed directories though.
All log messages are sorted in categories. By default Lsyncd is scarce with log messages. You can turn Lsyncd into a motormouth by specifying ```-log all```.
{% highlight shell %}
lsyncd -log all CONFIGFILE
{% endhighlight %}
This might easily become too much. A particularly useful category is "Exec" which will log the command lines of all processes Lsyncd spawns.
{% highlight shell %}
lsyncd -log Exec CONFIGFILE
{% endhighlight %}
When the initial startup sync fails by default Lsyncd will terminate with an error message. It has been designed this way, so configuration failures are visibly reported to a possibly beginning user. However, in production a remote target might be done, but you want Lsyncd to start nevertheless and keep trying to sync to the remote target until it is up.
{% highlight shell %}
lsyncd -insist -rsync /home/USER/src remotehost:dst
{% endhighlight %}
In production mode it is recommended to have insist on. It can also be specified in the settings{} command in a config file.

1
flake.nix
View File

@ -22,6 +22,7 @@
rsync
openssh
curl
jekyll
];
version = builtins.elemAt
(builtins.match ''.*set\(.LSYNCD_VERSION ([0-9\.]*).*''