Beware this content is over 6 years old and considered stale. It may no longer be accurate and/or reflect the understanding of the author but remains here for reference only. Please keep this in mind as you use this content.

In the past, I’ve been using Dropbox to securely store backups for sites. However, since I was introduced to BitTorrent Sync (BT Sync), I immediately liked the concept of running by own Dropbox-like setup without the costs and limits that Dropbox imposes.

The documentation is still a little sparse and somewhat confusing, so I’ve put together these few instructions to help get you up and running.

As BT Sync is still in alpha stage of development, it’s seeing lots of updates and is in active development so versions and options and features are likely to change rapidly. Another aspect of it being an alpha release is that it’s likely still a little risky and therefore YMMV.

I would still recommend you hold a secure backup but there is no reason why you cannot use both.

At time of publishing, the latest version of BitTorrent Sync is 1.0.134. You can see the download options here:

Before we get going, I’ll assume you’re server is running a current version of Ubuntu, I’m using 12.04.2 LTS (Precise). If you’re not sure what whether your version of Ubuntu is 64-bit or not, you can try this command on the command line:

$ arch

It will return x86_64 for most 64-bit versions.

You’ll first want to create a directory for BT Sync to run in as the current download only contains the executable btsync and LICENSE.txt

$ mkdir ~/.btsync

Next you’ll want to actually download the files from the BitTorrent site.

For the 64-bit version of BT Sync use this command:

$ cd ~/.btsync && wget -O - "" | tar xzf -

Or use this one if your architecture is i386:

$ cd ~/.btsync && wget -O - "" | tar xzf -

After using that previous command, you should now be able to see the executable file and the license file in that directory you just created.

Run the following to check the version of your executable and see the options:

$ ~/.btsync/btsync --help

You’ll want to ensure that the files you’ve just downloaded have the correct permissions set for them.

Now you’ll want to create a configuration file for the executable to use. BT Sync comes with an option to generate a sample file by using the following:

$ ~/.btsync/btsync --dump-sample-config > ~/.btsync/sync.conf

Once you’ve generated a sample configuration file, you’ll need to open it and edit it. At this stage you may want to do the following to get the a test folder ready for a sync.

But before that you may want to generate a secret for the folder you’re going to want to sync.

BT Sync gives you two options for creating a secret. The default secret for a folder (which every folder you want to sync will need to have) gives a linked device full permissions on that folder resulting in any changes in a linked folder to be replicated across all other linked folder(s).

The alternative to the full permissions secret is a read-only secret, which means that any changes on a linked remote folder(s) will not affect the source folder or any other linked folders.

Use the following to generate a unique secret:

$ ~/.btsync/btsync --generate-secret

That command should output an a 32 character alphanumeric string with uppercase alpha characters.


You’ll want to make a note of the secret that was created. You’ll need it later.

If you want to generate a read-only secret, you’ll need to pass the secret you generated to the command:

$ ~/.btsync/btsync --get-ro-secret A1B2C3D4E5F6GHIJKLMNOPQRSTUVWXYZ

That will then output another, slightly longer alphanumeric secret which will permit read-only access to the folder.

While you can link to any folder on your system, it helps to keep things neat and tidy by creating a separate folder that holds all the folders you might want to sync.

$ mkdir ~/BTSync && mkdir ~/BTSync/

That creates two folders one in the other. The second mkdir creates a folder called, which could be anything but in this example, it creates a folder that we’ll store some backup files in for our website

Now that you have a folder path and a secret we can go ahead and begin editing the BT Sync configuration file. You may want to keep a backup of the sample configuration file, just in case.

$ cp ~/.btsync/sync.conf ~/.btsync/sync.conf.orig
$ vi ~/.btsync/sync.conf

Once you’ve opened the sample configuration file, you’ll see that it is in JSON format and heavily annotated so you should be able to work your way through it. The key things to remember are the following:

  • device_name: change the this to something that will help you identify the server.
  • listening_port: Define a unique and unused port for the service to listen on.
  • storage_path: This will be the full absolute path to the .btsync folder you created earlier. If you’re not sure, you can go to the folder and type pwd.
  • pid_file: You can leave this as it is, but I like to keep everything in once place so I change it to be within the storage_path and uncomment the line by deleting the two leading forward slashes.
  • check_for_updates: Change to false as its not needed on a server.
  • use_upnp: Change to false as its not needed on a server.
  • webui/listen: Comment out the line “listen”: “0.0.0:8888” to turn off the web user interface as you won’t need it. Use two forward slashes (//) to comment out a line.
  • shared_folders: At approximately line 40 in the file, before the shared_folders list, there may be the start multi-line comment (/) that you’ll have to remove. Don’t forget the corresponding closing comment line (/) at approximately line 63.
  • shared_folders/secret: Paste the secret you generated earlier here.
  • shared_folders/dir: This needs to be the absolute path of the folder you want to sync.
  • shared_folders/use_relay_server: Change to false.
  • shared_folders/use_tracker: Change to false.
  • shared_folders/search_lan: Change to false.
  • shared_folders/known_hosts: Enter each linked device in the format of IP/host a colon (:) and then the port number. Add multiple devices by separating each string with a comma (,).

Once the changes have been made and your happy the document is valid JSON, you can save your changes.

Your configuration file will likely look something like this (NB: I’ve stripped out all the annotations):

"device_name": "web server",
"listening_port" : 8888,
"storage_path" : "/root/.btsync",
"pid_file" : "/root/.btsync/",
"check_for_updates" : false,
"use_upnp" : false,
"download_limit" : 0,
"upload_limit" : 0,
"webui" : {
//"listen" : "",
"login" : "admin",
"password" : "password"
"shared_folders" :
"dir" : "/root/BTSync/",
"use_relay_server" : false,
"use_tracker" : false,
"use_dht" : false,
"search_lan" : false,
"use_sync_trash" : false,
"known_hosts" :

Now to start BT Sync running, run this:

$ ~/.btsync/btsync --config ~/.btsync/sync.conf
You should then see the following output:
By using this application, you agree to our Privacy Policy and Terms.

BitTorrent Sync forked to background. pid = 27732

The pid will likely be different number. That’s what you’ll need to kill the process should you need to modify the configuration file.

If you see an error, this is most likely due to an invalid JSON file or a folder path being incorrect. Check both and try again.

If you need to kill the BT Sync instance you can do that by using the following command.

$ kill -15 27732

You’ll notice the number 27732 is the pid that BT Sync mentioned when I started it. If you forget you can check the .pid file in the ~/.btsync directory:

$ cat ~/.btsync/

Once it’s stopped, make your changes and get it running again:

$ ~/.btsync/btsync --config ~/.btsync/sync.conf

Next, make sure you setup the linked device to start syncing a folder on the server you have just setup.

Once that is ready, try dropping a file in a folder and keep an eye out for the changes.

If you hit any problems getting it up and running, drop a comment below.