{"id":13395261,"url":"https://github.com/deajan/osync","last_synced_at":"2025-05-14T20:09:05.785Z","repository":{"id":9007788,"uuid":"10761190","full_name":"deajan/osync","owner":"deajan","description":"A robust two way (bidirectional) file sync script based on rsync with fault tolerance, POSIX ACL support, time control and near realtime sync","archived":false,"fork":false,"pushed_at":"2025-03-08T13:14:22.000Z","size":3809,"stargazers_count":956,"open_issues_count":39,"forks_count":104,"subscribers_count":33,"default_branch":"master","last_synced_at":"2025-04-13T16:53:27.007Z","etag":null,"topics":["acl-replication","file-replication","posix-acl","replication","rsync-wrapper","sync-files","synchronization","time-control"],"latest_commit_sha":null,"homepage":"http://www.netpower.fr/osync","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/deajan.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.TXT","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2013-06-18T10:56:16.000Z","updated_at":"2025-04-11T16:59:06.000Z","dependencies_parsed_at":"2023-02-11T21:16:29.367Z","dependency_job_id":"1a85d35a-8c87-4bb4-92a2-385f34f36360","html_url":"https://github.com/deajan/osync","commit_stats":{"total_commits":1766,"total_committers":33,"mean_commits":"53.515151515151516","dds":0.0928652321630804,"last_synced_commit":"548f3c573050308b9cdd7e3746cf783c054d5a00"},"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deajan%2Fosync","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deajan%2Fosync/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deajan%2Fosync/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deajan%2Fosync/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/deajan","download_url":"https://codeload.github.com/deajan/osync/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254219373,"owners_count":22034397,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["acl-replication","file-replication","posix-acl","replication","rsync-wrapper","sync-files","synchronization","time-control"],"created_at":"2024-07-30T17:01:48.091Z","updated_at":"2025-05-14T20:09:05.759Z","avatar_url":"https://github.com/deajan.png","language":"Shell","funding_links":[],"categories":["Backup","Shell","\u003ca name=\"backup\"\u003e\u003c/a\u003ebackup","others","Sync-Tools"],"sub_categories":[],"readme":"# osync\n[![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)\n[![GitHub Release](https://img.shields.io/github/release/deajan/osync.svg?label=Latest)](https://github.com/deajan/osync/releases/latest)\n[![Percentage of issues still open](http://isitmaintained.com/badge/open/deajan/osync.svg)](http://isitmaintained.com/project/deajan/osync \"Percentage of issues still open\")\n[![Codacy Badge](https://api.codacy.com/project/badge/Grade/651acb2fd64642eb91078ba523b7f887)](https://www.codacy.com/app/ozy/osync?utm_source=github.com\u0026amp;utm_medium=referral\u0026amp;utm_content=deajan/osync\u0026amp;utm_campaign=Badge_Grade)\n[![linux tests](https://github.com/deajan/osync/actions/workflows/linux.yml/badge.svg)](https://github.com/deajan/osync/actions/workflows/linux.yml/badge.svg)\n[![windows tests](https://github.com/deajan/osync/actions/workflows/windows.yml/badge.svg)](https://github.com/deajan/osync/actions/workflows/windows.yml/badge.svg)\n[![macos tests](https://github.com/deajan/osync/actions/workflows/macos.yml/badge.svg)](https://github.com/deajan/osync/actions/workflows/macos.yml/badge.svg)\n\n\nA two way filesync script running on bash Linux, BSD, Android, MacOSX, Cygwin, MSYS2, Win10 bash and virtually any system supporting bash.\nFile synchronization is bidirectional, and can be run manually, as scheduled task, or triggered on file changes in monitor mode.\nIt is a command line tool rsync wrapper with a lot of additional features baked in.\n\nThis is a quickstart guide, you can find the full documentation on the [author's site](http://www.netpower.fr/osync).\n\n## About\n\nosync provides the following capabilities:\n\n-   Local-Local and Local-Remote sync\n-   Fault tolerance with resume scenarios\n-   POSIX ACL and extended attributes synchronization\n-   Full script Time control\n-   Soft deletions and multiple backups handling\n-   Before/after run command execution\n-   Email alerts\n-   Logging facility\n-   Directory monitoring\n-   Running on schedule or as daemon\n-   Batch runner for multiple sync tasks with rerun option for failed sync tasks\n\nosync is a stateful synchronizer. This means it's agentless and doesn't have to monitor files for changes. Instead, it compares replica file lists between two runs.\nA full run takes about 2 seconds on a local-local replication and about 7 seconds on a local-remote replication.\nDisabling some features file like attributes preservation and disk space checks may speed up execution. \nosync uses a initiator/target sync schema. It can sync local to local or local to remote directories. By definition, initiator replica is always a local directory on the system osync runs on.\nosync uses pidlocks to prevent multiple concurrent sync processes on/to the same initiator/target replica.\nYou may launch concurrent sync processes on the same system but as long as the replicas to synchronize are different.\nMultiple osync tasks may be launched sequentially by osync osync-batch tool.\n\n## Tested platforms\n\n| Operating system | Version                |\n|------------------|------------------------|\n| AlmaLinux        | 9                      |\n| Android\\*        | Not known              |\n| CentOS           | 5.x, 6.x, 7.x          |\n| Fedora           | 22-25                  |\n| FreeBSD          | 8.3-11                 |\n| Debian           | 6-11                   |\n| Linux Mint       | 14-18                  |\n| macOS            | Not known              |\n| pfSense          | 2.3.x                  |\n| QTS (x86)        | 4.5.1                  |\n| Ubuntu           | 12.04-22.04            |\n| Windows\\*\\*      | 10                     |\n\n\\* via Termux.\n\\*\\* via MSYS, Cygwin and WSL.\n\nSome users also have successfully used osync on Gentoo and created an OpenRC init script for it.\n\n## Installation\n\nosync has been designed to not delete any data, but rather make backups of conflictual files or soft deletes.\nNevertheless, you should always have a neat backup of your data before trying a new sync tool.\n\nGetting osync via GitHub (remove the -b \"stable\" if you want latest dev snapshot)\n\n\t$ git clone -b \"stable\" https://github.com/deajan/osync\n\t$ cd osync\n\t$ bash install.sh\n\nInstaller script accepts some parameters for automation. Launch install.sh --help for options.\n\nThere is also an RPM file that should fit RHEL/CentOS/Fedora and basically any RPM based distro, see the GitHub release.\nPlease note that RPM files will install osync to `/usr/bin` instead of `/usr/local/bin` in order to enforce good practices.\n\nosync will install itself to `/usr/local/bin` and an example configuration file will be installed to `/etc/osync`.\n\nosync needs to run with bash shell. Using any other shell will most probably result in errors.\nIf bash is not your default shell, you may invoke it using\n\n\t$ bash osync.sh [options]\n\nOn *BSD and BusyBox, be sure to have bash installed.\n\nIf you can't install osync, you may just copy osync.sh where you needed and run it from there.\n\nArch Linux packages are available at \u003chttps://aur.archlinux.org/packages/osync/\u003e (thanks to Shadowigor, \u003chttps://github.com/shadowigor\u003e).\n\n## Upgrade from previous configuration files\n\nSince osync v1.1 the config file format has changed in semantics and adds new config options.\nAlso, master is now called initiator and slave is now called target.\nosync v1.3 also added multiple new configuration options.\n\nYou can upgrade all v1.0x-v1.3-dev config files by running the upgrade script\n\n\t$ ./upgrade-v1.0x-v1.3x.sh /etc/osync/your-config-file.conf\n\nThe script will backup your config file, update it's content and try to connect to initiator and target replicas to update the state dir.\n\n## Usage\n\nOsync can work in 3 modes:\n1. [:rocket: Quick sync mode](#quick-sync-mode)\n2. [:gear: Configuration file mode](#configuration-file-mode)\n3. [:mag_right: Monitor mode](#monitor-mode)\n\n\u003e [!NOTE]\n\u003e Please use double quotes as path delimiters. Do not use escaped characters in path names.\n\n### \u003ca id=\"quick-sync-mode\"\u003e\u003c/a\u003e:rocket: Quick sync mode\n\nQuick sync mode is convenient to do fast syncs between some directories. However, the [configuration file mode](#configuration-file-mode) gives much more functionality.\n\n\t# osync.sh --initiator=\"/path/to/dir1\" --target=\"/path/to/remote dir2\"\n\t# 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\n\n#### Quick sync with minimal options\n\nIn 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:\n\n\t# 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\n\nAll the settings described here may also be configured in the conf file.\n\n### Summary mode\n\nosync will output only file changes and errors with the following:\n\n\t# osync.sh --initiator=\"/path/to/dir1\" --target=\"/path/to/dir\" --summary --errors-only --no-prefix\n\nThis also works in configuration file mode.\n\n### \u003ca id=\"configuration-file-mode\"\u003e\u003c/a\u003e:gear: Configuration file mode\n\nYou'll have to customize the `sync.conf` file according to your needs.\n\nIf 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.\n\n\u003e [!TIP]\n\u003e Read the [example configuration file](https://github.com/deajan/osync/blob/master/sync.conf.example) for documentation about remote sync setups.\n\nOnce you've customized a `sync.conf` file, you may run osync with the following test run:\n\n\t# osync.sh /path/to/your.conf --dry\n\nIf everything went well, you may run the actual configuration with:\n\n\t# osync.sh /path/to/your.conf\n\nTo 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):\n \n\t# osync.sh /path/to/your.conf --verbose\n\nUse `--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:\n \n \t# osync.sh /path/to/your.conf --no-maxtime\n\nOnce 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:\n\n\t*/30 * * * * root /usr/local/bin/osync.sh /etc/osync/my_sync.conf --silent\n\nPlease note that this syntax works for RedHat/CentOS. On Debian you might want to remove the username (i.e. root) in order to make the crontab entry work.\n\n### Batch mode\n\nYou 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,\nrun it again if there's still some time left.\n\nTo 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:\n\n\t# osync-batch.sh --path=/etc/osync --max-retries=3 --max-exec-time=7200\n\nHaving multiple conf files can then be run in a single cron command like\n\n\t00 00 * * * root /usr/local/bin/osync-batch.sh --path=/etc/osync --silent\n\n### \u003ca id=\"monitor-mode\"\u003e\u003c/a\u003e:mag_right: Monitor mode\n\n\u003e [!NOTE]\n\u003e 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.\n\nMonitor 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.\n\nThis mode can also be launched as a daemon with an init script. Please read the documentation for more info.\n\nTo use this mode, use `--on-changes`:\n\n\t# osync.sh /etc/osync/my_sync.conf --on-changes\n\nTo 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:\n- `osync.sh` to `/usr/bin/local`\n- `sync.conf` to `/etc/osync`\n- For InitV, `osync-srv` to `/etc/init.d`\n- For systemd, `osync-srv@.service` to `/usr/lib/systemd/system`\n- For OpenRC, `osync-srv-openrc` to `/etc/init.d/osync-srv-openrc`\n\nFor InitV (any configuration file found in `/etc/osync` will create an osync daemon instance when service is launched on initV):\n\n\t$ service osync-srv start\n\t$ chkconfig osync-srv on\n\nFor systemd, launch service (one service per config file to launch) with:\n\n\t$ systemctl start osync-srv@configfile.conf\n\t$ systemctl enable osync-srv@configfile.conf\n\nFor OpenRC (user contrib), launch service (one service per config file to launch) with:\n\n\t$ rc-update add osync-srv.configfile default\n\n## Security enhancements\n\nRemote SSH connection security can be improved by limiting what hostnames may connect, disabling some SSH options and using ssh filter.\nPlease read full documentation in order to configure ssh filter.\n\n## Contributions\n\nAll kind of contribs are welcome.\n\nWhen submitting a PR, please be sure to modify files in dev directory (`dev/n_osync.sh`, `dev/ofunctions.sh`, `dev/common_install.sh etc`) as most of the main files are generated via merge.sh.\nWhen testing your contribs, generate files via merge.sh or use bootstrap.sh which generates a temporary version of n_osync.sh with all includes.\n\nUnit tests are run by travis on every PR, but you may also run them manually which adds some tests that travis can't do, via `dev/tests/run_tests.sh`.\nSSH port can be changed on the fly via environment variable SSH_PORT, e.g.:\n\n\t# SSH_PORT=2222 dev/tests/run_tests.sh\n\nConsider reading CODING_CONVENTIONS.TXT before submitting a patch.\n\n## Troubleshooting\n\nYou may find osync's logs in `/var/log/osync.[INSTANCE_ID].log` (or current directory if `/var/log` is not writable).\nAdditionnaly, you can use the --verbose flag see to what actions are going on.\n\nWhen opening an issue, please post the corresponding log files. Also, you may run osync with _DEBUG option in order to have more precise logs, e.g.:\n\n\t# _DEBUG=yes ./osync.sh /path/to/conf\n\n## Uninstalling\n\nThe installer script also has an uninstall mode that will keep configuration files. Use it with\n\n\t$ ./install.sh --remove\n\n## Author\n\nFeel free to open an issue on GitHub or mail me for support in my spare time :)\nOrsiris de Jong | ozy@netpower.fr\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeajan%2Fosync","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdeajan%2Fosync","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeajan%2Fosync/lists"}