How To Use BitTorrent Sync to Synchronize Directories in Ubuntu 12.04
How To Use BitTorrent Sync to Synchronize Directories in Ubuntu 12.04
We hope you find this tutorial helpful. In addition to guides like this one, we provide simple cloud infrastructure for developers. Learn more →

How To Use BitTorrent Sync to Synchronize Directories in Ubuntu 12.04

Posted Jan 16, 2014 146.6k views Backups Miscellaneous Ubuntu


Syncing folders and files between computers and devices can be done in many different ways. One method for automatically syncing content is BitTorrent Sync. BitTorrent Sync is a method of synchronizing content based on the popular BitTorrent protocol for file sharing.

Unlike traditional BitTorrent, files shared using BitTorrent Sync are encrypted and access is restricted based on a shared secret that is auto-generated. While BitTorrent proper is often used to distribute files in a public way, BitTorrent Sync is often used as a private method to sync and share files between devices due to its added security measures.

In this guide, we will discuss how to install and configure BitTorrent Sync on two Ubuntu 12.04 VPS instances.

Install BitTorrent Sync

To begin, we will need to install BitTorrent Sync on both of our Ubuntu 12.04 instances. If you would like to install BitTorrent Sync on your local computer to allow you to sync with your server, you can find the binary packages here.

BitTorrent Sync is relatively easy to install on Ubuntu 12.04, but it is not included in the default repositories. We can use a PPA (personal package archive) so that we can have access to a maintained BitTorrent Sync repository and manage it with our normal apt tools.

Ubuntu 12.04 includes the PPA tools in a package called python-software-properties, which we can download through apt:

sudo apt-get update
sudo apt-get install python-software-properties

After this is installed, we can add the PPA that contains updated Ubuntu packages:

sudo add-apt-repository ppa:tuxpoldo/btsync

Press "enter" to add the new PPA.

Once the new repository is added, we should update apt to build a package index for the new source, and then install the BitTorrent Sync software:

sudo apt-get update
sudo apt-get install btsync

Initial Configuration During Installation

During the installation phase, you will be asked a number of questions that can assist you in configuring the service. The first question asks if you'd like to do this configuration to define a default BitTorrent Sync instance. Select "Yes".

We want operate BitTorrent Sync with its own user and group for security purposes. Select btsync for the next question.

The next question will be about the port you wish to use to communicate between instances. You can leave the selection at 0 to have btsync choose a random port each time it starts. If you are configuring a firewall for your server (which is highly recommended), you probably want to define a specific port.

The next question asks about configuring a UPNP request, which we don't need. Select "No".

Next, define your download and upload limits. If you do not wish to limit either of these, leave the default of 0 to allow maximum throughput.

Next, you'll be asked which interface you wish to configure the service for. If you leave it at, the BitTorrent Sync service will use any available interface. If you wish to restrict it to one network, such as the DigitalOcean private network, you can specify the appropriate IP address here. Note that you will not be able to sync to your home computer using the private network.

Next, select a port to access the web interface. The default value is 8888, but you can change that to any open port.

Finally, select a username and password to secure the web interface.

The installation will complete and your service will be started.

If you need to change the configuration at some point in the future, you can run through the configuration menus at any time by issuing:

sudo dpkg-reconfigure btsync

The configuration directory for the service is:


Do not edit the config file generated by the menu system by hand. You can, however, copy the configuration to use as a template for another configuration if you'd like to adjust details not covered in the menu configuration.

How To Configure Shared Folders

In order to sync folders with BitTorrent Sync, the btsync user or group needs write access to the folders. There are a few different ways to achieve this.

First, let's create the folder:

sudo mkdir /shared

We need to complete these steps on both of your VPS instances that will be syncing.

Giving the btsync Process Full Ownership

One way to give the btsync user access is to simply give ownership of the folder to the btsync user:

sudo chown btsync:btsync /shared

This will allow the BitTorrent Sync service to correctly serve the contents of this directory, but we are not able to write to this as a normal user. This may be what you want, but it usually is not.

Give Your Normal User Ownership and the btsync Process Group Ownership

