Use github discussions

Added the 'filter' parameter to the manual

.editorconfig

@@ -0,0 +1,8 @@
+# 4 tab indentation
+
+indent_style = tab
+indent_size = 4
+
+[*.nix]
+indent_style = space
+indent_size = 2

.github/workflows/build.yaml

@@ -0,0 +1,20 @@
+name: "Build"
+on:
+  pull_request:
+  push:
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        version:
+          - lsyncd_lua5_3
+          # broken with lua 5.4.4. luac segfault
+          # - lsyncd_lua5_4
+          - lsyncd_lua5_1
+    steps:
+      - uses: actions/checkout@v2.4.0
+      - uses: cachix/install-nix-action@v15
+      - run: chmod og-rw ~
+      - run: nix develop .#${{ matrix.version }} --command ./tests/ci-run.sh

.gitignore

@@ -10,7 +10,7 @@ lsyncd
 AdditionalInfo.txt
 config.h
 Makefile
-build/
+build*/
 CMakeCache.txt
 CMakeFiles/
 cmake_install.cmake
@@ -21,3 +21,8 @@ install_manifest.txt
 
 defaults.c
 runner.c
+result
+tests/ssh
+
+# docs cache
+.jekyll-cache

CMakeLists.txt

@@ -1,7 +1,13 @@
 # preamble
 project( Lsyncd )
-cmake_minimum_required( VERSION 2.8 )
-set( LSYNCD_VERSION 2.2.2 )
+cmake_minimum_required( VERSION 3.5 )
+
+# extract version
+file(STRINGS "lsyncd.lua" LSYNCD_VERSION_RAW REGEX "lsyncd_version = '.*'")
+string(REGEX REPLACE "lsyncd_version = \'(.*)\'"
+       "\\1" LSYNCD_VERSION
+       ${LSYNCD_VERSION_RAW})
+
 set( CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${CMAKE_SOURCE_DIR}/cmake/" )
 
 
@@ -34,6 +40,9 @@ if( WITH_FSEVENTS )
 	include_directories( ${XNU_DIR} )
 endif( WITH_FSEVENTS )
 
+if ( APPLE )
+	set( LSYNCD_TARGET_APPLE 1 )
+endif ( APPLE )
 
 # generating the config.h file
 configure_file (
@@ -82,23 +91,45 @@ 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 ${CMAKE_COMMAND} -E make_directory ${CMAKE_CURRENT_BINARY_DIR}/man
+	COMMAND a2x --format=manpage ${PROJECT_SOURCE_DIR}/docs/manpage/lsyncd.1.txt -D ${CMAKE_CURRENT_BINARY_DIR}/man
+	DEPENDS docs/manpage/lsyncd.1.txt
 )
 
-add_custom_target( tests
+# the html documention
+add_custom_target( docs-html
+	COMMAND ${CMAKE_COMMAND} -E echo "Generate html documentation"
+	COMMAND env JEKYLL_ENV=local jekyll build -d ${CMAKE_CURRENT_BINARY_DIR}/html
+	WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}/docs
+	DEPENDS ${CMAKE_SOURCE_DIR}/docs
+)
+
+add_custom_command(
+    OUTPUT tests
+    COMMAND ${CMAKE_COMMAND} -E create_symlink ${CMAKE_SOURCE_DIR}/tests tests)
+
+ADD_CUSTOM_TARGET(prepare_tests ALL
+				  DEPENDS tests/
+)
+
+add_custom_target( run-tests
 	COMMAND echo "Running the tests"
 	COMMAND echo "Note you are expected to:"
 	COMMAND echo "  * have lua-posix installed"
-	COMMAND echo "  * have a passwordless ssh access to localhost"
-	COMMAND tests/schedule.lua
-	COMMAND tests/l4rsyncdata.lua
-	COMMAND tests/exclude-rsync.lua
-	COMMAND tests/exclude-rsyncssh.lua
-	COMMAND tests/churn-rsync.lua
-	COMMAND tests/churn-rsyncssh.lua
-	COMMAND tests/churn-direct.lua
+	COMMAND ${LUA_EXECUTABLE} ${CMAKE_SOURCE_DIR}/tests/setup.lua
+	COMMAND ${CMAKE_BINARY_DIR}/lsyncd -log all -script ${CMAKE_SOURCE_DIR}/tests/utils_test.lua
+	COMMAND ${LUA_EXECUTABLE} ${CMAKE_SOURCE_DIR}/tests/cron-rsync.lua
+	COMMAND ${LUA_EXECUTABLE} ${CMAKE_SOURCE_DIR}/tests/schedule.lua
+	COMMAND ${LUA_EXECUTABLE} ${CMAKE_SOURCE_DIR}/tests/l4rsyncdata.lua
+	COMMAND ${LUA_EXECUTABLE} ${CMAKE_SOURCE_DIR}/tests/filter-rsync.lua
+	COMMAND ${LUA_EXECUTABLE} ${CMAKE_SOURCE_DIR}/tests/exclude-rsync.lua
+	COMMAND ${LUA_EXECUTABLE} ${CMAKE_SOURCE_DIR}/tests/exclude-rsyncssh.lua
+	COMMAND ${LUA_EXECUTABLE} ${CMAKE_SOURCE_DIR}/tests/churn-rsync.lua
+	COMMAND ${LUA_EXECUTABLE} ${CMAKE_SOURCE_DIR}/tests/churn-rsyncssh.lua
+	COMMAND ${LUA_EXECUTABLE} ${CMAKE_SOURCE_DIR}/tests/churn-direct.lua
+	COMMAND ${LUA_EXECUTABLE} ${CMAKE_SOURCE_DIR}/tests/teardown.lua
 	COMMAND echo "Finished all successfull!"
+	DEPENDS prepare_tests
 )
 
 # compiling and linking it all together
@@ -106,4 +137,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 man )
+install( FILES ${CMAKE_CURRENT_BINARY_DIR}/man/lsyncd.1 DESTINATION ${CMAKE_INSTALL_MANDIR}/man1 COMPONENT man )
+install( DIRECTORY examples DESTINATION doc )
+install( DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html DESTINATION doc OPTIONAL)

ChangeLog

@@ -1,18 +1,41 @@
+2022-11-17: 2.3.1
+    change: multiple bugfixes, style fixes
+
+2022-03-09: 2.3.0
+    add: nix flake support
+	add: support for tunnel commands
+	add: support for batchSizeLimit
+	add: -onepass option
+	add: crontab support
+    change: support relative executable paths
+
+2018-03-09: 2.2.3
+	enhaencement: supporting includes with new filter and filterFrom options
+	change: needing now at least Lua 5.2 (Lua 5.1 no longer supported, Lua5.3 supported)
+	change: if the target/targetdir ends with a ':' do not append
+			a trailing '/' to it, since that would change it from homedir to rootdir!
+	add: example for Amazon S3 Bucket (Daniel Miranda)
+	fix: setting stdout/stderr to linebuffer mode.
+	fix: Lua5.3 compatiblity, using load() instead of loadstring()
+	fix: cmake lua detection, will resort to "lua" and "luac" binaries only if
+	     more specific suffixes (e.g. luac5.3) are not available
+	fix: test suit, Lua5.3 compatibility (table.unpack)
+
 2017-02-16: 2.2.2
-	 fix: checkgauge 'insist'
-	 fix: no partial path exlusion tests
-	 fix: write pid of forked process in pidfile
-	 fix: crash on not reachable target
-	 workaround:
-	    changed back to filter style rsync calling
-	    until https://bugzilla.samba.org/show_bug.cgi?id=12569
+	fix: checkgauge 'insist'
+	fix: no partial path exlusion tests
+	fix: write pid of forked process in pidfile
+	fix: crash on not reachable target
+	workaround:
+		changed back to filter style rsync calling
+		until https://bugzilla.samba.org/show_bug.cgi?id=12569
 		is fixed and released.
 
 2017-01-05: 2.2.1
 	enhancement: now always using filter lists with rysnc
 		instead of include/exclude lists taking advantage of the new --delete-missing-args
 		parameter to delete files on target.
-		>>> Thus Lsyncd 2.1.1 needs rsync >= 3.1.0
+		>>> Thus Lsyncd 2.2.1 needs rsync >= 3.1.0
 	change: added "tests" make target to run all the tests.
 	fix: crash due to typo in changed ^path, ^pathdir, ^pathname
 

INSTALL

@@ -15,22 +15,22 @@ Prerequisites
   Lua
 
     For building Lsyncd the Lua interpreter 'lua'
-	and the Lua compiler 'luac' are needed.
-	They aren't needed in the deployed binary though.
-	
-	Use Lua 5.1 or Lua 5.2 at your choice.
+    and the Lua compiler 'luac' are needed.
+    They aren't needed in the deployed binary though.
+
+    Use Lua 5.2 or later.
 
   Liblua
 
     The lua library.
 	
-	Note that you likely need the package "liblua-dev"
-	or something like that.
+    Note that you likely need the package "liblua-dev"
+    or something like that.
 
-	Use Lua 5.1 or Lua 5.2 at your choice.
+    Use Lua 5.2 or later.
 
-	Note, this has to be exactly the same Version as the
-	lua compiler used above!
+    Note, this has to be exactly the same Version as the
+    lua compiler used above!
 
 
 Building
@@ -41,16 +41,16 @@ Building
     mkdir build
     cd build
     cmake ..
-	make
+    make
     sudo make install
 
   Building intree:
     cmake .
-	make
+    make
 
   On OSX you yet need to get the xnu sources.
   For example:
     cmake -DWITH_INOTIFY=OFF -DWITH_FSEVENTS=ON -DXNU_DIR=/path/to/xnu-VERSION
-	make
+    make
 
 FIXME make install not yet done

README.md

