From 2ce2561f99f314ee15d7bfeed84e84a4302f95bb Mon Sep 17 00:00:00 2001 From: Vitor Henrique <87824454+vitorhcl@users.noreply.github.com> Date: Wed, 13 Mar 2024 10:55:48 -0300 Subject: [PATCH 1/5] Improve Usage section --- README.md | 58 +++++++++++++++++++++++++++++++++---------------------- 1 file changed, 35 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index fa458eb..7a905e6 100644 --- a/README.md +++ b/README.md @@ -86,15 +86,29 @@ The script will backup your config file, update it's content and try to connect ## Usage -Osync can work with in three flavors: Quick sync mode, configuration file mode, and monitor mode. -While quick sync mode is convenient to do fast syncs between some directories, a configuration file gives much more functionality. -Please use double quotes as path delimiters. Do not use escaped characters in path names. +Osync can work in 3 modes: +1. [:rocket: Quick sync mode](#quick-sync-mode) +2. [:gear: Configuration file mode](#configuration-file-mode) +3. [:mag_right: Monitor mode](#monitor-mode) -### QuickSync example +> [!NOTE] +> Please use double quotes as path delimiters. Do not use escaped characters in path names. + +### :rocket: Quick sync mode + +Quick sync mode is convenient to do fast syncs between some directories. However, the [configuration file mode](#configuration-file-mode) gives much more functionality. # osync.sh --initiator="/path/to/dir1" --target="/path/to/remote dir2" # osync.sh --initiator="/path/to/another dir" --target="ssh://user@host.com:22//path/to/dir2" --rsakey=/home/user/.ssh/id_rsa_private_key_example.com +#### Quick sync with minimal options + +In order to run osync the quickest (without transferring file attributes, without softdeletion, without prior space checks and without remote connectivity checks, you may use the following: + + # MINIMUM_SPACE=0 PRESERVE_ACL=no PRESERVE_XATTR=no SOFT_DELETE_DAYS=0 CONFLICT_BACKUP_DAYS=0 REMOTE_HOST_PING=no osync.sh --initiator="/path/to/another dir" --target="ssh://user@host.com:22//path/to/dir2" --rsakey=/home/user/.ssh/id_rsa_private_key_example.com + +All the settings described here may also be configured in the conf file. + ### Summary mode osync will output only file changes and errors with the following: @@ -103,33 +117,30 @@ osync will output only file changes and errors with the following: This also works in configuration file mode. -### QuickSync with minimal options +### :gear: Configuration file mode -In order to run osync the quickest (without transferring file attributes, without softdeletion, without prior space checks and without remote connectivity checks, you may use the following: +You'll have to customize the `sync.conf` file according to your needs. - # MINIMUM_SPACE=0 PRESERVE_ACL=no PRESERVE_XATTR=no SOFT_DELETE_DAYS=0 CONFLICT_BACKUP_DAYS=0 REMOTE_HOST_PING=no osync.sh --initiator="/path/to/another dir" --target="ssh://user@host.com:22//path/to/dir2" --rsakey=/home/user/.ssh/id_rsa_private_key_example.com +If you intend to sync a remote directory, osync will need a pair of private/public RSA keys to perform remote SSH connections. Also, running sync as superuser requires to configure the `/etc/sudoers` file. -All the settings described here may also be configured in the conf file. +> [!TIP] +> Read the [example configuration file](https://github.com/deajan/osync/blob/master/sync.conf.example) for documentation about remote sync setups. -### Running osync with a configuration file - -You'll have to customize the `sync.conf` file according to your needs. -If you intend to sync a remote directory, osync will need a pair of private/public RSA keys to perform remote SSH connections. -Also, running sync as superuser requires to configure the `/etc/sudoers` file. -Please read the documentation about remote sync setups. -Once you've customized a sync.conf file, you may run osync with the following test run: +Once you've customized a `sync.conf` file, you may run osync with the following test run: # osync.sh /path/to/your.conf --dry -If everything went well, you may run the actual configuration with one of the following: +If everything went well, you may run the actual configuration with: # osync.sh /path/to/your.conf + +To display which files and attrs are actually synchronized and which files are to be soft deleted / are in conflict, use `--verbose` (you may mix it with `--silent` to output verbose input only in the log files): + # osync.sh /path/to/your.conf --verbose - # osync.sh /path/to/your.conf --no-maxtime -Verbose option will display which files and attrs are actually synchronized and which files are to be soft deleted / are in conflict. -You may mix "--silent" and "--verbose" parameters to output verbose input only in the log files. -No-Maxtime option will disable execution time checks, which is usefull for big initial sync tasks that might take long time. Next runs should then only propagate changes and take much less time. +Use `--no-maxtime` to disable execution time checks, which is usefull for big initial sync tasks that might take long time. Next runs should then only propagate changes and take much less time: + + # osync.sh /path/to/your.conf --no-maxtime Once you're confident about your first runs, you may add osync as a cron task like the following in `/etc/crontab` which would run osync every 30 minutes: @@ -139,9 +150,10 @@ Please note that this syntax works for RedHat/CentOS. On Debian you might want t ### Batch mode -You may want to sequentially run multiple sync sets between the same servers. In that case, osync-batch.sh is a nice tool that will run every osync conf file, and, if a task fails, +You may want to sequentially run multiple sync sets between the same servers. In that case, `osync-batch.sh` is a nice tool that will run every osync conf file, and, if a task fails, run it again if there's still some time left. -The following example will run all .conf files found in `/etc/osync`, and retry 3 times every configuration that fails, if the whole sequential run took less than 2 hours. + +To run all `.conf` files found in `/etc/osync`, and retry 3 times every configuration that fails if the whole sequential run took less than 2 hours, use: # osync-batch.sh --path=/etc/osync --max-retries=3 --max-exec-time=7200 @@ -149,7 +161,7 @@ Having multiple conf files can then be run in a single cron command like 00 00 * * * root /usr/local/bin/osync-batch.sh --path=/etc/osync --silent -### Monitor mode +### :mag_right: Monitor mode > [!NOTE] > Monitoring changes requires inotifywait command (inotify-tools package for most Linux distributions) BSD, macOS and Windows are not yet supported for this operation mode, unless you find an inotify-tools package on these OSes. From 51e79cb56a219c072a8783d9dc3752816b21cd26 Mon Sep 17 00:00:00 2001 From: Vitor Henrique <87824454+vitorhcl@users.noreply.github.com> Date: Wed, 13 Mar 2024 11:00:26 -0300 Subject: [PATCH 2/5] Fix modes links --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 7a905e6..cecff1f 100644 --- a/README.md +++ b/README.md @@ -94,7 +94,7 @@ Osync can work in 3 modes: > [!NOTE] > Please use double quotes as path delimiters. Do not use escaped characters in path names. -### :rocket: Quick sync mode +### :rocket: Quick sync mode Quick sync mode is convenient to do fast syncs between some directories. However, the [configuration file mode](#configuration-file-mode) gives much more functionality. @@ -117,7 +117,7 @@ osync will output only file changes and errors with the following: This also works in configuration file mode. -### :gear: Configuration file mode +### :gear: Configuration file mode You'll have to customize the `sync.conf` file according to your needs. @@ -161,7 +161,7 @@ Having multiple conf files can then be run in a single cron command like 00 00 * * * root /usr/local/bin/osync-batch.sh --path=/etc/osync --silent -### :mag_right: Monitor mode +### :mag_right: Monitor mode > [!NOTE] > Monitoring changes requires inotifywait command (inotify-tools package for most Linux distributions) BSD, macOS and Windows are not yet supported for this operation mode, unless you find an inotify-tools package on these OSes. From 7aeb2e3b69c28b770075eb4fac6f035e709aff70 Mon Sep 17 00:00:00 2001 From: Vitor Henrique Date: Wed, 13 Mar 2024 11:26:58 -0300 Subject: [PATCH 3/5] Improve Monitor mode section --- README.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index cecff1f..7042268 100644 --- a/README.md +++ b/README.md @@ -166,15 +166,20 @@ Having multiple conf files can then be run in a single cron command like > [!NOTE] > Monitoring changes requires inotifywait command (inotify-tools package for most Linux distributions) BSD, macOS and Windows are not yet supported for this operation mode, unless you find an inotify-tools package on these OSes. -Additionaly, you may run osync in monitor mode, which means it will perform a sync upon file operations on initiator replica. -This can be a drawback on functionality versus scheduled mode because this mode only launches a sync task if there are file modifications on the initiator replica, without being able to monitor the target replica. -Target replica changes are only synced when initiator replica changes occur, or when a given amount of time (default 600 seconds) passed without any changes on initiator replica. +Monitor mode will perform a sync upon file operations on initiator replica. This can be a drawback on functionality versus scheduled mode because this mode only launches a sync task if there are file modifications on the initiator replica, without being able to monitor the target replica. Target replica changes are only synced when initiator replica changes occur, or when a given amount of time (600 seconds by default) passed without any changes on initiator replica. + File monitor mode can also be launched as a daemon with an init script. Please read the documentation for more info. +To use this mode, use `--on-changes`: + # osync.sh /etc/osync/my_sync.conf --on-changes -Osync file monitor mode may be run as system service with the osync-srv script. -You may run the install.sh script which should work in most cases or copy the files by hand (osync.sh to `/usr/bin/local`, sync.conf to `/etc/osync`, osync-srv to `/etc/init.d` for initV, osync-srv@.service to `/usr/lib/systemd/system` for systemd, osync-srv-openrc to `/etc/init.d/osync-srv-openrc` for OpenRC). +Osync file monitor mode may be run as system service with the osync-srv script. You may run the install.sh script which should work in most cases or copy the files by hand: +- `osync.sh` to `/usr/bin/local` +- `sync.conf` to `/etc/osync` +- For InitV, `osync-srv` to `/etc/init.d` +- For systemd, `osync-srv@.service` to `/usr/lib/systemd/system` +- For OpenRC, `osync-srv-openrc` to `/etc/init.d/osync-srv-openrc` For InitV (any configuration file found in `/etc/osync` will create an osync daemon instance when service is launched on initV): From e34ebfd4cd6f12765a801360208d284b1d540741 Mon Sep 17 00:00:00 2001 From: Vitor Henrique <87824454+vitorhcl@users.noreply.github.com> Date: Wed, 13 Mar 2024 12:27:27 -0300 Subject: [PATCH 4/5] Improve wording of "Monitor mode" section --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 7042268..41423ce 100644 --- a/README.md +++ b/README.md @@ -168,13 +168,13 @@ Having multiple conf files can then be run in a single cron command like Monitor mode will perform a sync upon file operations on initiator replica. This can be a drawback on functionality versus scheduled mode because this mode only launches a sync task if there are file modifications on the initiator replica, without being able to monitor the target replica. Target replica changes are only synced when initiator replica changes occur, or when a given amount of time (600 seconds by default) passed without any changes on initiator replica. -File monitor mode can also be launched as a daemon with an init script. Please read the documentation for more info. +This mode can also be launched as a daemon with an init script. Please read the documentation for more info. To use this mode, use `--on-changes`: # osync.sh /etc/osync/my_sync.conf --on-changes -Osync file monitor mode may be run as system service with the osync-srv script. You may run the install.sh script which should work in most cases or copy the files by hand: +To run this mode as system service with the `osync-srv` script, you can run the `install.sh` script (which should work in most cases) or copy the files by hand: - `osync.sh` to `/usr/bin/local` - `sync.conf` to `/etc/osync` - For InitV, `osync-srv` to `/etc/init.d` From 99d01b2ed0b380d603fb04fc08420d8d831fb156 Mon Sep 17 00:00:00 2001 From: Vitor Henrique <87824454+vitorhcl@users.noreply.github.com> Date: Wed, 13 Mar 2024 12:33:20 -0300 Subject: [PATCH 5/5] Improve monitor mode section --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 41423ce..32cb297 100644 --- a/README.md +++ b/README.md @@ -164,7 +164,7 @@ Having multiple conf files can then be run in a single cron command like ### :mag_right: Monitor mode > [!NOTE] -> Monitoring changes requires inotifywait command (inotify-tools package for most Linux distributions) BSD, macOS and Windows are not yet supported for this operation mode, unless you find an inotify-tools package on these OSes. +> Monitoring changes requires inotifywait command (`inotify-tools` package for most Linux distributions). BSD, macOS and Windows are not yet supported for this operation mode, unless you find an `inotify-tool` package on these OSes. Monitor mode will perform a sync upon file operations on initiator replica. This can be a drawback on functionality versus scheduled mode because this mode only launches a sync task if there are file modifications on the initiator replica, without being able to monitor the target replica. Target replica changes are only synced when initiator replica changes occur, or when a given amount of time (600 seconds by default) passed without any changes on initiator replica. @@ -174,7 +174,7 @@ To use this mode, use `--on-changes`: # osync.sh /etc/osync/my_sync.conf --on-changes -To run this mode as system service with the `osync-srv` script, you can run the `install.sh` script (which should work in most cases) or copy the files by hand: +To run this mode as a system service with the `osync-srv` script, you can run the `install.sh` script (which should work in most cases) or copy the files by hand: - `osync.sh` to `/usr/bin/local` - `sync.conf` to `/etc/osync` - For InitV, `osync-srv` to `/etc/init.d`