If you have only one normal user on the system, you can give that user ownership of the folder and give the btsync group ownership of the folder:

sudo chown your_user:btsync /shared

You would then have to give the group write permissions:

sudo chmod 775 /shared

This will allow the btsync service to access the folder. However, any files created inside the directory will be owned by your user and group.

For instance, if we add a file to this folder called test, it would be completely owned by our user:

cd /shared
touch test
ls -l
-rw-rw-r-- 1 your_user your_user 6 Jan 16 14:36 test

This will cause problems for the syncing, because the btsync process cannot modify the file. We want to give it the same group permissions as the folder it is in so that the process has write access.

We can do this by setting the SGID bit on the directory. This will set the group on all new files created inside of the directory to the group of the directory itself. This will allow proper write access to modify things:

sudo chmod g+s /shared

Now, when we create a file, it will be given the permissions of the directory:

cd /shared
touch test2
ls -l
-rw-rw-r-- 1 your_user your_user 6 Jan 16 14:36 test
-rw-rw-r-- 1 your_user btsync 0 Jan 16 14:41 test2

This goes a long way towards getting the appropriate functionality, but it isn't quite right yet.

Delete the test files we created before continuing:

rm /shared/test*

Add Your User to the btsync Group and Give the Root User Ownership

The method above works somewhat, but files that are transferred with BitTorrent Sync are owned by the btsync user and group. This means that currently, any files synced by the service will not be editable by us.

We can change this by adding our user to the btsync group. This will allow us to modify files that are writeable by the btsync group, which is what we want.

Add any username that you wish to be able to use btsync to the btsync group:

sudo usermod -a -G btsync your_user

This will append the btsync group to your user's group definition. This will allow you to edit files created in the shared folder by the btsync process.

However, the directory is still owned by our user, which is not a good way of going about things if we have multiple users on the system. We should transfer ownership to the root user to avoid regular users changing folder settings. We should also allow group write permissions so that anyone in the btsync group can add content:

sudo chown root:btsync /shared
sudo chmod g+w /shared

You may have to log out and log back in for these changes to take affect.

In the end, the process for creating a shared folder that works well for BitTorrent Sync goes something like this:

sudo mkdir shared_folder
sudo chown root:btsync shared_folder
sudo chmod 2775 shared_folder
sudo usermod -a -G btsync your_user

The first "2" in the chmod command sets the SGID bit in the same way that the "g+s" did previously. This is just a more succinct way of combining these commands.

Accessing the BitTorrent Sync Web Interface

Now that we have a folder that is configured appropriately for BitTorrent Sync sharing, we can access the web interface to add our folder to begin syncing.

Again, we will have to do this on each of the servers that we wish to configure syncing on.

Access the web interface by going to your droplet's IP address, followed by the port you configured during install. By default, this is 8888:


BitTorrent Sync login

You will have to sign in using the credentials you configured during installation. The default username is admin if you didn't change it.

You will be presented with a rather simple interface to start:

BitTorrent Sync main page

Adding the Shared Folder to the First Droplet

Now that we are in our web interface, we can add our shared folder so that the btsync process can register it.

On your first machine, click on the "Add Folder" button in the upper-right corner. This will bring up a box that allows you to select a directory to share:

BitTorrent Sync add folder

Find the folder that you configured for sharing. In our case, this is the /shared folder. Once you have a folder selected, you should click on the "Generate" button to generate a secret for the folder.

BitTorrent Sync generate secret

The secret that is generated allows you to sync this folder with another instance of BitTorrent Sync. This unique value is basically a password to allow the two services to connect to each other.

Click the "Add" button when you have completed these steps. This will add our folder to the interface and give you some buttons on the side to manage this folder.

BitTorrent Sync buttons

Right now, we are only interested in the "Secret/QR" button. Click this to bring up a box that will allow you to choose how you want to share this folder.

We can grant access to the folder with read/write permissions through "Full access". If we only want to sync one way, like a backup, we can allow only read access. The secrets that are provided for each kind of access differ.

Copy the secret for the type of access you want. We will be using full access in this tutorial.

