File synchronization with Osync and Freehold

Sync and Host

Article from Issue 188/2016

Sync files and host them on the web with a minimum of effort using Osync and Freehold.

File synchronization and hosting applications come in all shapes and sizes, but if simplicity and speed are your primary requirements, then Osync and Freehold are right up your alley. Both tools are light on resources, easy to deploy, and straightforward in use.

File Syncing from the Command Line with Osync

Rsync is probably the most popular command-line backup tool on the Linux platform. Even though mastering rsync basics doesn't require a lot of effort, things can quickly become somewhat tricky when you move beyond simple backup commands and scripts. Enter Osync [1], a Bash shell script that acts as a user-friendly wrapper for rsync and lets you make the most of rsync's functionality.

Osync has no other dependencies besides rsync, and the latter is available in the software repositories of all mainstream Linux distributions. To install rsync on Ubuntu and its derivatives, run the sudo apt-get install rsync command. Note that Osync is designed for Bash, and the script might not work with other shells like Zsh or Fish. Osync comes with an installer script that simplifies the process of deploying the tool on a Linux system. Clone the project's GitHub repository and then run the supplied installer script (the last command must be run as root):

git clone
cd osync/

The installer copies a handful of scripts, including, to the /usr/local/bin directory and creates the osync-srv script for starting Osync on boot. To check whether Osync has been installed properly, run the command, which should return the current version number and usage info (Figure 1).

Figure 1: Run the command to view brief usage info.

Unlike rsync, which supports only one-way synchronization, Osync can sync the contents of two directories in both directions. This means that all changes (i.e., modifications, additions, and deletions) in Directory A are mirrored in Directory B, and vice versa. Better still, Osync handles file deletions in a rather intelligent manner: When a file is deleted in one directory, Osync moves its copy in the other directory to the special .osync_workdir/deleted folder instead of simply deleting it. This ensures that you can always retrieve the deleted files, if needed. To purge the deleted files after a specified period of time, you can use a dedicated Osync option (more about it later).

To perform synchronization, Osync requires two parameters: --initiator (path to the source directory) and --target (path to the target directory): --initiator=/path/to/source --target=/path/to/target

Like any other command-line tool, Osync supports several useful options. The --dry option, for example, can be used to test synchronization commands before actually running them, and --verbose generates a detailed output during synchronization. The --on-change option performs synchronization automatically when the contents of the source directory are changed. And, if you set up a cron job to run Osync at a specified schedule, you should use the --silent option to suppress all output.

In addition to the command-line options, you can also specify Osync-specific parameters. For example, Osync supports the CREATE_DIRS parameter. When enabled, it instructs Osync to create the target directory if it doesn't exist. Unlike the regular options, Osync-specific parameters must be specified before the Osync command:

CREATE_DIRS=yes --initiator=/path/to/source --target=/path/to/target

Because Osync is powered by rsync, the tool supports remote synchronization via SSH. To make use of this feature, you need to specify the SSH URL as part of the target directory path: --initiator=/path/to/source --target=ssh://

Specifying options and parameters on the fly is fine for occasional synchronization, but if you plan to use Osync on a regular basis, it makes sense to create a configuration file and point Osync to it. You also can use the supplied sync.conf file as a template. At the very minimum, you need to specify the correct paths for the INITIATOR_SYNC_DIR and TARGET_SYNC_DIR options.

If the target directory is on a remote host, you also need to add the path to your private SSH key to the SSH_RSA_PRIVATE_KEY option. You can tweak several other useful options to your liking. For example, if you want to exclude certain files from being synced, you can create a file containing exclusion rules and add its path to the RSYNC_EXCLUDE_FROM option. Osync comes with an exclude.list.example example file you can use as a starting point. Keep in mind that the exclusion file must be in the same directory as the configuration file.

Osync also supports several options that control backup and deletion. Although there is probably no need to tweak them, understanding what they do can give you a better idea how Osync handles synchronization conflicts and deletions. When the CONFLICT_BACKUP option is enabled, Osync saves backup copies of files that have been modified in the source directory in the special .osync_workdir/backups folder inside the target directory.

Enabling the CONFLICT_BACKUP_MULTIPLE option effectively adds no-frills versioning capabilities to Osync; whenever you edit a file in one directory and perform synchronization, Osync creates a backup version of the file in the other directory. With this feature activated, you can quickly end up with a large number of backup files. Fortunately, Osync has the dedicated CONFLICT_BACKUP_DAYS option that purges the backup copies after a specified number of days.

Osync can also send email alerts, which can come in rather handy when you run Osync unattended. To enable this feature, configure the required options (email addresses and SMTP connection info) in the ALERT OPTIONS section of the configuration file.