@@ -6,7 +6,7 @@ Lsyncd watches a local directory trees event monitor interface (inotify or fseve
 
 Rsync+ssh is an advanced action configuration that uses a SSH to act file and directory moves directly on the target instead of re-transmitting the move destination over the wire.
 
-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/). This way simple, powerful and flexible configurations can be acheived.  See [the manual](https://axkibe.github.io/lsyncd/) for details.
+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/). This way simple, powerful and flexible configurations can be achieved.  See [the manual](https://lsyncd.github.io/lsyncd/) for details.
 
 Lsyncd 2.2.1 requires rsync >= 3.1 on all source and target machines.
 
@@ -16,6 +16,13 @@ When to use
 -----------
 Lsyncd is designed to synchronize a local directory tree with low profile of expected changes to a remote mirror. Lsyncd is especially useful to sync data from a secure area to a not-so-secure area.
 
+2-way/bidirection synchronization
+---------------------------------
+It is not possible to use lsyncd to synchronize for example `folder1` with `folder2` and vice versa. Only one source to one target. Two way synchronization is a very hard problem that needs specialized tools.
+Imagine you start writing a very large file to `folder1`, lsyncd will start synchronizing this file to `folder2`, which might be on a different machine. The lsyncd on that machine will see a new file, and try to synchronize it back to `folder1`. If at the same time, you change bytes in this file, those changes will be overwritten with old data. Using lsyncd in such a way might work in practice, but data corruption is easily possible if you write into files afterwards.
+`git-annex` is a good way to do this, if you don't mind working with git repositories. It stores each change as a revision that can be rolled back.
+
+
 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.
@@ -24,6 +31,12 @@ Other synchronization tools
 
 [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.
 
+[git-annex](https://git-annex.branchable.com/) allows managing large files with git, without storing the file contents in git. It can sync, backup, and archive your data, offline and online. Checksums and encryption keep your data safe and secure. Bring the power and distributed nature of git to bear on your large files with git-annex.
+
+git-annex is designed for git users who love the command line. For everyone else, the git-annex assistant turns git-annex into an easy to use folder synchroniser.
+
+[Wikipedia](https://en.wikipedia.org/wiki/Comparison_of_file_synchronization_software) Comparison of file synchronization software
+
 Lsyncd usage examples
 ---------------------
 ```lsyncd -rsync /home remotehost.org::share/```
@@ -35,7 +48,7 @@ transfers them to 'remotehost' using the rsync-share 'share'.
 
 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.
 
-Some more complicated examples, tips and tricks you can find in the [manual](https://axkibe.github.io/lsyncd/).
+Some more complicated examples, tips and tricks you can find in the [manual](https://lsyncd.github.io/lsyncd/).
 
 Disclaimer
 ----------

cmake/FindLua.cmake

@@ -1,7 +1,7 @@
 # Locate Lua library
 # This module defines
 #  LUA_EXECUTABLE, if found
-#  LUA_FOUND, if false, do not try to link to Lua 
+#  LUA_FOUND, if false, do not try to link to Lua
 #  LUA_LIBRARIES
 #  LUA_INCLUDE_DIR, where to find lua.h
 #  LUA_VERSION_STRING, the version of Lua found (since CMake 2.8.8)
@@ -16,6 +16,7 @@
 #=============================================================================
 # Copyright 2007-2009 Kitware, Inc.
 # Modified to support Lua 5.2 by LuaDist 2012
+# Modified to support Lua 5.4 by LuaDist 2022
 #
 # Distributed under the OSI-approved BSD License (the "License");
 # see accompanying file Copyright.txt for details.
@@ -27,25 +28,19 @@
 # (To distribute this file outside of CMake, substitute the full
 #  License text for the above reference.)
 #
-# The required version of Lua can be specified using the
-# standard syntax, e.g. FIND_PACKAGE(Lua 5.1)
-# Otherwise the module will search for any available Lua implementation
+# This module will try to find the newest Lua version down to 5.4
 
 # Always search for non-versioned lua first (recommended)
 SET(_POSSIBLE_LUA_INCLUDE include include/lua)
-SET(_POSSIBLE_LUA_EXECUTABLE lua)
-SET(_POSSIBLE_LUA_COMPILER luac)
-SET(_POSSIBLE_LUA_LIBRARY lua)
+#SET(_POSSIBLE_LUA_EXECUTABLE lua)
+#SET(_POSSIBLE_LUA_COMPILER luac)
+#SET(_POSSIBLE_LUA_LIBRARY lua)
 
 # Determine possible naming suffixes (there is no standard for this)
-IF(Lua_FIND_VERSION_MAJOR AND Lua_FIND_VERSION_MINOR)
-  SET(_POSSIBLE_SUFFIXES "${Lua_FIND_VERSION_MAJOR}${Lua_FIND_VERSION_MINOR}" "${Lua_FIND_VERSION_MAJOR}.${Lua_FIND_VERSION_MINOR}" "-${Lua_FIND_VERSION_MAJOR}.${Lua_FIND_VERSION_MINOR}")
-ELSE(Lua_FIND_VERSION_MAJOR AND Lua_FIND_VERSION_MINOR)
-  SET(_POSSIBLE_SUFFIXES "53" "5.3" "-5.3" "52" "5.2" "-5.2" "51" "5.1" "-5.1")
-ENDIF(Lua_FIND_VERSION_MAJOR AND Lua_FIND_VERSION_MINOR)
+SET(_POSSIBLE_SUFFIXES "54" "5.4" "-5.4" "53" "5.3" "-5.3" "52" "5.2" "-5.2" "")
 
 # Set up possible search names and locations
-FOREACH(_SUFFIX ${_POSSIBLE_SUFFIXES})
+FOREACH(_SUFFIX IN LISTS _POSSIBLE_SUFFIXES)
   LIST(APPEND _POSSIBLE_LUA_INCLUDE "include/lua${_SUFFIX}")
   LIST(APPEND _POSSIBLE_LUA_EXECUTABLE "lua${_SUFFIX}")
   LIST(APPEND _POSSIBLE_LUA_COMPILER "luac${_SUFFIX}")
@@ -59,7 +54,7 @@ FIND_PROGRAM(LUA_EXECUTABLE
 
 # Find the lua executable
 FIND_PROGRAM(LUA_COMPILER
-  NAMES ${_POSSIBLE_LUA_COMPILER}
+  NAMES luac5.3 ${_POSSIBLE_LUA_COMPILER}
 )
 
 # Find the lua header
@@ -79,7 +74,7 @@ FIND_PATH(LUA_INCLUDE_DIR lua.h
 )
 
 # Find the lua library
-FIND_LIBRARY(LUA_LIBRARY 
+FIND_LIBRARY(LUA_LIBRARY
   NAMES ${_POSSIBLE_LUA_LIBRARY}
   HINTS
   $ENV{LUA_DIR}
@@ -108,14 +103,23 @@ ENDIF(LUA_LIBRARY)
 
 # Determine Lua version
 IF(LUA_INCLUDE_DIR AND EXISTS "${LUA_INCLUDE_DIR}/lua.h")
-  FILE(STRINGS "${LUA_INCLUDE_DIR}/lua.h" lua_version_str REGEX "^#define[ \t]+LUA_RELEASE[ \t]+\"Lua .+\"")
+  FILE(STRINGS "${LUA_INCLUDE_DIR}/lua.h" lua_version_major_str REGEX "^#define[ \t]+LUA_VERSION_MAJOR[ \t]+\".+\"")
+  FILE(STRINGS "${LUA_INCLUDE_DIR}/lua.h" lua_version_minor_str REGEX "^#define[ \t]+LUA_VERSION_MINOR[ \t]+\".+\"")
+  FILE(STRINGS "${LUA_INCLUDE_DIR}/lua.h" lua_version_release_str REGEX "^#define[ \t]+LUA_VERSION_RELEASE[ \t]+\".+\"")
 
-  STRING(REGEX REPLACE "^#define[ \t]+LUA_RELEASE[ \t]+\"Lua ([^\"]+)\".*" "\\1" LUA_VERSION_STRING "${lua_version_str}")
-  UNSET(lua_version_str)
+  STRING(REGEX REPLACE "^#define[ \t]+LUA_VERSION_MAJOR[ \t]+\"([^\"]+)\".*" "\\1" LUA_VERSION_MAJOR "${lua_version_major_str}")
+  STRING(REGEX REPLACE "^#define[ \t]+LUA_VERSION_MINOR[ \t]+\"([^\"]+)\".*" "\\1" LUA_VERSION_MINOR "${lua_version_minor_str}")
+  STRING(REGEX REPLACE "^#define[ \t]+LUA_VERSION_RELEASE[ \t]+\"([^\"]+)\".*" "\\1" LUA_VERSION_RELEASE "${lua_version_release_str}")
+  
+  STRING(CONCAT LUA_VERSION_STRING ${LUA_VERSION_MAJOR} "." ${LUA_VERSION_MINOR} "." ${LUA_VERSION_RELEASE})
+  
+  UNSET(lua_version_major_str)
+  UNSET(lua_version_minor_str)
+  UNSET(lua_version_release_str)
 ENDIF()
 
 INCLUDE(FindPackageHandleStandardArgs)
-# handle the QUIETLY and REQUIRED arguments and set LUA_FOUND to TRUE if 
+# handle the QUIETLY and REQUIRED arguments and set LUA_FOUND to TRUE if
 # all listed variables are TRUE
 FIND_PACKAGE_HANDLE_STANDARD_ARGS(Lua
                                   REQUIRED_VARS LUA_LIBRARIES LUA_INCLUDE_DIR

config.h.in

@@ -4,3 +4,6 @@
 /* File event notification mechanims available */
 #cmakedefine WITH_INOTIFY 1
 #cmakedefine WITH_FSEVENTS 1
+
+/* OS */
+#cmakedefine LSYNCD_TARGET_APPLE 1

default-direct.lua

@@ -1,7 +1,7 @@
 --~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 -- default-direct.lua
 --
---    Keeps two directories with /bin/cp, /bin/rm and /bin/mv in sync.
+--    Keeps two directories with cp, rm and mv in sync.
 --    Startup still uses rsync tough.
 --
 --    A (Layer 1) configuration.
@@ -61,7 +61,7 @@ direct.action = function(inlet)
 		if event.isdir then
 			spawn(
 				event,
-				'/bin/mkdir',
+				'mkdir',
 				'--',
 				event.targetPath
 			)
@@ -69,7 +69,7 @@ direct.action = function(inlet)
 			-- 'cp -t', not supported on OSX
 			spawn(
 				event,
-				'/bin/cp',
+				'cp',
 				'-p',
 				'--',
 				event.sourcePath,
@@ -81,7 +81,7 @@ direct.action = function(inlet)
 			error("Do not know how to handle 'Modify' on dirs")
 		end
 		spawn(event,
-			'/bin/cp',
+			'cp',
 			'-p',
 			'--',
 			event.sourcePath,
@@ -104,7 +104,7 @@ direct.action = function(inlet)
 			error('Refusing to erase your harddisk!')
 		end
 
-		spawn(event, '/bin/rm', '-rf', '--', tp)
+		spawn(event, 'rm', '-rf', '--', tp)
 
 	elseif event.etype == 'Move' then
 		local tp = event.targetPath
@@ -114,13 +114,13 @@ direct.action = function(inlet)
 			error('Refusing to erase your harddisk!')
 		end
 
-		local command = '/bin/mv -- "$1" "$2" || /bin/rm -rf -- "$1"'
+		local command = 'mv -- "$1" "$2" || rm -rf -- "$1"'
 
 		if
 			config.delete ~= true and
 			config.delete ~= 'running'
 		then
-			command = '/bin/mv -- "$1" "$2"'
+			command = 'mv -- "$1" "$2"'
 		end
 
 		spawnShell(
@@ -129,7 +129,16 @@ direct.action = function(inlet)
 			event.targetPath,
 			event2.targetPath
 		)
+	elseif event.etype == 'Full' then
+		local tp = event.targetPath
 
+		-- extra security check
+		if tp == '' or tp == '/' or not tp then
+			error('Refusing to erase your harddisk!')
+		end
+
+		-- trigger full sync function
+		direct.full(event)
 	else
 		log('Warn', 'ignored an event of type "',event.etype, '"')
 		inlet.discardEvent(event)
@@ -177,6 +186,12 @@ end
 --
 direct.init = default.rsync.init
 
+--
+-- Spawns the recursive startup sync
+-- (currently) identical to default rsync.
+--
+direct.full = default.rsync.full
+
 --
 -- Checks the configuration.
 --

default-rsync.lua

@@ -16,16 +16,9 @@
 --~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 
-if not default
-then
-	error( 'default not loaded' )
-end
+if not default then error( 'default not loaded' ) end
 
-
-if default.rsync
-then
-	error( 'default-rsync already loaded' )
-end
+if default.rsync then error( 'default-rsync already loaded' ) end
 
 
 local rsync = { }
@@ -49,7 +42,10 @@ rsync.checkgauge = {
 	delete      =  true,
 	exclude     =  true,
 	excludeFrom =  true,
+	filter      =  true,
+	filterFrom  =  true,
 	target      =  true,
+	batchSizeLimit = true,
 
 	rsync  = {
 		acls              =  true,
@@ -66,7 +62,9 @@ rsync.checkgauge = {
 		compress          =  true,
 		copy_dirlinks     =  true,
 		copy_links        =  true,
+		copy_unsafe_links =  true,
 		cvs_exclude       =  true,
+		delete_excluded   =  true,
 		dry_run           =  true,
 		executability     =  true,
 		existing          =  true,
@@ -105,66 +103,25 @@ rsync.checkgauge = {
 }
 
 
---
--- Returns true for non Init and Blanket events.
---
-local eventNotInitBlank =
-	function
-(
-	event
-)
-	return event.etype ~= 'Init' and event.etype ~= 'Blanket'
-end
-
-
---
--- Replaces what rsync would consider filter rules by literals.
---
-local replaceRsyncFilter =
-	function
-(
-	path
-)
-	if not path
-	then
-		return
-	end
-
-	return(
-		path
-		:gsub( '%?', '\\?' )
-		:gsub( '%*', '\\*' )
-		:gsub( '%[', '\\[' )
+-- internal function to actually do the transfer
+local run_action = function
+	(
+		inlet,
+		elist
 	)
-end
-
-
---
--- Spawns rsync for a list of events
---
--- Exclusions are already handled by not having
--- events for them.
---
-rsync.action = function
-(
-	inlet
-)
 	local config = inlet.getConfig( )
 
-	-- gets all events ready for syncing
-	local elist = inlet.getEvents( eventNotInitBlank )
-
-	-- gets the list of paths for the event list
-	-- deletes create multi match patterns
-	local paths = elist.getPaths( )
+	local substitudes = inlet.getSubstitutionData(elist, {})
+	local target = substitudeCommands(config.target, substitudes)
 
 	--
 	-- Replaces what rsync would consider filter rules by literals
 	--
-	local function sub( p )
-		if not p then
-			return
-		end
+	local function sub
+	(
+		p  -- pattern
+	)
+		if not p then return end
 
 		return p:
 			gsub( '%?', '\\?' ):
@@ -179,8 +136,14 @@ rsync.action = function
 	-- Deletes create multi match patterns
 	--
 	local paths = elist.getPaths(
-		function( etype, path1, path2 )
-			if string.byte( path1, -1 ) == 47 and etype == 'Delete' then
+		function
+		(
+			etype,  -- event type
+			path1,  -- path
+			path2   -- path to for move events
+		)
+			if string.byte( path1, -1 ) == 47 and etype == 'Delete'
+			then
 				return sub( path1 )..'***', sub( path2 )
 			else
 				return sub( path1 ), sub( path2 )
@@ -195,11 +158,11 @@ rsync.action = function
 	local filterP = { }
 
 	-- adds one path to the filter
-	local function addToFilter( path )
-
-		if filterP[ path ] then
-			return
-		end
+	local function addToFilter
+	(
+		path
+	)
+		if filterP[ path ] then return end
 
 		filterP[ path ] = true
 
@@ -211,21 +174,21 @@ rsync.action = function
 	-- rsync needs to have entries for all steps in the path,
 	-- so the file for example d1/d2/d3/f1 needs following filters:
 	-- 'd1/', 'd1/d2/', 'd1/d2/d3/' and 'd1/d2/d3/f1'
-	for _, path in ipairs( paths ) do
-
-		if path and path ~= '' then
-
-			addToFilter(path)
+	for _, path in ipairs( paths )
+	do
+		if path and path ~= ''
+		then
+			addToFilter( path )
 
 			local pp = string.match( path, '^(.*/)[^/]+/?' )
 
-			while pp do
-				addToFilter(pp)
+			while pp
+			do
+				addToFilter( pp )
+
 				pp = string.match( pp, '^(.*/)[^/]+/?' )
 			end
-
 		end
-
 	end
 
 	log(
@@ -255,11 +218,126 @@ rsync.action = function
 		'--include-from=-',
 		'--exclude=*',
 		config.source,
-		config.target
+		target
 	)
 end
 
 
+--
+-- Returns true for non Init and Blanket events.
+--
+local eventNotInitBlank =
+       function
+(
+       event
+)
+       return event.etype ~= 'Init' and event.etype ~= 'Blanket'
+end
+
+--
+-- Returns size or true if the event is for batch processing
+--
+local getBatchSize =
+	function
+(
+	event
+)
+	-- print("getBatchSize", event, event.status, event.etype, event.pathname)
+	if event.status == 'active' then
+		return false
+	end
+	if event.etype == 'Init' or event.etype == 'Blanket' or event.etype == 'Full' then
+		return false
+	end
+	-- moves and deletes go always into batch
+	if event.etype == 'Move' or event.etype == 'Delete' then
+		return true
+	end
+	return lsyncd.get_file_size(event.sourcePath)
+end
+
+--
+-- Spawns rsync for a list of events
+--
+-- Exclusions are already handled by not having
+-- events for them.
+--
+rsync.action = function
+	(
+		inlet
+	)
+	local sizeLimit = inlet.getConfig().batchSizeLimit
+
+	if sizeLimit == nil then
+		-- gets all events ready for syncing
+		return run_action(inlet, inlet.getEvents(eventNotInitBlank))
+	else
+		-- spawn all files under the size limit/deletes/moves in batch mode
+		local eventInBatch = function(event)
+			if event.etype == "Full" then
+				return false
+			end
+			local size = getBatchSize(event)
+			if type(size) == "boolean" then
+				return size
+			elseif size == nil then
+				return true
+			end
+			if size <= sizeLimit then
+				return true
+			end
+			return false
+		end
+
+		-- indicator for grabbing one element of the queue
+		local single_returned = false
+		-- grab all events for seperate transfers
+		local eventNoBatch = function(event)
+			if event.etype == "Full" then
+				return false
+			end
+			local size = getBatchSize(event)
+			if type(size) ~= "number" or size == nil then
+				return false
+			end
+			if single_returned then
+				return 'break'
+			end
+			if size > sizeLimit then
+				single_returned = true
+				return true
+			end
+			return false
+		end
+		local extralist = inlet.getEvents(eventInBatch)
+
+		-- get all batched events
+		if extralist.size() > 0 then
+			run_action(inlet, extralist)
+		end
+
+		while true do
+			local cnt, maxcnt = lsyncd.get_process_info()
+			if inlet.getSync().processes:size( ) >= inlet.getConfig().maxProcesses then
+				log('Normal',
+				'Maximum processes for sync reached. Delaying large transfer for sync: '..inlet.getConfig().name)
+				break
+			elseif maxcnt and cnt >= maxcnt then
+			log('Normal',
+				'Maximum process count reached. Delaying large transfer for sync: '..inlet.getConfig().name)
+				break
+			end
+			local extralist = inlet.getEvents(eventNoBatch)
+
+			-- no more single size events
+			if extralist.size() == 0 then break end
+			run_action(inlet, extralist)
+			-- get next result
+			single_returned = false
+		end
+	end
+end
+
 ----
 ---- NOTE: This optimized version can be used once
 ----       https://bugzilla.samba.org/show_bug.cgi?id=12569
@@ -328,13 +406,25 @@ rsync.init = function
 (
 	event
 )
+	return rsync.full(event)
+end
+
+--
+-- Triggers a full sync event
+--
+rsync.full = function
+	(
+		event
+	)
 	local config   = event.config
 
 	local inlet    = event.inlet
 
 	local excludes = inlet.getExcludes( )
 
-	local delete   = nil
+	local filters = inlet.hasFilters( ) and inlet.getFilters( )
+
+	local delete   = {}
 
 	local target   = config.target
 
@@ -348,18 +438,26 @@ rsync.init = function
 		target = config.host .. ':' .. config.targetdir
 	end
 
+	local substitudes = inlet.getSubstitutionData(event, {})
+	target = substitudeCommands(target, substitudes)
+
 	if config.delete == true
 	or config.delete == 'startup'
 	then
 		delete = { '--delete', '--ignore-errors' }
 	end
 
-	if #excludes == 0
+	if config.rsync.delete_excluded == true
 	then
-		-- starts rsync without any excludes
+		table.insert( delete, '--delete-excluded' )
+	end
+
+	if not filters and #excludes == 0
+	then
+		-- starts rsync without any filters or excludes
 		log(
 			'Normal',
-			'recursive startup rsync: ',
+			'recursive full rsync: ',
 			config.source,
 			' -> ',
 			target
@@ -375,14 +473,15 @@ rsync.init = function
 			target
 		)
 
-	else
+	elseif not filters
+	then
 		-- starts rsync providing an exclusion list
 		-- on stdin
 		local exS = table.concat( excludes, '\n' )
 
 		log(
 			'Normal',
-			'recursive startup rsync: ',
+			'recursive full rsync: ',
 			config.source,
 			' -> ',
 			target,
@@ -401,6 +500,32 @@ rsync.init = function
 			config.source,
 			target
 		)
+	else
+		-- starts rsync providing a filter list
+		-- on stdin
+		local fS = table.concat( filters, '\n' )
+
+		log(
+			'Normal',
+			'recursive full rsync: ',
+			config.source,
+			' -> ',
+			target,
+			' filtering\n',
+			fS
+		)
+
+		spawn(
+			event,
+			config.rsync.binary,
+			'<', fS,
+			'--filter=. -',
+			delete,
+			config.rsync._computed,
+			'-r',
+			config.source,
+			target
+		)
 	end
 end
 
@@ -467,6 +592,7 @@ rsync.prepare = function
 
 	crsync._computed = { true }
 
+	--- @type any
 	local computed = crsync._computed
 
 	local computedN = 2
@@ -579,6 +705,12 @@ rsync.prepare = function
 		computedN = computedN  + 1
 	end
 
+	if crsync.copy_unsafe_links
+	then
+		computed[ computedN ] = '--copy-unsafe-links'
+		computedN = computedN  + 1
+	end
+
 	if crsync.groupmap
 	then
 		computed[ computedN ] = '--groupmap=' .. crsync.groupmap
@@ -647,11 +779,13 @@ rsync.prepare = function
 	end
 
 	-- appends a / to target if not present
-	if not skipTarget and string.sub(config.target, -1) ~= '/'
+	-- and not a ':' for home dir.
+	if not skipTarget
+	and string.sub( config.target, -1 ) ~= '/'
+	and string.sub( config.target, -1 ) ~= ':'
 	then
 		config.target = config.target..'/'
 	end
-
 end
 
 
@@ -671,7 +805,7 @@ rsync.exitcodes  = default.rsyncExitCodes
 rsync.rsync =
 {
 	-- The rsync binary to be called.
-	binary        = '/usr/bin/rsync',
+	binary        = 'rsync',
 	links         = true,
 	times         = true,
 	protect_args  = true

default-rsyncssh.lua

@@ -91,10 +91,7 @@ local replaceRsyncFilter =
 (
 	path
 )
-	if not path
-	then
-		return
-	end
+	if not path then return end
 
 	return(
 		path
@@ -105,6 +102,41 @@ local replaceRsyncFilter =
 end
 
 
+---
+--- Check if _extra arguments are of correct form
+---
+local checkSSH = function (args)
+	local SINGLES = "46AaCfGgKkMNnqsTtVvXxYy"
+	local needs_more = true
+	local is_data = false
+	local rv = true
+	for index, value in ipairs(args) do
+		if is_data == false then
+			if string.sub(value, 1, 1) ~= "-" then
+				log('Warn', "_extra argument does not start with -")
+				rv = false
+			end
+			needs_more = true
+		end
+		for i = 1, #SINGLES do
+			if string.sub(SINGLES, i, i) == string.sub(value, 2, 2) then
+				needs_more = false
+				break
+			end
+		end
+		if needs_more == false then
+			is_data = false
+		else
+			is_data = true
+		end
+	end
+	if needs_more == true then
+		log('Warn', "passend argument requires more arguments")
+		rv = false
+	end
+	return rv
+end
+
 --
 -- Spawns rsync for a list of events
 --
@@ -161,9 +193,7 @@ rsyncssh.action = function
 	-- Replaces what rsync would consider filter rules by literals
 	--
 	local function sub( p )
-		if not p then
-			return
-		end
+		if not p then return end
 
 		return p:
 			gsub( '%?', '\\?' ):
@@ -195,11 +225,7 @@ rsyncssh.action = function
 
 	-- adds one path to the filter
 	local function addToFilter( path )
-
-		if filterP[ path ]
-		then
-			return
-		end
+		if filterP[ path ] then return end
 
 		filterP[ path ] = true
 
@@ -372,7 +398,7 @@ rsyncssh.collect = function
 
 		if rc == 'ok'
 		then
-			log('Normal', 'Startup of "', agent.source, '" finished: ', exitcode)
+			log( 'Normal', 'Startup of "', agent.source, '" finished: ', exitcode )
 		elseif rc == 'again'
 		then
 			if settings('insist')
@@ -382,16 +408,16 @@ rsyncssh.collect = function
 				log(
 					'Error',
 					'Temporary or permanent failure on startup of "',
-					agent.source, '". Terminating since "insist" is not set.' 
+					agent.source, '". Terminating since "insist" is not set.'
 				)
 
 				terminate( -1 ) -- ERRNO
 			end
 		elseif rc == 'die'
 		then
-			log( 'Error', 'Failure on startup of "',agent.source,'": ', exitcode )
+			log( 'Error', 'Failure on startup of "', agent.source, '": ', exitcode )
 		else
-			log( 'Error', 'Unknown exitcode on startup of "', agent.source,': "',exitcode )
+			log( 'Error', 'Unknown exitcode on startup of "', agent.source, ': "', exitcode )
 
 			rc = 'die'
 		end
@@ -431,7 +457,7 @@ rsyncssh.collect = function
 		then
 			log( 'Normal', 'Failure ', agent.etype, ' ', agent.sourcePath, ': ', exitcode )
 		else
-			log( 'Error', 'Unknown exitcode ',agent.etype,' ',agent.sourcePath,': ',exitcode )
+			log( 'Error', 'Unknown exitcode ', agent.etype,' ', agent.sourcePath,': ', exitcode )
 
 			rc = 'die'
 		end
@@ -453,18 +479,12 @@ rsyncssh.prepare = function
 
 	if not config.host
 	then
-		error(
-			'default.rsyncssh needs "host" configured',
-			level
-		)
+		error( 'default.rsyncssh needs "host" configured', level )
 	end
 
 	if not config.targetdir
 	then
-		error(
-			'default.rsyncssh needs "targetdir" configured',
-			level
-		)
+		error( 'default.rsyncssh needs "targetdir" configured', level )
 	end
 
 	--
@@ -472,18 +492,12 @@ rsyncssh.prepare = function
 	--
 	if config.ssh._computed
 	then
-		error(
-			'please do not use the internal rsync._computed parameter',
-			level
-		)
+		error( 'please do not use the internal rsync._computed parameter', level )
 	end
 
 	if config.maxProcesses ~= 1
 	then
-		error(
-			'default.rsyncssh must have maxProcesses set to 1.',
-			level
-		)
+		error( 'default.rsyncssh must have maxProcesses set to 1.', level )
 	end
 
 	local cssh = config.ssh;
@@ -569,19 +583,34 @@ rsyncssh.prepare = function
 
 	if cssh._extra
 	then
+		if checkSSH(cssh._extra) == false then
+			log( 'Warn', 'The ssh._extra parameter is a list of arguments, ensure it is written correctly')
+		end
 		for k, v in ipairs( cssh._extra )
 		do
 			computed[ computedN ] = v
 
 			computedN = computedN  + 1
+
+            if not config.rsync._rshIndex
+		    then
+			    config.rsync._rshIndex = #rsyncc + 1
+
+			    rsyncc[ config.rsync._rshIndex ] = '--rsh=ssh'
+		    end
+
+		    rsyncc[ config.rsync._rshIndex ] =
+			    rsyncc[ config.rsync._rshIndex ] .. ' ' .. v
+
 		end
 	end
 
 	-- appends a slash to the targetdir if missing
+	-- and is not ':' for home dir
 	if string.sub( config.targetdir, -1 ) ~= '/'
+	and string.sub( config.targetdir, -1 ) ~= ':'
 	then
-		config.targetdir =
-			config.targetdir .. '/'
+		config.targetdir = config.targetdir .. '/'
 	end
 
 end
@@ -628,7 +657,7 @@ rsyncssh.ssh = {
 	--
 	-- the binary called
 	--
-	binary = '/usr/bin/ssh',
+	binary = 'ssh',
 
 	--
 	-- if set adds this key to ssh

default.lua

@@ -13,6 +13,7 @@ then
 	error( 'default already loaded' )
 end
 
+--- @diagnostic disable-next-line: lowercase-global
 default = { }
 
 
@@ -38,9 +39,11 @@ default.checkgauge = {
 	action        =  true,
 	checkgauge    =  true,
 	collect       =  true,
+	crontab       =  true,
 	delay         =  true,
 	exitcodes     =  true,
 	init          =  true,
+	full          =  true,
 	maxDelays     =  true,
 	maxProcesses  =  true,
 	onAttrib      =  true,
@@ -49,9 +52,11 @@ default.checkgauge = {
 	onDelete      =  true,
 	onStartup     =  true,
 	onMove        =  true,
+	onFull        =  true,
 	prepare       =  true,
 	source        =  true,
 	target        =  true,
+	tunnel        =  true,
 }
 
 --
@@ -120,7 +125,14 @@ default.collect = function
 				agent.target,
 				' finished.'
 			)
-
+			if settings('onepass')
+			then
+				log(
+					'Normal', 
+					'onepass config set, exiting'
+				)
+				terminate( 0 )
+			end
 			return 'ok'
 		elseif rc == 'again'
 		then
@@ -388,13 +400,10 @@ local function check
 )
 	for k, v in pairs( config )
 	do
-		if not gauge[k]
+		if not gauge[ k ]
 		then
 			error(
-				'Parameter "'
-				.. subtable
-				.. k
-				.. '" unknown.'
+				'Parameter "' .. subtable .. k .. '" unknown.'
 				.. ' ( if this is not a typo add it to checkgauge )',
 				level
 			);
@@ -405,10 +414,7 @@ local function check
 			if type( v ) ~= 'table'
 			then
 				error(
-					'Parameter "'
-					.. subtable
-					.. k
-					.. '" must be a table.',
+					'Parameter "' .. subtable .. k .. '" must be a table.',
 					level
 				)
 			end
@@ -432,10 +438,7 @@ default.prepare = function
 
 	local gauge = config.checkgauge
 
-	if not gauge
-	then
-		return
-	end
+	if not gauge then return end
 
 	check( config, gauge, '', level + 1 )
 end

docs/.gitignore

@@ -0,0 +1 @@
+_site/

docs/_config.yml

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

docs/_data/docs.yml

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

docs/_layouts/default.html

@@ -0,0 +1,93 @@
+{% if jekyll.environment == "local"
+%}{% assign suffix = 'index.html'
+%}{% else
+%}{% assign suffix = ''
+%}{% endif
+%}{% assign base = ''
+%}{% assign depth = page.url | split: '/' | size
+%}{% if depth <= 1
+%}{% assign base = '.'
+%}{% elsif depth == 2
+%}{% assign base = '..'
+%}{% elsif depth == 3
+%}{% assign base = '../..'
+%}{% elsif depth == 4
+%}{% assign base = '../../..'
+%}{% endif
+%}<!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="{{ base }}/css/main.css">
+  <link rel="stylesheet" type="text/css" href="{{ base }}/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="{{ base| append: p.url | append: suffix }}">{{ title }}</a></li>
+     {% endfor %}
+     </ul>
+    {% endfor %}
+    <div id="menufooter"></div>
+  </div>
+  <div id="ribbonwrap"><a href="https://github.com/lsyncd/lsyncd" id="ribbon"></a></div>
+  </nav>
+  <div id="container">
+  <a href="https://github.com/lsyncd/lsyncd/edit/master/docs{{ 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>

docs/_layouts/default3.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>

docs/appendices/devdocs/index.md

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

docs/css/main.css

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

docs/css/syntax.css

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

docs/download/index.md

@@ -0,0 +1,13 @@
+---
+layout: default
+title: "Download"
+---
+Current Release
+=======================
+All releases are on the [releases page](https://github.com/lsyncd/lsyncd/releases)
+
+HEAD Development
+================
+{% highlight shell %}
+git clone https://github.com/lsyncd/lsyncd.git
+{% endhighlight %}

docs/faq/index.md

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

docs/faq/multiple-targets/index.md

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

docs/faq/nothing-after-startup/index.md

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

docs/faq/postscript/index.md

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

docs/help/index.md

@@ -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://github.com/lsyncd/lsyncd/discussions)
+
+Issues
+------
+For cases Lsyncd is missbehaving there are [Issues](https://github.com/lsyncd/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/lsyncd/lsyncd)

docs/index.md

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

docs/manpage/lsyncd.1

@@ -1,7 +1,7 @@
 '\" t
 .\"     Title: lsyncd
 .\"    Author: [see the "AUTHOR" section]
-.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
+.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
 .\"      Date: January 2017
 .\"    Manual: Lsyncd
 .\"    Source: Lsyncd 2.2.1
@@ -44,7 +44,8 @@ default rsync behaviour
 \ \&
 \fBlsyncd\fR
 [\fIOPTIONS\fR] \-rsync
-\fISOURCEDIR\fR\fITARGET\fR
+\fISOURCEDIR\fR
+\fITARGET\fR
 \&...
 .RE
 .PP
@@ -53,7 +54,9 @@ default rync+ssh behaviour (moves and deletes through ssh)
 \ \&
 \fBlsyncd\fR
 [\fIOPTIONS\fR] \-rsyncssh
-\fISOURCEDIR\fR\fITARGETHOST\fR\fITARGETDIR\fR
+\fISOURCEDIR\fR
+\fITARGETHOST\fR
+\fITARGETDIR\fR
 \&...
 .RE
 .PP
@@ -62,7 +65,8 @@ default direct behaviour (local file operations/rsync)
 \ \&
 \fBlsyncd\fR
 [\fIOPTIONS\fR] \-direct
-\fISOURCEDIR\fR\fITARGETDIR\fR
+\fISOURCEDIR\fR
+\fITARGETDIR\fR
 \&...
 .RE
 .SH "DESCRIPTION"
@@ -71,7 +75,7 @@ Lsyncd(1) watches local directory trees through an event monitor interface (inot
 .sp
 Rsync+ssh is an advanced action configuration that uses a SSH(1) to act file and directory moves directly on the target instead of re\-transmitting the move destination over the wire\&.
 .sp
-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(1) language\&. This way simplicity can be balanced with powerfulness\&. See the online manual for details on the CONFIG\-FILE https://axkibe\&.github\&.io/lsyncd/config/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(1) language\&. This way simplicity can be balanced with powerfulness\&. See the online manual for details on the CONFIG\-FILE https://axkibe\&.github\&.io/lsyncd/manual/config/file/ \&.
 .sp
 Note that under normal configuration Lsyncd will delete pre\-existing files in the target directories that are not present in the respective source directory\&.
 .SH "OPTIONS"
@@ -145,13 +149,13 @@ Failure (syntax, unrecoverable error condition, internal failure)
 .RE
 .SH "SEE ALSO"
 .sp
-Online Manual: https://axkibe\&.github\&.io/lsyncd/
+Online Manual: https://lsyncd\&.github\&.io/lsyncd/
 .SH "VERSION"
 .sp
 This man page is for lsyncd(1) version 2\&.2\&.0
 .SH "AUTHOR"
 .sp
-Axel Kittenberger, <axkibe@gmail\&.com> 2010\-2017
+Axel Kittenberger, <axkibe@gmail\&.com> 2010\-2017 Daniel Poelzleithner, <poelzleithner@b1\-systems\&.de> 2021\-2023
 .SH "COPYING"
 .sp
 Copyright (C) 2010\-2017 Axel Kittenberger\&. Free use of this software is granted under the terms of the GNU General Public License (GPL) version 2, or any later version\&. Free redistrubition of this Documentation (/doc directory) is granted under the terms of the Creative Commons 3\&.0 Attribution License (CC\-3\&.0\-BY)\&.

docs/manpage/lsyncd.1.txt

@@ -41,7 +41,7 @@ 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(1) language.  This way simplicity
 can be balanced with powerfulness.  See the online manual for details on the
-CONFIG-FILE https://axkibe.github.io/lsyncd/config/file/ .
+CONFIG-FILE https://lsyncd.github.io/lsyncd/manual/config/file/ .
 
 Note that under normal configuration Lsyncd will delete pre-existing files in
 the target directories that are not present in the respective source directory.
@@ -69,6 +69,9 @@ OPTIONS
 *-nodaemon*::
 	Lsyncd will not detach from the invoker and log as well to stdout/err.
 
+*-onepass*::
+	Sync once and exit
+
 *-pidfile* 'FILE'::
 	Lsyncd will write its process ID in 'FILE'.
 
@@ -89,7 +92,7 @@ EXIT STATUS
 
 SEE ALSO
 --------
-Online Manual: https://axkibe.github.io/lsyncd/
+Online Manual: https://lsyncd.github.io/lsyncd/
 
 VERSION
 ------
@@ -98,6 +101,7 @@ This man page is for lsyncd(1) version 2.2.0
 AUTHOR
 ------
 Axel Kittenberger, <axkibe@gmail.com> 2010-2017
+Daniel Poelzleithner, <poelzleithner@b1-systems.de> 2021-2023
 
 COPYING
 -------

docs/manual/building/index.md

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

docs/manual/config/file/index.md

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

docs/manual/config/layer1/index.md

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

docs/manual/config/layer2/index.md

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

docs/manual/config/layer3/index.md

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

docs/manual/config/layer4/index.md

@@ -0,0 +1,735 @@
+---
+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:
+
+Shared Settings
+---------------
+
+Following settings are shared between all defaults:
+
+| Name            | Description      |
+|-----------------|------------------|
+| source          | Source directory |
+| crontab         | See section `Periodic Full-Sync`|
+
+
+
+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 %}
+
+Additional settings:
+| Name            | Description |
+|-----------------|-------------|
+| batchSizeLimit  | Files larger then this limit should not be batched into on transfer. Only makes sense with processes > 1 which prevents rsyncssh |
+
+
+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> filter
+</td><td> =
+</td><td> TABLE of STRINGS
+</td><td>
+</td><td> (Lsyncd >= 2.2.3)
+</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>
+
+Tunnels
+-------
+
+*New in: 2.3.0*
+
+Lsyncd is able to start and manage external programs to provide a tunnel for data transfer.
+Additionally it can spawn multiple connections and load-balance connections among them. A tunnel is created through the `tunnel` function.
+
+```
+{% highlight lua %}
+sync {
+    default.rsync,
+    tunnel    = tunnel {
+        command = {"ssh", "-N", "-L", "localhost:5432:localhost:873", "tunnel@testmachine"},
+    }
+    target    = "rsync://localhost:5432/projects",
+    source    = "/home/user/src/",
+}
+{% endhighlight %}
+```
+
+You can then set the shell for the tunnel user to `/bin/false` and configure the rsyncd server side appropriately.
+
+Valid arguments for `tunnel` are:
+
+| Argument   | Description                                           | Default   | Valid values                  |
+|------------|-------------------------------------------------------|-----------|-------------------------------|
+| mode       | Mode in which the tunnel is run                       | command   | command, pool                 |
+| command    | _Required_ Command to run                             | nil       | Table of arguments            |
+| parallel   | How many connections to run. Only for pool mode       | 1         | 1+                            |
+| retryDelay | Seconds to wait until tunnel is restarted             | 10        | Number                        |
+| readyDelay | Seconds after program start to consider tunnel up     | 5         | Number                        |
+| localhost  | Name of the local host variable                       | localhost | String                        |
+
+## Pool Mode
+
+In pool mode, lsyncd allocates a new local port which is then passed as variable to the host command.
+All variables can be substituded by `^variable` syntax.
+See [../../../../examples/lrsyncssh-tunnel.lua](lrsyncssh-tunnel.lua) for a extended configuration.
+
+### List of variables
+
+| Name       | Description                                   |
+|------------|-----------------------------------------------|
+| localport  | Port allocated for the selected connection    |
+| localhost  | Local hostname used. Default localhost        |
+
+### Example
+
+Run 2 tunnel ssh processes and 4 rsync processes at the same time. Use extra transfers for all files larger 30 MB.
+
+```lua
+sync {
+    default.rsync,
+    tunnel = tunnel {
+        command = {"ssh", "-N", "-L", "localhost:^localport:localhost:873", "user@testmachine"},
+        mode = "pool",
+        parallel = 2,
+    },
+    source = "/data/projects",
+    target    = "rsync://localhost:^localport/projects",
+    delay = 5,
+    batchSizeLimit = 1024 * 1024 * 30,
+    maxProcesses = 4
+}
+```
+
+This example will open 2 ssh connections for port forwarding and load balance 4 parallel rsync
+processes in a round roubin fashion.
+
+### Workflow in Poolmodel
+
+When a sync with a tunnel parameter is started, all events are queued until the tunnel reaches the
+ `UP` state, which is when one successful tunnel process exists for at least `readyDelay` seconds.
+Dead tunnel processes are automatically restarted. When the tunnel process count drops to 0, tunnel falls back to the
+`CONNECTING` state. There is a `retryDelay` seconds delay between each attempt to restart the tunnel.
+
+Once the tunnel is UP, a full transfer is initiated. Subsequent transfers are then load balanced over multiple connections.
+
+### Notes on Poolmode
+
+* Pool mode only works with `rsync` backend, since there is no way to prevent multiple transfers to the same file in a relieable way, the rsync backend only supports `maxProcesses = 1` which renders pool mode useless. Since the remote side rsync daemon can prevent file trashing, the rsync backend is safe.
+
+
+## Periodic Full-Sync
+
+*New in: 2.3.0*
+
+It is possible to trigger a full sync command from within lsync with the crontab feature. This requires that [lua-crontab](https://github.com/logiceditor-com/lua-crontab) is installed on the system. The crontab configuration accepts a list of `crontab` patterns to which a full sync will be triggered.
+
+```lua
+sync {
+    ...
+    crontab = {
+            -- does a full sync once a day at 3:00:01
+            "1 0 3 * * *",
+    },
+    ...
+}
+```
+
+### Field destination
+
+Each field is seperated by `" "` and can contain multiple values seperated by `,`.
+
+ |    FIELD     |     VALUES      | SPECIAL CHARACTERS |
+ |--------------|-----------------|--------------------|
+ | Seconds      | 0-59            |       , - *        |
+ | Minutes      | 0-59            |       , - *        |
+ | Hours        | 0-23            |       , - *        |
+ | Day of month | 1-31            |       , - *        |
+ | Month        | 1-12 or JAN-DEC |       , - *        |
+ | Day of week  | 0-6 or SUN-SAT  |       , - *        |
+

docs/manual/examples/auto-image-magic/index.md

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

docs/manual/examples/gforce/index.md

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

docs/manual/examples/index.md

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

docs/manual/invoking/index.md

@@ -0,0 +1,90 @@
+---
+layout: default
+title: Invoking
+---
+As most Unix tools, Lsyncd will print a synopsis of its command line options when called with --help. 
+
+```console
+lsyncd --help
+lsyncd -help
+```
+
+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.
+
+```console
+lsyncd -version
+```
+
+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.
+
+```console
+lsyncd CONFIGFILE
+```
+
+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:
+
+```console
+lsyncd -rsync /home/USER/src /home/USER/dst
+```
+
+The target can here be anything that Rsync recognizes.
+
+```console
+lsyncd -rsync /home/USER/src remotehost:dst
+```
+
+Two (or more) targets are configured by calling -rsync twice (or several times).
+
+```console
+lsyncd -rsync /home/USER/src remotehost1:dst -rsync /home/USER/src remotehost2:dst 
+```
+
+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```.
+
+```console
+lsyncd -rsyncssh /home/USER/src REMOTEHOST TARGETDIR
+```
+
+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_). 
+
+
+```console
+lsyncd -nodaemon CONFIGFILE
+```
+
+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.
+
+
+*New in 2.3.0*
+
+To only trigger the initial full sync and not monitor the file system, you can use the `-onepass` option.
+
+```console
+lsyncd -onepass CONFIGFILE
+```
+
+
+## Logging
+
+
+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```.
+
+```console
+lsyncd -log all CONFIGFILE
+```
+
+This might easily become too much. A particularly useful category is "Exec" which will log the command lines of all processes Lsyncd spawns.
+
+```console
+lsyncd -log Exec CONFIGFILE
+```
+
+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.
+
+```console
+lsyncd -insist -rsync /home/USER/src remotehost:dst
+```
+
+In production mode it is recommended to have insist on. It can also be specified in the settings{} command in a config file.

examples/lbash.lua

@@ -15,12 +15,12 @@ settings {
 -- for testing purposes. prefix can be used to slow commands down.
 -- prefix = "sleep 5 && "
 --
-prefix = ""
+local prefix = ""
 
 -----
 -- for testing purposes. uses bash command to hold local dirs in sync.
 --
-bash = {
+local bash = {
 	delay = 0,
 
 	maxProcesses = 1,

examples/lecho.lua

@@ -7,7 +7,7 @@
 -----
 -- for testing purposes. just echos what is happening.
 --
-echo = {
+local echo = {
 	maxProcesses = 1,
 	delay = 1,
 	onStartup = "/bin/echo telling about ^source",

examples/lgforce.lua

@@ -22,12 +22,12 @@
 ----
 -- forces this group.
 --
-fgroup = "staff"
+local fgroup = "staff"
 
 -----
 -- script for all changes.
 --
-command =
+local command =
 -- checks if the group is the one enforced and sets them if not
 [[
 perm=`stat -c %A ^sourcePathname`
@@ -59,13 +59,13 @@ fi
 -- the carret as first char tells Lsycnd to call a shell altough it
 -- starts with a slash otherwisw
 --
-startup =
+local 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 = {
+local gforce = {
 	maxProcesses = 99,
 	delay        = 1,
 	onStartup    = startup,

examples/limagemagic.lua

@@ -12,7 +12,7 @@
 --
 local formats = { jpg=true, gif=true, png=true,  }
 
-convert = {
+local convert = {
 	delay = 0,
 
 	maxProcesses = 99,

examples/lpostcmd.lua

@@ -24,24 +24,30 @@ local rsyncpostcmd = {
 	maxProcesses = 1,
 
 	-- called whenever something is to be done
-	action = function(inlet)
-		local event = inlet.getEvent()
-		local config = inlet.getConfig()
+	action = function
+	(
+		inlet
+	)
+		local event = inlet.getEvent( )
+		local config = inlet.getConfig( )
 		-- if the event is a blanket event and not the startup,
 		-- its there to spawn the webservice restart at the target.
-		if event.etype == "Blanket" then
+		if event.etype == 'Blanket'
+		then
 			-- uses rawget to test if "isPostcmd" has been set without
 			-- triggering an error if not.
-			local isPostcmd = rawget(event, "isPostcmd")
-			if isPostcmd then
+			local isPostcmd = rawget( event, 'isPostcmd' )
+
+			if isPostcmd
+			then
 				spawn(event, "/usr/bin/ssh",
 					config.host, config.postcmd)
-        		return
+				return
 			else
-            	-- this is the startup, forwards it to default routine.
-            	return default.rsync.action(inlet)
-        	end
-			error("this should never be reached")
+				-- this is the startup, forwards it to default routine.
+				return default.rsync.action(inlet)
+			end
+			error( 'this should never be reached' )
 		end
 		-- for any other event, a blanket event is created that
 		-- will stack on the queue and do the postcmd when its finished
@@ -53,33 +59,49 @@ local rsyncpostcmd = {
 
 	-- called when a process exited.
 	-- this can be a rsync command, the startup rsync or the postcmd
-	collect = function(agent, exitcode)
+	collect = function
+	(
+		agent,
+		exitcode
+	)
 		-- for the ssh commands 255 is network error -> try again
-		local isPostcmd = rawget(agent, "isPostcmd")
-		if not agent.isList and agent.etype == "Blanket" and isPostcmd then
-			if exitcode == 255 then
-				return "again"
-			end
+		local isPostcmd = rawget( agent, 'isPostcmd' )
+
+		if not agent.isList and agent.etype == "Blanket" and isPostcmd
+		then
+			if exitcode == 255 then return 'again' end
+
 			return
 		else
 			--- everything else, forward to default collection handler
-			return default.collect(agent,exitcode)
+			return default.collect( agent,exitcode )
 		end
-		error("this should never be reached")
+		error( 'this should never be reached' )
 	end,
 
 	-- called before anything else
 	-- builds the target from host and targetdir
-	prepare = function(config, level, skipTarget)
-		if not config.host then
-			error("rsyncpostcmd neets 'host' configured", 4)
+	prepare = function
+	(
+		config,
+		level,
+		skipTarget
+	)
+		if not config.host
+		then
+			error( 'rsyncpostcmd needs "host" configured', 4 )
 		end
-		if not config.targetdir then
-			error("rsyncpostcmd needs 'targetdir' configured", 4)
+
+		if not config.targetdir
+		then
+			error( 'rsyncpostcmd needs "targetdir" configured', 4)
 		end
-		if not config.target then
+
+		if not config.target
+		then
 			config.target = config.host .. ":" .. config.targetdir
 		end
+
 		return default.rsync.prepare(config, level, skipTarget)
 	end
 }
@@ -87,9 +109,10 @@ local rsyncpostcmd = {
 
 sync {
 	rsyncpostcmd,
-	source = "src",
-	host = "beetle",
-	targetdir = "/path/to/trg",
-	postcmd = "/usr/local/bin/restart-servelt.sh",
+	delay = 3,
+	source = '/path/to/src',
+	host = 'localhost',
+	targetdir = '/path/to/trg',
+	postcmd = '/usr/local/bin/dopostcmd',
 }
 

examples/lrsyncssh-advanced.lua

@@ -0,0 +1,35 @@
+settings {
+    logfile = "/home/lsync/job1/lsyncd.log",
+    statusFile = "/home/lsync/job1/lsyncd.status",
+    insist = true
+}
+
+sync {
+    default.rsyncssh,
+    source = "/data/projects",
+    host = "offsitehost",
+    targetdir = "/data/projects",
+    excludeFrom = "/home/lsync/job1/lsyncd.exclude",
+    delay = 5,
+    rsync = {
+            verbose = true,
+            inplace = true,
+            _extra = {
+                    "--info=progress2"
+            }
+    },
+    ssh = {
+            identityFile = "/home/lsync/.ssh/id_rsa_new",
+            options = {
+                    User = "poelzi",
+                    StrictHostKeyChecking = "no",
+                    Compression = "no",
+                    Cipher = "aes256-gcm@openssh.com"
+            },
+            _extra = {
+                    "-T",
+                    "-c",
+                    "aes256-gcm@openssh.com"
+            }
+    }
+}

examples/lrsyncssh-tunnel.lua

@@ -0,0 +1,33 @@
+-- This is an advanced tunnel config that uses the tunnel, load balancing
+-- and extra large file transfers
+
+sync {
+    default.rsync,
+    tunnel = tunnel {
+        command = {"ssh", "-N", "-L", "localhost:${localport}:localhost:873", "user@testmachine"},
+        mode = "pool",
+        parallel = 2,
+    },
+    crontab = {
+            -- does a full sync once a day at 3:00:01
+            "1 0 3 * * *"
+    },
+    source = "/data/projects",
+    target    = "rsync://localhost:${localport}/projects",
+    delay = 5,
+    batchSizeLimit = 1024 * 1024 * 30,
+    maxProcesses = 4,
+    rsync = {
+            inplace = true,
+    }
+}
+
+-- On your target machine configure rsyncd.conf like this:
+-- [projects]
+--   uid = myuser
+--   gid = mygroup
+--   path = /srv/projects
+--   read only = false
+
+-- If you restrict the ssh key or server to allow only port forwarding and no shell
+-- this is a very secure setup

examples/ls3.lua

@@ -0,0 +1,222 @@
+----
+-- Example lsyncd configuration for syncing with an Amazon S3 bucket
+--
+-- This requires the official AWS CLI to be available, and that credentials
+-- bet set up through some external method, such as environment variables,
+-- IAM profiles or the AWS SDK configuration.
+--
+-- The AWS CLI sync exclude rules are not as powerful as the ones supported by
+-- lsyncd. Hence, some of the do not translate perfectly. For example, '*'
+-- (asterisk) matches slashes, while it does not in lsyncd. Hence it is a good
+-- idea to only use exclude patterns for full directories, either by using a
+-- trailing / (slash) or ** (double asterisk), as those will be correctly
+-- translated.
+--
+-- An initialSync options is provided as a convenience, since it's not easy to
+-- make sure exclusion rules match when doing it manually. It will *pull* from
+-- the target bucket to the local dir (the opposite of the regular behavior)
+-- then exit immediately.
+--
+-- Author: Daniel Miranda <danielkza2@gmail.com>
+--
+local s3 = {}
+
+s3.checkgauge = {
+    onCreate  = false,
+    onModify  = false,
+    onDelete  = false,
+    onStartup = false,
+    onMove    = false,
+
+    delete      = true,
+    exclude     = true,
+    excludeFrom = true,
+    target      = true,
+
+    s3 = {
+        -- Path to the AWS CLI binary
+        awscliBinary  = true,
+        -- Extra options to pass to the AWS CLI (as a list)
+        awscliOptions = true,
+        -- Whether to do a dry-run, and not make any real changes
+        dryrun        = true,
+        -- Do an initial pull from the bucket and exit immediately.
+        initialSync   = true
+    }
+}
+
+-- Generate a list of exclude flags for the AWS CLI  based on the lsyncd
+-- patterns provided. Cache it to avoid re-generating it every time.
+
+local s3Excludes = function(config, excludes)
+    if config.s3._excludes == nil then
+        config.s3._excludes = {}
+        for _, pat in ipairs(excludes) do
+            pat = pat:gsub('%*%*', '[[ANY]]')
+            pat = pat:gsub('%?',   '[[ANY_BUT_SLASH_ONCE]]')
+            pat = pat:gsub('/$',   '/*')
+            pat = pat:gsub('%[%[ANY%]%]',                '*')
+            pat = pat:gsub('%[%[ANY_BUT_SLASH_ONCE%]%]', '[^/]')
+
+            if pat:match('^/') then
+                pat = pat:sub(2, -1)
+            else
+                pat = '*/' .. pat
+            end
+
+            table.insert(config.s3._excludes, '--exclude')
+            table.insert(config.s3._excludes, pat)
+        end
+
+        log('s3Excludes', table.concat(config.s3._excludes, '\n'))
+    end
+
+    return config.s3._excludes
+end
+
+-- Generates a command line to call the AWS CLI as configured, with the provided
+-- S3 action (such as cp, mv, rm or sync).
+-- Returns a tuple of (binaryPath, arguments)
+local awscliCommand = function(verb, config)
+    local bin = config.s3.awscliBinary
+    local args = {'s3', verb, '--only-show-errors'}
+    if config.s3.dryrun then
+        table.insert(args, '--dryrun')
+    end
+
+    if verb == 'sync'
+       and (config.delete == true or config.delete == 'startup')
+    then
+        table.insert(args, '--delete')
+    end
+
+    for _, opt in ipairs(config.s3.awscliOptions) do
+        table.insert(args, opt)
+    end
+
+    return bin, args
+end
+
+s3.action = function(inlet)
+    local event, event2 = inlet.getEvent()
+    -- S3 never actually deals with directories - they are just an illusion
+    -- created based on the common prefixes of objects. Hence discard any events
+    -- that do not concern files.
+    if event.isdir then
+        inlet.discardEvent(event)
+        return
+    end
+
+    local config = inlet.getConfig()
+    if event.etype == 'Create' or event.etype == 'Modify' then
+        local bin, args = awscliCommand('cp', config)
+        spawn(
+            event,
+            bin,
+            args,
+            event.sourcePath,
+            event.targetPath
+        )
+    elseif event.etype == 'Delete' then
+        if config.delete ~= true and config.delete ~= 'running' then
+            inlet.discardEvent(event)
+            return
+        end
+
+        local bin, args = awscliCommand('rm', config)
+        spawn(
+            event,
+            bin,
+            args,
+            event.targetPath
+        )
+    elseif event.etype == 'Move' then
+        local bin, args = awscliCommand('mv', config)
+        spawn(
+            event,
+            bin,
+            args,
+            event.targetPath,
+            event2.targetPath
+        )
+    else
+        log('Warn', 'ignored an event of type "', event.etype, '"')
+        inlet.discardEvent(event)
+    end
+end
+
+s3.init = function(event)
+    local config = event.config
+    local inlet = event.inlet
+    local excludes = s3Excludes(config, inlet.getExcludes())
+    local bin, args = awscliCommand('sync', config)
+
+    -- Do a pull when initialSync is enabled.
+    if config.s3.initialSync then
+        spawn(
+            event,
+            bin,
+            args,
+            excludes,
+            config.target,
+            event.sourcePath
+        )
+    -- And a push, as usual, otherwise
+    else
+        spawn(
+            event,
+            bin,
+            args,
+            excludes,
+            event.sourcePath,
+            config.target
+        )
+    end
+end
+
+-- Define a collect callback so we can terminate immediately when initialSync
+-- is enabled
+s3.collect = function(agent, exitcode)
+    local config = agent.config
+    if not agent.isList and agent.etype == 'Init' and config.s3.initialSync then
+        terminate(exitcode == 0 and 0 or -1)
+    end
+
+    return
+end
+
+s3.prepare = function(config, level)
+    default.prepare(config, level + 1)
+
+    config.target = config.target:gsub('/+$', '')
+    if not config.target:match('^s3://') then
+        config.target = 's3://' .. config.target
+    end
+end
+
+s3.s3 = {
+    awscliBinary  = '/usr/bin/aws',
+    awscliOptions = {},
+    dryrun       = false,
+    initialSync  = false
+}
+s3.delete       = false
+s3.delay        = 10
+s3.maxProcesses = 1
+
+sync {
+    s3,
+    source       = '/my/dir',
+    target       = 's3://my-bucket/my-path',
+    delay        = 30,
+    delete       = true,
+    maxProcesses = 2,
+    exclude = {
+        '/sub/folder/',
+    },
+    s3 = {
+        awscliBinary  = '/usr/local/bin/aws',
+        awscliOptions = {'--acl', 'public-read'},
+        dryrun        = false
+    }
+}

examples/lsayirc.lua

@@ -21,15 +21,16 @@ require("socket")
 
 -- For demo reasons, do not detach
 settings.nodaemon = true
-hostname = "irc.freenode.org"
+local hostname = "irc.freenode.org"
 --hostname = "127.0.0.1"
-port = 6667
-nick = "lbot01"
-chan = "##lfile01"
+local port = 6667
+local nick = "lbot01"
+local chan = "##lfile01"
 
 -- this blocks until the connection is established
 -- for once lets say this ok since Lsyncd didnt yet actually
 -- start.
+--- @diagnostic disable-next-line: undefined-global
 local ircSocket, err = socket.connect(hostname, port)
 if not ircSocket then
 	log("Error", "Cannot connect to IRC: ", err)

flake.lock

@@ -0,0 +1,43 @@
+{
+  "nodes": {
+    "flake-utils": {
+      "locked": {
+        "lastModified": 1659877975,
+        "narHash": "sha256-zllb8aq3YO3h8B/U0/J1WBgAL8EX5yWf5pMj3G0NAmc=",
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "rev": "c0e246b9b83f637f4681389ecabcb2681b4f3af0",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "type": "github"
+      }
+    },
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1666940097,
+        "narHash": "sha256-spcDvKqQU9iSMAjh5uj9gfu8Gu7vIFFkOKH2CCWvOVY=",
+        "owner": "nixos",
+        "repo": "nixpkgs",
+        "rev": "7269939a5d5610f2eec933607dc4d646394b29b8",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nixos",
+        "ref": "release-22.05",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "flake-utils": "flake-utils",
+        "nixpkgs": "nixpkgs"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

flake.nix

@@ -0,0 +1,174 @@
+{
+  description = "Lsyncd (Live Syncing Daemon)";
+  
+  inputs.nixpkgs.url = "github:nixos/nixpkgs/release-22.05";
+  inputs.flake-utils.url = "github:numtide/flake-utils";
+
+  outputs = { self, nixpkgs, flake-utils }:
+    flake-utils.lib.eachDefaultSystem
+      (system:
+        let
+          pkgs = (import nixpkgs {
+            inherit system;
+            # Makes the config pure as well. See <nixpkgs>/top-level/impure.nix:
+            config = {
+              allowBroken = true;
+            };}); #.legacyPackages.${system};
+          defaultDeps = with pkgs; [
+            glib
+            rsync
+            openssh
+          ];
+          nativeDeps = with pkgs; [
+            curl
+            asciidoc
+            jekyll
+            gcc
+            cmake
+            gnumake
+          ];
+          version = builtins.elemAt
+            (builtins.match ''.*lsyncd_version = '([0-9\.]*)'.*''
+              (builtins.substring 0 1200
+                (builtins.readFile ./lsyncd.lua))) 0;
+          # mylua5_4 = pkgs.lua5_4.override({
+          #   packageOverrides =  luaself: luaprev: {
+          #     luarocks = luaprev.luarocks-3_7;
+          #   };
+          # });
+          luaposix35 = mylua: mylua.pkgs.buildLuarocksPackage {
+            pname = "luaposix";
+            lua = mylua;
+            version = "35.1-1";
+            knownRockspec = (pkgs.fetchurl {
+              url    = "https://luarocks.org/luaposix-35.1-1.rockspec";
+              sha256 = "1n6c7qyabj2y95jmbhf8fxbrp9i73kphmwalsam07f9w9h995xh1";
+            }).outPath;
+            src = pkgs.fetchurl {
+              url    = "http://github.com/luaposix/luaposix/archive/v35.1.zip";
+              sha256 = "1c03chkzwr2p1wd0hs1bafl2890fqbrfc3qk0wxbd202gc6128zi";
+            };
+
+            #
+            propagatedBuildInputs = [ mylua ];
+
+            meta = {
+              homepage = "http://github.com/luaposix/luaposix/";
+              description = "Lua bindings for POSIX";
+              license.fullName = "MIT/X11";
+            };
+          };
+
+          buildExtensions = luapkgs: (
+            let
+              nucleo = luapkgs.buildLuarocksPackage {
+                pname = "lua-nucleo";
+                version = "1.1.0-1";
+                knownRockspec = (pkgs.fetchurl {
+                  url    = "https://luarocks.org/lua-nucleo-1.1.0-1.rockspec";
+                  sha256 = "02ly51wav1pxiahf6lflr4vks550bisdq4ir9cy1lxn9v2zmcbim";
+                }).outPath;
+                src = pkgs.fetchgit ( removeAttrs (builtins.fromJSON ''{
+                "url": "https://github.com/lua-nucleo/lua-nucleo.git",
+                "rev": "76835968ff30f182367abd58637560402990e0b1",
+                "date": "2021-04-26T11:51:34+03:00",
+                "path": "/nix/store/3ycmrh0j64qxm4f04yxmn3y42imc8bv5-lua-nucleo",
+                "sha256": "15kydmj64jhxv5ksayfgkwzmgzd7raj7xp636x8a7c3ybiirs90n",
+                "fetchSubmodules": true,
+                "deepClone": false,
+                "leaveDotGit": false
+              }
+              '') ["date" "path"]) ;
+
+                disabled = with luapkgs; (luaOlder "5.1");
+
+                meta = {
+                  homepage = "http://github.com/lua-nucleo/lua-nucleo";
+                  description = "A random collection of core and utility level Lua libraries";
+                  license.fullName = "MIT/X11";
+                };
+              };
+            in
+              luapkgs.buildLuarocksPackage {
+                pname = "lua-crontab";
+                version = "1.0.0-1";
+                knownRockspec = (pkgs.fetchurl {
+                  url    = "https://luarocks.org/lua-crontab-1.0.0-1.rockspec";
+                  sha256 = "1aynwxq488sxd2lyng4wnswfkqna5n07sfmdainlqlhcb6jan161";
+                }).outPath;
+                src = pkgs.fetchgit ( removeAttrs (builtins.fromJSON ''{
+                "url": "https://github.com/logiceditor-com/lua-crontab.git",
+                "rev": "e3929a572e8164f968da4dcbdf1c4464a2870699",
+                "date": "2021-07-29T14:12:08+03:00",
+                "path": "/nix/store/rsc49m4f1mjqbffaq7axcf31rgxxfjb3-lua-crontab",
+                "sha256": "0zkqslw3vg495k8g010cz931vlzfyynq4kcwi1jbbppia521z6rx",
+                "fetchSubmodules": true,
+                "deepClone": false,
+                "leaveDotGit": false
+              }
+              '') ["date" "path"]) ;
+
+                propagatedBuildInputs = [ nucleo ];
+
+                meta = {
+                  homepage = "http://github.com/logiceditor-com/lua-crontab";
+                  description = "Stores crontab-like rules for events and calculates timestamps for their occurrences";
+                  license.fullName = "MIT/X11";
+                };
+              }
+          );
+
+          buildTypes = { 
+            lua5_1 = [pkgs.lua5_1 pkgs.lua51Packages.luaposix (buildExtensions pkgs.lua51Packages)];
+            lua5_2 = [pkgs.lua5_2 pkgs.lua52Packages.luaposix (buildExtensions pkgs.lua52Packages)];
+            lua5_3 = [pkgs.lua5_3 pkgs.lua53Packages.luaposix (buildExtensions pkgs.lua53Packages)];
+            # lua5_4 = [mylua5_4pkgs.lua5_3 (luaposix35 mylua5_4)];
+            lua5_4 = [pkgs.lua5_4 (luaposix35 pkgs.lua5_4)  (buildExtensions pkgs.lua5_4.pkgs)];
+          };
+
+          # buildTypes = {
+          #   lua5_1 = [(pkgs.lua5_1.withPackages (ps: [ps.luaposix (buildExtensions pkgs.lua51Packages)]))];
+          #   lua5_2 = [(pkgs.lua5_2.withPackages (ps: [ps.luaposix (buildExtensions pkgs.lua52Packages)]))];
+          #   lua5_3 = [(pkgs.lua5_3.withPackages (ps: [ps.luaposix (buildExtensions pkgs.lua53Packages)]))];
+          #   lua5_4 = [(pkgs.lua5_4.withPackages (ps: [ps.luaposix (buildExtensions pkgs.lua54Packages)]))];
+          # };
+        in
+        let
+          mkLsync = luaPackages: pkgs.stdenv.mkDerivation ({
+            inherit version;
+            name = "lsyncd";
+
+            src = ./.;
+
+            buildPhase = ''
+              make all manpage docs-html
+            '';
+
+            buildInputs = defaultDeps ++ luaPackages;
+            nativeBuildInputs = nativeDeps;
+          });
+          mkDev = extras: pkgs.mkShell {
+            propagatedBuildInputs = defaultDeps ++ extras;
+          };
+        in
+        {
+          packages = {
+              lsyncd = mkLsync buildTypes.lua5_3;
+              lsyncd_lua5_1 = mkLsync buildTypes.lua5_1;
+              lsyncd_lua5_2 = mkLsync buildTypes.lua5_2;
+              lsyncd_lua5_3 = mkLsync buildTypes.lua5_3;
+              lsyncd_lua5_4 = mkLsync buildTypes.lua5_4;
+          };
+
+          devShells = {
+              lsyncd = mkDev buildTypes.lua5_3;
+              lsyncd_lua5_1 = mkDev buildTypes.lua5_1;
+              lsyncd_lua5_2 = mkDev buildTypes.lua5_2;
+              lsyncd_lua5_3 = mkDev buildTypes.lua5_3;
+              lsyncd_lua5_4 = mkDev buildTypes.lua5_4;
+          };
+
+          defaultPackage = self.packages.${system}.lsyncd;
+        }
+      );
+}

fsevents.c

@@ -153,6 +153,10 @@ handle_event(lua_State *L, struct kfs_event *event, ssize_t mlen)
 	const char *trg  = NULL;
 	const char *etype = NULL;
 	int isdir = -1;
+#ifdef LSYNCD_TARGET_APPLE \
+	// Since macOS 10.15, fsevent paths are prefixed with this string.
+	const char *const INOTIFY_PREFIX = "/System/Volumes/Data";
+#endif
 
 	if (event->type == FSE_EVENTS_DROPPED) {
 		logstring("Fsevents", "Events dropped!");
@@ -265,6 +269,11 @@ handle_event(lua_State *L, struct kfs_event *event, ssize_t mlen)
 		lua_pushstring(L, etype);
 		lua_pushboolean(L, isdir);
 		l_now(L);
+#ifdef LSYNCD_TARGET_APPLE
+		if (!strncmp(path, INOTIFY_PREFIX, strlen(INOTIFY_PREFIX ))) {
+			path += strlen(INOTIFY_PREFIX);
+		}
+#endif
 		lua_pushstring(L, path);
 		if (trg) {
 			lua_pushstring(L, trg);

inotify.c

@@ -222,10 +222,7 @@ handle_event(
 		// and overflow happened, tells the runner
 		load_runner_func( L, "overflow" );
 
-		if( lua_pcall( L, 0, 0, -2 ) )
-		{
-			exit( -1 );
-		}
+		if( lua_pcall( L, 0, 0, -2 ) ) exit( -1 );
 
 		lua_pop( L, 1 );
 
@@ -384,10 +381,7 @@ handle_event(
 		lua_pushnil( L );
 	}
 
-	if( lua_pcall( L, 7, 0, -9 ) )
-	{
-		exit( -1 );
-	}
+	if( lua_pcall( L, 7, 0, -9 ) ) exit( -1 );
 
 	lua_pop( L, 1 );
 
@@ -421,10 +415,7 @@ inotify_ready(
 	// sanity check
 	if( obs->fd != inotify_fd )
 	{
-		logstring(
-			"Error",
-			"internal failure, inotify_fd != ob->fd"
-		);
+		logstring( "Error", "internal failure, inotify_fd != obs->fd" );
 		exit( -1 );
 	}
 
@@ -574,13 +565,6 @@ open_inotify( lua_State *L )
 
 	close_exec_fd( inotify_fd );
 	non_block_fd( inotify_fd );
-
-	observe_fd(
-		inotify_fd,
-		inotify_ready,
-		NULL,
-		inotify_tidy,
-		NULL
-	);
+	observe_fd( inotify_fd, inotify_ready, NULL, inotify_tidy, NULL );
 }
 

lsyncd.c

@@ -19,6 +19,8 @@
 
 #define SYSLOG_NAMES 1
 
+#include <sys/socket.h>
+#include <netinet/in.h>
 #include <sys/select.h>
 #include <sys/stat.h>
 #include <sys/times.h>
@@ -46,6 +48,11 @@
 #include <lualib.h>
 #include <lauxlib.h>
 
+#if defined(LUA_VERSION_NUM) && LUA_VERSION_NUM >= 504
+#define lua_objlen lua_rawlen
+#endif
+
+
 /*
 | The Lua part of Lsyncd
 */
@@ -135,6 +142,22 @@ int pidfile_fd = 0;
 static long clocks_per_sec;
 
 
+/*
+| Dummy variable of which it's address is used as
+| the cores index in the lua registry to
+| the lua runners function table in the lua registry.
+*/
+static int runner;
+
+
+/*
+| Dummy variable of which it's address is used as
+| the cores index n the lua registry to
+| the lua runners error handler.
+*/
+static int callError;
+
+
 /**
  * signal handler
  */
@@ -438,6 +461,40 @@ printlogf0(lua_State *L,
 }
 
 
+/*
+ | Print a traceback of the error
+ */
+static int l_traceback (lua_State *L) {
+	// runner.callError
+    lua_getglobal(L, "debug");
+    lua_getfield(L, -1, "traceback");
+    lua_pushvalue(L, 1);
+    lua_pushinteger(L, 2);
+    lua_call(L, 2, 1);
+	printlogf( L, "traceback", "%s", lua_tostring(L, -1) );
+    return 1;
+}
+
+/*
+ | Call runners terminate function and exit with given exit code
+ */
+static void safeexit (lua_State *L, int exitcode) {
+	// load_runner_func(L, "teardown");
+	// pushes the function
+	lua_pushlightuserdata( L, (void *) &runner );
+	lua_gettable( L, LUA_REGISTRYINDEX );
+	lua_pushstring( L, "teardown" );
+	lua_gettable( L, -2 );
+	lua_remove( L, -2 );
+	lua_pushinteger(L, exitcode);
+    lua_call(L, 2, 1);
+	if (lua_isnumber(L, -1)) {
+		exitcode = luaL_checkinteger(L, -1);
+	}
+    exit(exitcode);
+}
+
+
 /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*
 (       Simple memory management            )
  *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/
@@ -605,23 +662,6 @@ pipe_tidy( struct observance * observance )
 (           Helper Routines                 )
  *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/
 
-
-/*
-| Dummy variable of which it's address is used as
-| the cores index in the lua registry to
-| the lua runners function table in the lua registry.
-*/
-static int runner;
-
-
-/*
-| Dummy variable of which it's address is used as
-| the cores index n the lua registry to
-| the lua runners error handler.
-*/
-static int callError;
-
-
 /*
 | Sets the close-on-exit flag of a file descriptor.
 */
@@ -697,7 +737,7 @@ write_pidfile
 			pidfile
 		);
 
-		exit( -1 );
+		safeexit(L, -1 );
 	}
 
 	int rc = lockf( pidfile_fd, F_TLOCK, 0 );
@@ -710,14 +750,21 @@ write_pidfile
 			pidfile
 		);
 
-		exit( -1 );
+		safeexit(L, -1 );
 	}
 
 	snprintf( buf, sizeof( buf ), "%i\n", getpid( ) );
 
-	write( pidfile_fd, buf, strlen( buf ) );
+	if (write( pidfile_fd, buf, strlen( buf ) ) != strlen(buf)) {
+		printlogf(
+			L, "Error",
+			"Cannot write pidfile; '%s'",
+			pidfile
+		);
+
+		safeexit(L, -1 );
+	}
 
-	//fclose( f );
 }
 
 
@@ -918,7 +965,7 @@ user_obs_ready(
 	// calls the user function
 	if( lua_pcall( L, 1, 0, -3 ) )
 	{
-		exit( -1 );
+		safeexit(L, -1 );
 	}
 
 	lua_pop( L, 2 );
@@ -954,7 +1001,7 @@ user_obs_writey(
 	// calls the user function
 	if( lua_pcall( L, 1, 0, -3 ) )
 	{
-		exit(-1);
+		safeexit(L, -1);
 	}
 
 	lua_pop( L, 2 );
@@ -1078,6 +1125,82 @@ l_now(lua_State *L)
 	return 1;
 }
 
+/*
+| Sends a signal to proceess pid
+|
+| Params on Lua stack:
+|     1: pid
+|     2: signal
+|
+| Returns on Lua stack:
+|     return value of kill
+*/
+static int
+l_kill( lua_State *L )
+{
+	pid_t pid = luaL_checkinteger( L, 1 );
+	int sig = luaL_checkinteger( L, 2 );
+
+	int rv = kill(pid, sig );
+
+	lua_pushinteger( L, rv );
+
+	return 1;
+}
+
+/*
+| Returns a free port of host
+|
+| Params on Lua stack:
+|    (not yet) 1: hostname or ip for bind
+|
+| Returns on Lua stack:
+|    return integer of free port
+|
+*/
+static int
+l_free_port(lua_State *L) {
+	int sock = socket(AF_INET, SOCK_STREAM, 0);
+	if(sock < 0) {
+		printf("error opening socket\n");
+		goto error;
+	}
+
+	struct sockaddr_in serv_addr;
+	memset((char *) &serv_addr, 0, sizeof(serv_addr));
+	serv_addr.sin_family = AF_INET;
+	serv_addr.sin_addr.s_addr = INADDR_ANY;
+	serv_addr.sin_port = 0;
+	if (bind(sock, (struct sockaddr *) &serv_addr, sizeof(serv_addr)) < 0) {
+		if(errno == EADDRINUSE) {
+			printf("the port is not available. already to other process\n");
+			goto error;
+		} else {
+			printf("could not bind to process (%d) %s\n", errno, strerror(errno));
+			goto error;
+		}
+	}
+
+	socklen_t len = sizeof(serv_addr);
+	if (getsockname(sock, (struct sockaddr *)&serv_addr, &len) == -1) {
+		goto error;
+	}
+
+	lua_pushinteger(L, ntohs(serv_addr.sin_port));
+
+	if (close (sock) < 0 ) {
+		printf("did not close: %s\n", strerror(errno));
+		lua_pop        ( L,  1 );
+		goto error;
+	}
+
+	return 1;
+error:
+	lua_pushnil(L);
+	return 1;
+}
+
+
 
 /*
 | Executes a subprocess. Does not wait for it to return.
@@ -1097,6 +1220,7 @@ l_exec( lua_State *L )
 {
 	// the binary to call
 	const char *binary = luaL_checkstring(L, 1);
+	l_stackdump(L);
 
 	// number of arguments
 	int argc = lua_gettop( L ) - 1;
@@ -1203,9 +1327,8 @@ l_exec( lua_State *L )
 				"in spawn(), expected a string after pipe '<'"
 			);
 
-			exit( -1 );
+			safeexit(L, -1 );
 		}
-
 		pipe_text = lua_tolstring( L, 3, &pipe_len );
 
 		if( strlen( pipe_text ) > 0 )
@@ -1215,7 +1338,7 @@ l_exec( lua_State *L )
 			{
 				logstring( "Error", "cannot create a pipe!" );
 
-				exit( -1 );
+				safeexit(L, -1 );
 			}
 
 			// always closes the write end for child processes
@@ -1278,7 +1401,7 @@ l_exec( lua_State *L )
 			}
 		}
 
-		execv( binary, ( char ** ) argv );
+		execvp( binary, ( char ** ) argv );
 
 		// in a sane world execv does not return!
 		printlogf(
@@ -1829,23 +1952,49 @@ l_nonobserve_fd( lua_State *L )
 	return 0;
 }
 
+/*
+| Returns file size of given path or nil on error
+|
+| Params on Lua stack:
+|     1:  path of filename
+*/
+extern int
+l_file_size( lua_State *L )
+{
+	struct stat sb;
+	const char *filename = luaL_checkstring( L, 1 );
 
+	if (stat(filename, &sb) == -1) {
+		lua_pushnil(L);
+		return 1;
+	}
+	lua_pushinteger(L, (long long) sb.st_size);
+
+	return 1;
+}
+
+
+static int l_jiffies_fromseconds(lua_State *L);
 /*
 | The Lsnycd's core library
 */
 static const luaL_Reg lsyncdlib[] =
-{
-	{ "configure",      l_configure     },
-	{ "exec",           l_exec          },
-	{ "log",            l_log           },
-	{ "now",            l_now           },
-	{ "nonobserve_fd",  l_nonobserve_fd },
-	{ "observe_fd",     l_observe_fd    },
-	{ "readdir",        l_readdir       },
-	{ "realdir",        l_realdir       },
-	{ "stackdump",      l_stackdump     },
-	{ "terminate",      l_terminate     },
-	{ NULL,             NULL            }
+{  
+	{ "configure",            l_configure     },
+	{ "exec",                 l_exec          },
+	{ "log",                  l_log           },
+	{ "now",                  l_now           },
+	{ "jiffies_from_seconds", l_jiffies_fromseconds},
+	{ "kill",                 l_kill          },
+	{ "get_free_port",        l_free_port     },
+	{ "nonobserve_fd",        l_nonobserve_fd },
+	{ "observe_fd",           l_observe_fd    },
+	{ "readdir",              l_readdir       },
+	{ "realdir",              l_realdir       },
+	{ "stackdump",            l_stackdump     },
+	{ "terminate",            l_terminate     },
+	{ "get_file_size",  	  l_file_size     },
+	{ NULL,                   NULL            }
 };
 
 
@@ -1861,7 +2010,7 @@ l_jiffies_add( lua_State *L )
 	if( p1 && p2 )
 	{
 		logstring( "Error", "Cannot add two timestamps!" );
-		exit( -1 );
+		safeexit(L, -1 );
 	}
 
 	{
@@ -1881,6 +2030,33 @@ l_jiffies_add( lua_State *L )
 	}
 }
 
+/*
+| Adds a number in seconds to a jiffy timestamp.
+*/
+static int
+l_jiffies_concat( lua_State *L )
+{
+	char buf[1024];
+	clock_t *p1 = ( clock_t * ) lua_touserdata( L, 1 );
+	clock_t *p2 = ( clock_t * ) lua_touserdata( L, 2 );
+
+	if( p1 && p2 )
+	{
+		logstring( "Error", "Cannot add two timestamps!" );
+		safeexit(L, -1 );
+	}
+
+	{
+		if (p1) {
+			snprintf( buf, sizeof(buf), "%Lf", (long double)(*p1));
+			lua_pushfstring(L, "%s%s", &buf, luaL_checkstring( L, 2));
+		} else {
+			snprintf( buf, sizeof(buf), "%Lf", (long double)(*p2));
+			lua_pushfstring(L, "%s%s", luaL_checkstring( L, 1), &buf);
+		}
+		return 1;
+	}
+}
 
 /*
 | Subracts two jiffy timestamps resulting in a number in seconds
@@ -1958,6 +2134,54 @@ l_jiffies_le(lua_State *L)
 	return 1;
 }
 
+/*
+| Converts a jiffies to a number
+*/
+static int
+l_jiffies_tonumber(lua_State *L)
+{
+	clock_t a1 = ( *( clock_t * ) luaL_checkudata( L, 1, "Lsyncd.jiffies" ) );
+
+	lua_pushinteger( L, a1 * clocks_per_sec);
+	return 1;
+}
+
+/*
+| Converts a jiffies to a number
+*/
+static int
+l_jiffies_fromseconds(lua_State *L)
+{
+	lua_Integer a1 = luaL_checkinteger(L, 1);
+
+	clock_t *r  = (clock_t *) lua_newuserdata( L, sizeof( clock_t ) );
+	luaL_getmetatable( L, "Lsyncd.jiffies" );
+	lua_setmetatable( L, -2 );
+
+	*r = a1 * clocks_per_sec;
+
+	return 1;
+}
+
+/*
+| Converts a jiffies to a number
+*/
+static int
+l_jiffies_index(lua_State *L)
+{
+	clock_t a1 = ( *( clock_t * ) luaL_checkudata( L, 1, "Lsyncd.jiffies" ) );
+	const char *a2 = luaL_checkstring(L, 2);
+
+	if (!strcmp(a2, "seconds")) {
+		lua_pushinteger( L, a1 / clocks_per_sec);
+		return 1;
+	} else if (!strcmp(a2, "string")) {
+		lua_pushfstring (L, "%d", a1 / clocks_per_sec);
+		return 1;
+	}
+	return 0;
+}
+
 
 /*
 | Registers the Lsyncd's core library.
@@ -1987,6 +2211,12 @@ register_lsyncd( lua_State *L )
 	lua_pushcfunction( L, l_jiffies_eq );
 	lua_setfield( L, mt, "__eq" );
 
+	lua_pushcfunction( L, l_jiffies_concat );
+	lua_setfield( L, mt, "__concat" );
+
+	lua_pushcfunction( L, l_jiffies_index );
+	lua_setfield( L, mt, "__index" );
+
 	lua_pop( L, 1 ); // pop(mt)
 
 #ifdef WITH_INOTIFY
@@ -2162,7 +2392,7 @@ masterloop(lua_State *L)
 
 		if( lua_pcall( L, 0, 1, -2 ) )
 		{
-			exit( -1 );
+			safeexit(L, -1 );
 		}
 
 		if( lua_type( L, -1 ) == LUA_TBOOLEAN)
@@ -2348,7 +2578,9 @@ masterloop(lua_State *L)
 			lua_pushinteger( L, WEXITSTATUS( status ) );
 
 			if ( lua_pcall( L, 2, 0, -4 ) )
-				{ exit(-1); }
+			{
+				safeexit(L, -1);
+			}
 
 			lua_pop( L, 1 );
 		}
@@ -2360,7 +2592,7 @@ masterloop(lua_State *L)
 
 			if( lua_pcall( L, 0, 0, -2 ) )
 			{
-				exit( -1 );
+				safeexit( L, -1 );
 			}
 
 			lua_pop( L, 1 );
@@ -2377,7 +2609,7 @@ masterloop(lua_State *L)
 
 			if( lua_pcall( L, 1, 0, -3 ) )
 			{
-				exit( -1 );
+				safeexit(L, -1 );
 			}
 
 			lua_pop( L, 1 );
@@ -2393,7 +2625,7 @@ masterloop(lua_State *L)
 
 		if( lua_pcall( L, 1, 1, -3 ) )
 		{
-			exit( -1 );
+			safeexit(L,  -1 );
 		}
 
 		if( !lua_toboolean( L, -1 ) )
@@ -2411,7 +2643,7 @@ masterloop(lua_State *L)
 				"internal, stack is dirty."
 			);
 			l_stackdump( L );
-			exit( -1 );
+			safeexit(L, -1 );
 		}
 	}
 }
@@ -2791,8 +3023,9 @@ main1( int argc, char *argv[] )
 				lsyncd_config_file,
 				lua_tostring( L, -1 )
 			);
+			l_traceback(L);
 
-			exit( -1 );
+			safeexit(L, -1 );
 		}
 	}
 
@@ -2889,6 +3122,9 @@ main( int argc, char * argv[ ] )
 	// gets a kernel parameter
 	clocks_per_sec = sysconf( _SC_CLK_TCK );
 
+	setlinebuf( stdout );
+	setlinebuf( stderr );
+
 	while( !term ) {
 		main1( argc, argv );
 	}

lsyncd.h

@@ -12,6 +12,7 @@
 #define LSYNCD_H
 
 // some older machines need this to see pselect
+#define _DEFAULT_SOURCE 1
 #define _BSD_SOURCE 1
 #define _XOPEN_SOURCE 700
 #define _DARWIN_C_SOURCE 1
@@ -56,6 +57,7 @@ extern struct settings {
 	int log_facility; // The syslog facility
 	int log_level;    // -1 logs everything, 0 normal mode, LOG_ERROR errors only.
 	bool nodaemon;    // True if Lsyncd shall not daemonize.
+	bool onepass;     // True if Lsyncd should exit after first sync pass
 	char * pidfile;   // If not NULL Lsyncd writes its pid into this file.
 
 } settings;

tests/churn-direct.lua

@@ -1,4 +1,3 @@
-#!/usr/bin/lua
 -- a heavy duty test.
 -- makes thousends of random changes to the source tree
 
@@ -13,7 +12,7 @@ cwriteln( '****************************************************************' )
 local tdir, srcdir, trgdir = mktemps( )
 
 -- makes some startup data
-churn( srcdir, 10, init )
+churn( srcdir, 10, false )
 
 local logs = { }
 --local logs = {'-log', 'Exec', '-log', 'Delay' }
@@ -21,7 +20,7 @@ local pid = spawn(
 	'./lsyncd',
 	'-nodaemon',
 	'-direct', srcdir, trgdir,
-	unpack( logs )
+	table.unpack( logs )
 )
 
 cwriteln( 'waiting for Lsyncd to startup' )
@@ -35,10 +34,10 @@ posix.sleep( 10 )
 cwriteln( 'killing the Lsyncd daemon' )
 posix.kill( pid )
 
-local _, exitmsg, lexitcode = posix.wait( lpid )
+local _, exitmsg, lexitcode = posix.wait( pid )
 cwriteln( 'Exitcode of Lsyncd = ', exitmsg, ' ', lexitcode )
 
-_, result, code = os.execute( 'diff -r ' .. srcdir .. ' ' .. trgdir )
+local result, code = execute( 'diff -r ' .. srcdir .. ' ' .. trgdir )
 
 if result == 'exit'
 then

tests/churn-rsync.lua

@@ -1,6 +1,6 @@
-#!/usr/bin/lua
 -- a heavy duty test.
 -- makes thousends of random changes to the source tree
+
 require( 'posix' )
 dofile( 'tests/testlib.lua' )
 
@@ -20,7 +20,7 @@ local pid = spawn(
 	'-nodaemon',
 	'-delay', '5',
 	'-rsync', srcdir, trgdir,
-	unpack( logs )
+	table.unpack( logs )
 )
 
 cwriteln( 'waiting for Lsyncd to startup' )
@@ -36,10 +36,10 @@ posix.sleep( 10 )
 cwriteln( 'killing the Lsyncd daemon' )
 
 posix.kill( pid )
-local _, exitmsg, lexitcode = posix.wait( lpid )
+local _, exitmsg, lexitcode = posix.wait( pid )
 cwriteln( 'Exitcode of Lsyncd = ', exitmsg, ' ', lexitcode )
 
-_, result, code = os.execute( 'diff -r ' .. srcdir .. ' ' .. trgdir )
+local result, code = execute( 'diff -r ' .. srcdir .. ' ' .. trgdir )
 
 if result == 'exit'
 then

tests/churn-rsyncssh.lua

@@ -1,4 +1,3 @@
-#!/usr/bin/lua
 -- a heavy duty test.
 -- makes thousends of random changes to the source tree
 
@@ -9,8 +8,6 @@ dofile( 'tests/testlib.lua' )
 cwriteln( '****************************************************************' )
 cwriteln( ' Testing default.rsyncssh with random data activity             ' )
 cwriteln( '****************************************************************' )
-cwriteln( '( this test needs passwordless ssh localhost access            )' )
-cwriteln( '( for current user                                             )' )
 
 local tdir, srcdir, trgdir = mktemps()
 
@@ -25,11 +22,13 @@ local pid = spawn(
 	'-nodaemon',
 	'-delay',
 	'5',
+	'-sshopts',
+	'-i tests/ssh/id_rsa -p 2468 -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null',
 	'-rsyncssh',
 	srcdir,
 	'localhost',
 	trgdir,
-	unpack(logs)
+	table.unpack(logs)
 )
 
 cwriteln( 'waiting for Lsyncd to startup' )
@@ -44,11 +43,11 @@ cwriteln( 'killing the Lsyncd daemon' )
 
 posix.kill(pid)
 
-local _, exitmsg, lexitcode = posix.wait( lpid )
+local _, exitmsg, lexitcode = posix.wait( pid )
 
 cwriteln( 'Exitcode of Lsyncd = ', exitmsg, ' ', lexitcode )
 
-_, result, code = os.execute( 'diff -r ' .. srcdir .. ' ' .. trgdir )
+local result, code = execute( 'diff -r ' .. srcdir .. ' ' .. trgdir )
 
 if result == 'exit'
 then

tests/ci-run.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+
+set -ex
+
+function cleanup() {
+        echo "** abort. cleanup ssh server"
+        cd `dirname $BASH_SOURCE`/..
+        # CLEANUP=`dirname $BASH_SOURCE`/../teardown.lua
+        lua tests/teardown.lua
+}
+
+trap cleanup INT EXIT
+
+SRC=`pwd`
+BUILD_FOLDER=`mktemp -d`
+echo "Build folder: $BUILD_FOLDER"
+cd $BUILD_FOLDER
+cmake $SRC
+make VERBOSE=1
+make run-tests
+rm -rf $BUILD_FOLDER

tests/cron-rsync.lua

@@ -0,0 +1,149 @@
+require( 'posix' )
+dofile( 'tests/testlib.lua' )
+
+cwriteln( '****************************************************************' )
+cwriteln( ' Testing crontab (rsync)' )
+cwriteln( '****************************************************************' )
+
+local tdir, srcdir, trgdir = mktemps( )
+local logfile = tdir .. "log"
+local cfgfile = tdir .. "config.lua"
+local range = 5
+local log = {"-log", "all"}
+
+writefile(cfgfile, [[
+settings {
+        logfile = "]]..logfile..[[",
+        nodaemon = true,
+}
+
+sync {
+        default.rsync,
+        crontab = {
+		-- trigger full sync every 1 minute
+                "*/10 * * * * *",
+        },
+        source = "]]..srcdir..[[",
+        action = function (inlet)
+                local e = inlet.getEvent( );
+                print("inhibit action ".. e.path.. " = " .. e.etype);
+                if e.etype ~= "Full" then
+                    inlet.discardEvent(e);
+                    return;
+                end
+                return default.rsync.action(inlet);
+        end,
+        target    = "]]..trgdir..[[",
+        delay = 2,
+        delete = true,
+        rsync = {
+                verbose = true,
+                inplace = true,
+                _extra = {
+                        "-vv",
+                        "--info=progress2"
+                }
+        },
+        filter = {
+            '- /xb**',
+            '+ /x**',
+            '- /**',
+        },
+}
+]])
+
+-- writes all files
+local function writefiles
+( )
+	writefile( srcdir .. 'xbc', 'xbc' )
+	writefile( srcdir .. 'xcc', 'xcc' )
+	writefile( srcdir .. 'yaa', 'yaa' )
+	posix.mkdir( srcdir .. 'xbx' )
+	writefile( srcdir .. 'xbx/a', 'xbxa' )
+	posix.mkdir( srcdir .. 'xcx' )
+	writefile( srcdir .. 'xcx/x', 'xcxx' )
+    writefile( srcdir .. 'xda', 'xda', '700' )
+    writefile( srcdir .. 'xdb', 'xdb', '755' )
+end
+
+-- test all files
+local function testfiles
+( )
+	testfile( trgdir .. 'xbc', false )
+	testfile( trgdir .. 'xcc', true )
+	testfile( trgdir .. 'yaa', false )
+	testfile( trgdir .. 'xbx/a', false )
+	testfile( trgdir .. 'xcx/x', true )
+	testfile( trgdir .. 'xda', true )
+	testfile( trgdir .. 'xdb', true )
+end
+
+
+cwriteln( 'testing crontab' )
+
+writefiles( )
+
+cwriteln( 'starting Lsyncd' )
+
+local pid = spawn( './lsyncd', cfgfile, '-log', 'all' )
+
+cwriteln( 'waiting for Lsyncd to start' )
+
+posix.sleep( 3 )
+
+cwriteln( 'testing filters after startup' )
+
+testfiles( )
+
+cwriteln( 'ok, removing sources' )
+
+if srcdir:sub( 1,4 ) ~= '/tmp'
+then
+	-- just to make sure before rm -rf
+	cwriteln( 'exit before drama, srcdir is "', srcdir, '"' )
+
+	os.exit( 1 )
+end
+
+os.execute( 'rm -rf '..srcdir..'/*' )
+
+cwriteln( 'waiting for Lsyncd to remove destination' )
+
+posix.sleep( 20 )
+
+local result, code = execute( 'diff -urN ' .. srcdir .. ' ' .. trgdir )
+
+if result ~= 'exit' or code ~= 0
+then
+	cwriteln( 'fail, target directory not empty!' )
+    posix.kill( pid )
+
+	os.exit( 1 )
+end
+
+cwriteln( 'writing files after startup' )
+
+writefiles( )
+
+cwriteln( 'waiting for Lsyncd to transmit changes' )
+
+posix.sleep( 20 )
+
+testfiles( )
+
+cwriteln( 'killing started Lsyncd' )
+
+posix.kill( pid )
+local _, exitmsg, exitcode = posix.wait( pid )
+
+cwriteln( 'Exitcode of Lsyncd = ', exitmsg, ' ', exitcode );
+
+if exitcode == 143
+then
+	cwriteln( 'OK' )
+	os.exit( 0 )
+else
+	os.exit( 1 )
+end
+
+-- TODO remove temp

tests/exclude-rsync.lua

@@ -1,16 +1,15 @@
-#!/usr/bin/lua
-require("posix")
-dofile("tests/testlib.lua")
+require( 'posix' )
+dofile( 'tests/testlib.lua' )
 
-cwriteln('****************************************************************' )
-cwriteln(' Testing excludes (rsync)' )
-cwriteln('****************************************************************' )
+cwriteln( '****************************************************************' )
+cwriteln( ' Testing excludes (rsync)' )
+cwriteln(' ****************************************************************' )
 
 local tdir, srcdir, trgdir = mktemps( )
-local logfile = tdir .. "log"
-local cfgfile = tdir .. "config.lua"
+local logfile = tdir .. 'log'
+local cfgfile = tdir .. 'config.lua'
 local range = 5
-local log = {"-log", "all"}
+local log = { '-log', 'all' }
 
 writefile(cfgfile, [[
 settings {
@@ -34,15 +33,15 @@ sync {
 -- writes all files
 local function writefiles
 ( )
-	posix.mkdir( srcdir .. "d" )
-	writefile( srcdir .. "erf", "erf" )
-	writefile( srcdir .. "eaf", "erf" )
-	writefile( srcdir .. "erd", "erd" )
-	writefile( srcdir .. "ead", "ead" )
-	writefile( srcdir .. "d/erf", "erf" )
-	writefile( srcdir .. "d/eaf", "erf" )
-	writefile( srcdir .. "d/erd", "erd" )
-	writefile( srcdir .. "d/ead", "ead" )
+	posix.mkdir( srcdir .. 'd' )
+	writefile( srcdir .. 'erf', 'erf' )
+	writefile( srcdir .. 'eaf', 'erf' )
+	writefile( srcdir .. 'erd', 'erd' )
+	writefile( srcdir .. 'ead', 'ead' )
+	writefile( srcdir .. 'd/erf', 'erf' )
+	writefile( srcdir .. 'd/eaf', 'erf' )
+	writefile( srcdir .. 'd/erd', 'erd' )
+	writefile( srcdir .. 'd/ead', 'ead' )
 end
 
 --
@@ -73,14 +72,14 @@ end
 -- test all files
 local function testfiles
 ( )
-	testfile( trgdir .. "erf", false )
-	testfile( trgdir .. "eaf", false )
-	testfile( trgdir .. "erd", true )
-	testfile( trgdir .. "ead", true )
-	testfile( trgdir .. "d/erf", false )
-	testfile( trgdir .. "d/eaf", true )
-	testfile( trgdir .. "d/erd", true ) 
-	testfile( trgdir .. "d/ead", true )
+	testfile( trgdir .. 'erf', false )
+	testfile( trgdir .. 'eaf', false )
+	testfile( trgdir .. 'erd', true )
+	testfile( trgdir .. 'ead', true )
+	testfile( trgdir .. 'd/erf', false )
+	testfile( trgdir .. 'd/eaf', true )
+	testfile( trgdir .. 'd/erd', true )
+	testfile( trgdir .. 'd/ead', true )
 end
 
 
@@ -116,7 +115,7 @@ cwriteln( 'waiting for Lsyncd to remove destination' )
 
 posix.sleep( 5 )
 
-_, result, code = os.execute( 'diff -urN ' .. srcdir .. ' ' .. trgdir )
+local result, code = execute( 'diff -urN ' .. srcdir .. ' ' .. trgdir )
 
 if result ~= 'exit' or code ~= 0
 then
@@ -138,14 +137,13 @@ testfiles( )
 cwriteln( 'killing started Lsyncd' )
 
 posix.kill( pid )
-local _, exitmsg, exitcode = posix.wait( lpid )
+local _, exitmsg, exitcode = posix.wait( pid )
 
 cwriteln( 'Exitcode of Lsyncd = ', exitmsg, ' ', exitcode );
 
 if exitcode == 143
 then
-	cwriteln( "OK" )
-
+	cwriteln( 'OK' )
 	os.exit( 0 )
 else
 	os.exit( 1 )

tests/exclude-rsyncssh.lua

@@ -1,5 +1,3 @@
-#!/usr/bin/lua
-
 require( 'posix' )
 dofile( 'tests/testlib.lua' )
 
@@ -26,6 +24,14 @@ sync {
 	default.rsyncssh,
 	delay = 3,
 	host = 'localhost',
+	ssh = {
+       port= 2468,
+	   identityFile = "]] .. script_path() .. [[/ssh/id_rsa",
+	   options = {
+		StrictHostKeyChecking="no",
+		UserKnownHostsFile="/dev/null",
+	   },
+	},
 	source = ']]..srcdir..[[',
 	targetdir = ']]..trgdir..[[',
 	exclude = {
@@ -88,7 +94,7 @@ end
 cwriteln( 'testing startup excludes' )
 writefiles( )
 cwriteln( 'starting Lsyncd' )
-local pid = spawn( './lsyncd', cfgfile, unpack( log ) )
+local pid = spawn( './lsyncd', cfgfile, table.unpack( log ) )
 cwriteln( 'waiting for Lsyncd to start' )
 posix.sleep( 10 )
 cwriteln( 'testing excludes after startup' )
@@ -107,7 +113,7 @@ os.execute( 'rm -rf ' .. srcdir .. '/*' )
 cwriteln( 'waiting for Lsyncd to remove destination' )
 posix.sleep( 5 )
 
-_, result, code = os.execute( 'diff -urN '..srcdir..' '..trgdir )
+local result, code = execute( 'diff -urN '..srcdir..' '..trgdir )
 
 if result ~= 'exit' or code ~= 0
 then
@@ -123,7 +129,7 @@ testfiles( )
 
 cwriteln( 'killing started Lsyncd' )
 posix.kill( pid )
-local _, exitmsg, lexitcode = posix.wait( lpid )
+local _, exitmsg, lexitcode = posix.wait( pid )
 cwriteln( 'Exitcode of Lsyncd = ', exitmsg, ' ', lexitcode )
 posix.sleep( 1 )
 

tests/filter-rsync.lua

@@ -0,0 +1,146 @@
+require( 'posix' )
+dofile( 'tests/testlib.lua' )
+
+cwriteln( '****************************************************************' )
+cwriteln( ' Testing filters (rsync)' )
+cwriteln( '****************************************************************' )
+
+local tdir, srcdir, trgdir = mktemps( )
+local logfile = tdir .. "log"
+local cfgfile = tdir .. "config.lua"
+local range = 5
+local log = {"-log", "all"}
+
+writefile(cfgfile, [[
+settings {
+	logfile = ']]..logfile..[[',
+	nodaemon = true,
+}
+
+sync {
+	default.rsync,
+	source = ']]..srcdir..[[',
+	target = ']]..trgdir..[[',
+	delay = 3,
+	filter = {
+		'- /ab**',
+		'+ /a**',
+		'- /**',
+	},
+}]])
+
+-- writes all files
+local function writefiles
+( )
+	writefile( srcdir .. 'abc', 'abc' )
+	writefile( srcdir .. 'acc', 'acc' )
+	writefile( srcdir .. 'baa', 'baa' )
+	posix.mkdir( srcdir .. 'abx' )
+	writefile( srcdir .. 'abx/a', 'abxa' )
+	posix.mkdir( srcdir .. 'acx' )
+	writefile( srcdir .. 'acx/x', 'acxx' )
+end
+
+--
+-- Tests if the filename exists
+-- fails if this is different to expect.
+--
+local function testfile
+(
+	filename,
+	expect
+)
+	local stat, err = posix.stat( filename )
+
+	if stat and not expect
+	then
+		cwriteln( 'failure: ', filename, ' should be filtered')
+
+		os.exit( 1 )
+	end
+
+	if not stat and expect
+	then
+		cwriteln( 'failure: ', filename, ' should not be filtered' )
+		os.exit( 1 )
+	end
+end
+
+-- test all files
+local function testfiles
+( )
+	testfile( trgdir .. 'abc', false )
+	testfile( trgdir .. 'acc', true )
+	testfile( trgdir .. 'baa', false )
+	testfile( trgdir .. 'abx/a', false )
+	testfile( trgdir .. 'acx/x', true )
+end
+
+
+cwriteln( 'testing startup filters' )
+
+writefiles( )
+
+cwriteln( 'starting Lsyncd' )
+
+local pid = spawn( './lsyncd', cfgfile, '-log', 'all' )
+
+cwriteln( 'waiting for Lsyncd to start' )
+
+posix.sleep( 3 )
+
+cwriteln( 'testing filters after startup' )
+
+testfiles( )
+
+cwriteln( 'ok, removing sources' )
+
+if srcdir:sub( 1,4 ) ~= '/tmp'
+then
+	-- just to make sure before rm -rf
+	cwriteln( 'exit before drama, srcdir is "', srcdir, '"' )
+
+	os.exit( 1 )
+end
+
+os.execute( 'rm -rf '..srcdir..'/*' )
+
+cwriteln( 'waiting for Lsyncd to remove destination' )
+
+posix.sleep( 5 )
+
+local result, code = execute( 'diff -urN ' .. srcdir .. ' ' .. trgdir )
+
+if result ~= 'exit' or code ~= 0
+then
+	cwriteln( 'fail, target directory not empty!' )
+
+	os.exit( 1 )
+end
+
+cwriteln( 'writing files after startup' )
+
+writefiles( )
+
+cwriteln( 'waiting for Lsyncd to transmit changes' )
+
+posix.sleep( 5 )
+
+testfiles( )
+
+cwriteln( 'killing started Lsyncd' )
+
+posix.kill( pid )
+local _, exitmsg, exitcode = posix.wait( pid )
+
+cwriteln( 'Exitcode of Lsyncd = ', exitmsg, ' ', exitcode );
+
+if exitcode == 143
+then
+	cwriteln( 'OK' )
+	os.exit( 0 )
+else
+	os.exit( 1 )
+end
+
+-- TODO remove temp

tests/l4rsyncdata.lua

@@ -1,4 +1,3 @@
-#!/usr/bin/lua
 require( 'posix' )
 dofile( 'tests/testlib.lua' )
 
@@ -20,7 +19,7 @@ then
 end
 cwriteln( 'starting Lsyncd' )
 
-logs = { }
+local logs = { }
 local pid =
 	spawn(
 		'./lsyncd',
@@ -28,7 +27,7 @@ local pid =
 		'-nodaemon',
 		'-delay', '5',
 		"-rsync", srcdir, trgdir,
-		unpack( logs )
+		table.unpack( logs )
 	)
 
 cwriteln( 'waiting for lsyncd to start' )
@@ -56,12 +55,12 @@ posix.sleep( 10 )
 cwriteln( '* killing Lsyncd' )
 
 posix.kill( pid )
-local _, exitmsg, lexitcode = posix.wait(lpid)
+local _, exitmsg, lexitcode = posix.wait(pid)
 cwriteln( 'Exitcode of Lsyncd = ', exitmsg, ' ', lexitcode)
 posix.sleep( 1 )
 
 cwriteln( '* differences:' )
-_, result, code = os.execute( 'diff -urN ' .. srcdir .. ' ' .. trgdir )
+local result, code = execute( 'diff -urN ' .. srcdir .. ' ' .. trgdir )
 
 if result == 'exit'
 then

tests/schedule.lua

@@ -1,10 +1,9 @@
-#!/usr/bin/lua
-require("posix")
-dofile("tests/testlib.lua")
+require( 'posix' )
+dofile( 'tests/testlib.lua' )
 
-cwriteln("****************************************************************")
-cwriteln(" Testing Lsyncd scheduler                                       ")
-cwriteln("****************************************************************")
+cwriteln( '****************************************************************' )
+cwriteln( ' Testing Lsyncd scheduler                                       ' )
+cwriteln( '****************************************************************' )
 
 local tdir, srcdir, trgdir = mktemps()
 local logfile = tdir .. "log"
@@ -47,30 +46,36 @@ sync {ccircuit, source ="]]..srcdir..[[", target = "]]..trgdir..[["}
 
 
 -- test if the filename exists, fails if this is different to expect
-local function testfile(filename)
+local function testfile
+(
+	filename
+)
 	local stat, err = posix.stat(filename)
-	if not stat then
-		cwriteln("failure: ",filename," missing")
-		os.exit(1)
+	
+	if not stat
+	then
+		cwriteln( 'failure: ', filename, ' missing' )
+		os.exit( 1 )
 	end
 end
 
-cwriteln("starting Lsyncd")
-local pid = spawn("./lsyncd", cfgfile, unpack(logs))
-cwriteln("waiting for Lsyncd to do a few cycles")
-posix.sleep(30)
-cwriteln("look if every circle got a chance to run")
-testfile(srcdir.."a")
-testfile(srcdir.."b")
-testfile(srcdir.."c")
-cwriteln("killing started Lsyncd")
-posix.kill(pid)
-local _, exitmsg, lexitcode = posix.wait(lpid)
-cwriteln("Exitcode of Lsyncd = ", exitmsg, " ", lexitcode)
+cwriteln( 'starting Lsyncd' )
+local pid = spawn( './lsyncd', cfgfile, table.unpack( logs ) )
+cwriteln( 'waiting for Lsyncd to do a few cycles' )
+posix.sleep( 30 )
+cwriteln( 'look if every circle got a chance to run' )
+testfile( srcdir..'a' )
+testfile( srcdir..'b' )
+testfile( srcdir..'c' )
+cwriteln( 'killing started Lsyncd' )
+posix.kill( pid )
+local _, exitmsg, lexitcode = posix.wait( pid )
+cwriteln( 'Exitcode of Lsyncd = ', exitmsg, ' ', lexitcode)
 posix.sleep(1);
 
-if lexitcode == 143 then
-	cwriteln("OK")
+if lexitcode == 143
+then
+	cwriteln( 'OK' )
 	os.exit( 0 )
 else
 	os.exit( 1 )

tests/setup.lua

@@ -0,0 +1,9 @@
+-- a heavy duty test.
+-- makes thousends of random changes to the source tree
+
+require( 'posix' )
+
+dofile( 'tests/testlib.lua' )
+cwriteln( ' Start Testsuite '               )
+
+startSshd()

tests/teardown.lua

@@ -0,0 +1,8 @@
+-- a heavy duty test.
+-- makes thousends of random changes to the source tree
+
+require( 'posix' )
+
+dofile( 'tests/testlib.lua' )
+
+stopSshd()

tests/test_actions.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+
+if [ -z $1 ]; then
+    echo "usage: test_actions [directory]"
+    exit 1
+fi
+
+set -x
+
+BLOBB1=$(realpath /tmp/src/../blobb1)
+
+if [ ! -e $BLOBB1 ]; then
+    echo "create outside blobb $BLOBB1"
+    dd count=50 bs=1M if=/dev/urandom of=$BLOBB1
+    echo done
+fi
+
+while true; do
+    mkdir -p $1/testdir
+    sleep 3
+    touch $1/testfile
+    sleep 2
+    echo "blubb" >> $1/testfile
+    sleep 2
+    mv $1/testfile $1/testdir
+    sleep 2
+    ln $BLOBB1 $1/blubb1
+    ln $BLOBB1 $1/testdir/blubb2
+    ln $BLOBB1 $1/blubb3
+    sleep 30
+    rm $1/testdir/testfile
+    sleep 2
+    rm -rf $1/testdir
+    sleep 1
+    rm $1/blubb1
+    rm $1/blubb3
+    sleep 5
+done

tests/testlib.lua

@@ -1,11 +1,22 @@
+--- @diagnostic disable: lowercase-global, need-check-nil
+
 -- common testing environment
 posix = require( 'posix' )
+string = require( 'string' )
+
+local sys_stat = require "posix.sys.stat"
 
 -- escape codes to colorize output on terminal
 local c1='\027[47;34m'
 
 local c0='\027[0m'
 
+-- compatibility with 5.1
+if table.unpack == nil then
+	--- @diagnostic disable-next-line: deprecated
+	table.unpack = unpack
+end
+
 --
 -- Writes colorized.
 --
@@ -15,14 +26,30 @@ function cwriteln
 	io.write( c0, '\n' )
 end
 
+local lver = string.gmatch(_VERSION, "Lua (%d).(%d)")
+_LUA_VERSION_MAJOR, _LUA_VERSION_MINOR = lver()
+_LUA_VERSION_MAJOR   = tonumber(_LUA_VERSION_MAJOR)
+_LUA_VERSION_MINOR  = tonumber(_LUA_VERSION_MINOR)
+
+-- Compatibility execute function
+function execute(...)
+	if _LUA_VERSION_MAJOR <= 5 and
+	   _LUA_VERSION_MINOR < 2 then
+		local rv = os.execute(...)
+		return "exit", rv
+	else
+		local ok, why, code = os.execute(...)
+		return why, code
+	end
+end
+
 --
 -- Initializes the pseudo random generator
 --
 -- If environment variable 'SEED' is set,
 -- that one is used seed.
 --
-local seed = os.getenv( 'SEED')  or os.time( )
-
+local seed = tonumber(os.getenv( 'SEED'))  or os.time( )
 math.randomseed( seed )
 
 cwriteln( 'random seed: ', seed )
@@ -36,6 +63,10 @@ function mktempd
 ( )
 	local f = io.popen( 'mktemp -td ltest.XXX', 'r' )
 
+	if f == nil then
+		return error("can't create testing directory")
+	end
+
 	local s = f:read( '*a' )
 
 	f:close( )
@@ -58,17 +89,11 @@ end
 function mktemps
 ( )
 	local tdir = mktempd() .. '/'
-
 	cwriteln( 'using ', tdir, ' as test root' )
-
 	local srcdir = tdir..'src/'
-
 	local trgdir = tdir..'trg/'
-
 	posix.mkdir( srcdir )
-
 	posix.mkdir( trgdir )
-
 	return tdir, srcdir, trgdir
 end
 
@@ -79,7 +104,8 @@ end
 function writefile
 (
 	filename,
-	text
+	text,
+	mode
 )
 	local f = io.open( filename, 'w' )
 
@@ -90,21 +116,135 @@ function writefile
 	end
 
 	f:write( text )
-
 	f:write( '\n' )
-
 	f:close( )
 
+	if mode ~= nil then
+		posix.chmod(filename, mode)
+	end
+
 	return true
 end
 
+function splitpath(P)
+    local i = #P
+    local ch = P:sub(i,i)
+    while i > 0 and ch ~= "/" do
+        i = i - 1
+        ch = P:sub(i,i)
+    end
+    if i == 0 then
+        return '',P
+    else
+        return P:sub(1,i-1), P:sub(i+1)
+    end
+end
+
+function isabs(p)
+	return string.sub(p, 1, 2) == "/"
+end
+
+function abspath(P,pwd)
+	P = P:gsub('[\\/]$','')
+	if not isabs(P) then
+		local rv = posix.unistd.getcwd() .. "/" .. P
+		return rv
+	end
+	return P
+end
+
+
+function script_path()
+	-- local str = debug.getinfo(2, "S").source:sub(2)
+	-- return str:match("(.*/)")
+	local dir, file = splitpath(abspath(debug.getinfo(1).short_src))
+	return dir
+end
+
+function which(exec)
+	local path = os.getenv("PATH")
+	for match in (path..':'):gmatch("(.-)"..':') do
+		local fname = match..'/'..exec
+        local s = sys_stat.stat(fname)
+		if s ~= nil then
+			return fname
+		end
+    end
+end
+
+--
+-- Starts test ssh server
+--
+function startSshd()
+	-- local f = io.open(script_path() .. "ssh/sshd.pid", 'r')
+
+	-- if f
+	-- then
+	-- 	return false
+	-- end
+
+	cwriteln(arg[0])
+	cwriteln(script_path() ..  "ssh/sshd_config")
+
+	local sshdPath = script_path() .. "/ssh/"
+
+	if posix.stat( sshdPath ) == nil then
+		cwriteln("setup ssh server in " .. sshdPath)
+		posix.mkdir(sshdPath)
+		os.execute("ssh-keygen -t rsa -N '' -f" .. sshdPath .. "id_rsa")
+		os.execute("cp ".. sshdPath .. "id_rsa.pub ".. sshdPath .. "authorized_keys")
+		os.execute("ssh-keygen -t rsa -N '' -f ".. sshdPath .. "ssh_host_rsa_key")
+		cwriteln("done")
+	end
+
+	local f = io.open( sshdPath ..  "sshd_config", 'w')
+	local cfg = [[
+		Port 2468
+		HostKey ]] .. sshdPath .. [[ssh_host_rsa_key
+		AuthorizedKeysFile ]] .. sshdPath .. [[authorized_keys
+		ChallengeResponseAuthentication no
+		UsePAM no
+		#Subsystem   sftp    /usr/lib/ssh/sftp-server
+		PidFile ]] .. sshdPath .. [[sshd.pid
+	]]
+	cwriteln("Use ssh config: "..cfg)
+	f:write(cfg)
+	f:close()
+	--local which = io.popen("which sshd")
+	exePath = which('sshd')
+	cwriteln("Using sshd: "..exePath)
+
+	local pid = spawn(exePath, "-D", "-e", "-f", sshdPath .. "sshd_config")
+	cwriteln( 'spawned sshd server: ' .. pid)
+
+	return true
+end
+
+
+function strip(s)
+	return s:match "^%s*(.-)%s*$"
+end
+
+--
+-- Stop test ssh server
+--
+function stopSshd()
+	local f = io.open(script_path() .. "/ssh/sshd.pid", 'r')
+
+	if not f
+	then
+		return false
+	end
+	pid = strip(f:read("*a"))
+	posix.kill(tonumber(pid))
+end
+
 --
 -- Spawns a subprocess.
 --
 -- Returns the processes pid.
 --
-function spawn
-(...)
+function spawn(...)
 	args = { ... }
 
 	cwriteln( 'spawning: ', table.concat( args, ' ' ) )
@@ -143,11 +283,8 @@ function churn
 )
 	-- all dirs created, indexed by integer and path
 	root = { name = '' }
-
 	alldirs = { root }
-
 	dirsWithFileI = { }
-
 	dirsWithFileD = { }
 
 	--
@@ -510,4 +647,59 @@ function churn
 	end
 end
 
+-- check if tables are equal
+function isTableEqual(o1, o2, ignore_mt)
+    if o1 == o2 then return true end
+    local o1Type = type(o1)
+    local o2Type = type(o2)
+    if o1Type ~= o2Type then return false end
+    if o1Type ~= 'table' then return false end
 
+    if not ignore_mt then
+        local mt1 = getmetatable(o1)
+        if mt1 and mt1.__eq then
+            --compare using built in method
+            return o1 == o2
+        end
+    end
+
+    local keySet = {}
+
+    for key1, value1 in pairs(o1) do
+        local value2 = o2[key1]
+        if value2 == nil or isTableEqual(value1, value2, ignore_mt) == false then
+            return false
+        end
+        keySet[key1] = true
+    end
+
+    for key2, _ in pairs(o2) do
+        if not keySet[key2] then return false end
+    end
+    return true
+end
+
+--
+-- Tests if the filename exists
+-- fails if this is different to expect.
+--
+function testfile
+	(
+		filename,
+		expect
+	)
+	local stat, err = posix.stat( filename )
+
+	if stat and not expect
+	then
+		cwriteln( 'failure: ', filename, ' should be filtered')
+
+		os.exit( 1 )
+	end
+
+	if not stat and expect
+	then
+		cwriteln( 'failure: ', filename, ' should not be filtered' )
+		os.exit( 1 )
+	end
+end

tests/utils_test.lua

@@ -0,0 +1,79 @@
+dofile( 'tests/testlib.lua' )
+
+cwriteln( '****************************************************************' )
+cwriteln( ' Testing Utils Functions                                         ' )
+cwriteln( '****************************************************************' )
+
+assert(isTableEqual(
+    lsyncd.splitQuotedString("-p 22 -i '/home/test/bla blu/id_rsa'"),
+    {"-p", "22", "-i", "/home/test/bla blu/id_rsa"}
+))
+
+-- test string replacement
+local testData = {
+    localPort = 1234,
+    localHost = "localhorst"
+}
+
+assert(isTableEqual(
+    substitudeCommands({"-p^doesNotExist", "2^localHostA", "-i '^localPort'"}, testData),
+    {"-p^doesNotExist", "2localhorstA", "-i '1234'"}
+))
+
+assert(
+    substitudeCommands("-p^doesNotExist 2^localHostA -i '^localPort'", testData),
+    "-p^doesNotExist 2localhorstA -i '1234'"
+)
+
+
+assert(type(lsyncd.get_free_port()) == "number")
+
+local function testQueue()
+    local q = Queue.new()
+    q:push(1)
+    q:push(2)
+    q:push(3)
+    q:push(4)
+    assert(q:size(), 4)
+    assert(q[1], 1)
+    assert(q[4], 4)
+
+    q:remove(4)
+    assert(q:size(), 3)
+    assert(q[3], 3)
+    assert(q[1], 1)
+
+    q:remove(1)
+    assert(q:size(), 2)
+    assert(q[3], 3)
+    assert(q[2], 2)
+    assert(q.first, 2)
+    assert(q.last, 3)
+
+    q:push(5)
+    assert(q:size(), 3)
+    assert(q.last, 4)
+    assert(q.first, 2)
+    assert(q[4], 5)
+    assert(q[3], 3)
+    assert(q[2], 2)
+
+    q:remove(3)
+    assert(q:size(), 2)
+    assert(q.last, 3)
+    assert(q.first, 2)
+    assert(q[2], 2)
+    assert(q[3], 5)
+
+    q:inject(23)
+    assert(q:size(), 3)
+    assert(q.last, 3)
+    assert(q.first, 1)
+    assert(q[1], 23)
+    assert(q[2], 2)
+    assert(q[3], 5)
+end
+
+testQueue()
+
+os.exit(0)