Adding the Shared Folder and Secret to the Second Droplet

Now that we have our secret from our first VPS, we can add the shared folder that we created on our second VPS and use the secret to sync our files.

First, you must log into the web interface just like you did with the first server:


Once you are to the interface for the second server, click the "Add Folder" button again.

Add the locally created shared folder.

This time, instead of clicking the "Generate" button, we will paste the secret from the other instance into the "Secret" box:

BitTorrent Sync pasted secret

Click the "Add" button to create the share.

After a moment, in both web interfaces, you should see some new information in the "Connected devices and status" section:

BitTorrent Sync connected devices

This means that our two instances of BitTorrent Sync have found each other! The icon in front means that we have given full access and files will be synced in both directions.

Test Syncing

Now that we have configured syncing, let's test to see if it works.

On one of your servers (it doesn't matter which one if you configured full access), we will add some files to our shared folder.

As a user that has been given access to the btsync group, create some files in the shared directory:

cd /shared
touch file {1..10}

This will create 10 files in the shared directory. We can check that these have been given the appropriate permissions by typing:

ls -l

-rw-rw-r-- 1 your_user btsync 0 Jan 16 16:16 file1
-rw-rw-r-- 1 your_user btsync 0 Jan 16 16:16 file10
-rw-rw-r-- 1 your_user btsync 0 Jan 16 16:16 file2
-rw-rw-r-- 1 your_user btsync 0 Jan 16 16:16 file3
-rw-rw-r-- 1 your_user btsync 0 Jan 16 16:16 file4
. . .

As you can see, the files are owned by your user, but the group owner is btsync. This is exactly what we want.

If we check our other server after a few seconds, we should see our files in our shared directory!

cd /shared
ls -l

-rw-r--r-- 1 btsync btsync 0 Jan 16 16:16 file1
-rw-r--r-- 1 btsync btsync 0 Jan 16 16:16 file10
-rw-r--r-- 1 btsync btsync 0 Jan 16 16:16 file2
-rw-r--r-- 1 btsync btsync 0 Jan 16 16:16 file3
-rw-r--r-- 1 btsync btsync 0 Jan 16 16:16 file4

As you can see, the files are given to the btuser and group. This is because the service can't be sure that the original username exists on the second system.

The last step is to get the btsync daemon to automatically set the file permissions of the files that it syncs to be writeable by the btsync group. This is necessary if you are providing full access in order for your user to edit the files that it has synced.

We can do this in by reconfiguring the btsync daemon. This will open up a lot more options than we were given when we originally went through the configuration. Begin to reconfigure on both of your syncing machines by typing:

sudo dpkg-reconfigure btsync

You will run through the configuration menu, this time with many more questions. For the most part, it should automatically select either your previous selection, or the default choice for any previously unset parameters. One question that you'll have to remember not to skip is the password prompt.

The option that you are looking is the default umask for files synced by the daemon.

We can set the appropriate umask to create files that are writeable by both the owner and the group (which our user is a part of), by typing this:


Finish up the configuration and the daemon should restart automatically with the new settings. Once you have completed this task on both servers, you should be able to create a new file on one server, and it will be given correct writeable permissions on the second host:

touch /shared/write_test

On the second host once the file syncs, you'll see somethings like this:

-rw-rw-r-- 1 btsync btsync  0 Jan 30 10:44 write_test

In the web interface, you will not see that your files have been synced, because the files don't contain any actual data. If we add some content to our files, the interface will update to show how many files we have synced:

for item in /shared/file{1..10}; do echo "some content" > $item; done

BitTorrent Sync file size


Now that you have your servers configured, you can easily transfer files between them. You can also configure multiple folders to automatically sync. This can provide some interesting options for dealing with configuration files and such.

The application is fairly flexible in how to sync between multiple computers. You can create one-time secrets to ensure that no one shares access to your directories, you can share only with specific hosts, and sync between your mobile device. BitTorrent Sync provides an archive version control system through the .SyncArchive file in directories and can rate limit to ensure that you have bandwidth available for other applications.

By Justin Ellingwood


Creative Commons License