Once you've configured all the options, save the configuration file under the osync.conf name in the /etc/osync directory and move the exclusion file there, too. Then, run Osync using the /etc/osync/osync.conf command.

This is all fine and dandy, but what if you need to sync multiple source and target directories? The script can help you with that. It reads all configuration files in the specified directory and performs synchronization for each profile. So, to keep multiple source/target directories sets in sync, you need to create a .conf profile for each set as described above and point the script to the directory where these configuration files are stored: --path=/etc/osync

Besides running Osync manually and via a cron job, you can configure the tool to run on boot using a systemd service. To do this, make sure that the osync.conf file is properly configured and stored in the etc/osync directory, and then run the systemctl enable osync-srv@osync.conf command as root.

Freehold: Synchronization and Hosting Combo

Written in Go, Freehold [2] has two things going for it: simplicity and speed. This application is very light on resources and runs blazingly fast even on modest hardware like Raspberry Pi. Better still, Freehold is distributed as a ready-to-go binary, so you can deploy it in a matter of minutes. Grab the appropriate tarball from the project's website, extract the archive, switch to the resulting directory, and run the ./freehold command. By default, Freehold runs on port 80, but you can easily change that by editing the port option in the ~/.config/freehold/settings.json file. Point your browser to your Freehold installation, specify the desired user name and password, log in using the created credentials, and you should see the application's dashboard.

Before you can start using Freehold, you need to add the Admin Console and Explorer apps to it (Figure 2). The former allows you to manage users, backups, and application settings, and the latter is used to manage files. Installing both apps is a matter of hitting the Install button next to each item in the Available to Install section.

Figure 2: Freehold comes with several apps including Admin Console and Explorer.

Populating Freehold with files couldn't be easier. Launch the Explorer app, switch to the files section in the navigation sidebar, and drop the files from your machine onto the main area to upload them. Alternatively, you can use the dedicated Upload Files button.

Click on the Properties icon next to the file item, and you can tweak the file's properties in the Properties window (Figure 3). Here, you can star the file, modify its permissions and owner, and change the default color and handling behavior. The latter two properties are global (i.e., they apply to all files of the same type). The Sharing section of the Properties window lets you generate a sharable link to the current file with a single press on the New Link button (Figure 4). The system automatically sets an expiration date for the link, but you can remove it, if necessary.

Figure 3: Editing file properties.
Figure 4: Files in Freehold can be shared via automatically generated links.

Files in Freehold can be organized into folders and subfolders, and you can switch between the icon and list views. You can also sort items by name, owner, modification date, and size. A search feature is available for finding specific files and documents.

The Admin Console app provides access to administrative functions, such as adding and managing user accounts, viewing logs, tweaking Freehold's settings, and creating backups. All features in the administration dashboard are straightforward in use. Creating a user account, for example, is a matter of pressing the New User button under the Users tab and filling out the required fields. Because Freehold works perfectly well with the default configuration, there is no need to tweak the settings. However, if you decide to do that, brief descriptions provide clues to what each configuration option does.

In addition to hosting and sharing files, Freehold can act as a synchronization platform courtesy of the dedicated Freehold-Sync tool (Figure 5). Like Freehold, the sync client is written in Go, and it requires no installation. Grab the Freehold-Sync client for your platform, unpack the downloaded archive, switch to the resulting directory, and run the ./freehold-sync command.

Figure 5: Freehold-Sync client turns Freehold into a synchronization platform.

Point your browser to, and you should see Freehold-Sync's dashboard. Hit the New Profile button to create and configure a synchronization profile. Add paths to the local directory and a remote Freehold folder you want to keep in sync, specify a syncing direction, and give the profile a name. Press the Advanced button if you want to modify the default conflict resolution behavior and add an ignore rule. Hit New to save the profile and the client will keep the specified directories in sync.

Final Word

Both Osync and Freehold are really nifty tools. Osync transforms rsync into a capable bidirectional synchronization tool that boasts a range of genuinely useful features and is supremely easy to use. Freehold, in turn, is a no-nonsense platform for hosting and sharing files that can be deployed in a matter of minutes even on modest hardware like Raspberry Pi. Better still, the accompanying Freehold-Sync client provides an easy way to keep your data in sync across multiple machines.

Buy this article as PDF

Express-Checkout as PDF
Price $2.95
(incl. VAT)

Buy Linux Magazine

Get it on Google Play

US / Canada

Get it on Google Play

UK / Australia

comments powered by Disqus

Direct Download

Read full article as PDF:

Price $2.95

Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs
Subscribe to our ADMIN Newsletters
Find SysAdmin Jobs