Sharing Binary Assets with BTSync

BTSync Web Interface
BTSync Web Interface on Linux NAS.

We recently began using BTSync to share binary assets with members of project teams. At Atomic Object, binary assets are often images or design-related files, and are uniquely challenging to manage and distribute.

The Binary Asset Problem

Almost all source code and files at Atomic Object are managed with a version control system (VCS) such as git, mercurial, and even venerable old svn. However, VCS software does not handle binary files very efficiently, and the value of any binary diff is quite marginal. In addition, the binary assets are usually rather large (in comparison to source code), and so quickly bloat a VCS repo with a history of changes which are often not needed.

There have been a few different attempted solutions to this problem: shared network drives (NFS/Samba/AFP), external hard drives, USB thumb drives, etc. Sometimes the files were still kept in svn or git repositories despite the issues mentioned above. All of these solutions are workable, but each has snags which detracted from the suitability for this purpose.

For example:

  • Shared network drives (NFS/Samba/AFP):
    Only useful within the office. Too slow over the VPN.
  • External hard drives / USB thumb drives:
    Synchronization and stewardship issues (“Who has the drive?”).
  • VCS Software (git/mercurial/svn):
    Massive repositories due to inefficient binary diffs.

DropBox seemed like a promising solution, but the personal plans were limited to only 2 GB for the free tier, and quickly ramped up in price for the business tier. While this wasn’t prohibitively expensive, the search for other options continued.


BTSync is a product of BitTorrent, Inc. Technically, it is still classified as an “experiment,” coming out of BitTorrent Labs, but it works exceptionally well despite this. It operates using the BitTorrent peer-to-peer (P2P) protocol, but rather than targeting one-way file distribution, it synchronizes shared files across multiple nodes. When a file is changed on one node, that change is propagated to other nodes. Additionally, communication over the BitTorrent protocol is encrypted so that files can be synchronized securely.


Getting BTSync clients installed and operating on individual computers is quite easy. Clients are available for many platforms, including Linux, Mac, Windows, and mobile. The interface is fairly intuitive, and the BTSync website provides good guidance. Like DropBox, BTSync will attempt to utilize a LAN for communication if it is available. This makes file transfers very speedy within an office.

At Atomic, synchronized folders are created on a per-project basis. This allows members of project teams to selectively participate in synchronized folders. If people leave a project, they can remove all files for that project from their computers without affecting files for other projects. When people join a project, they add the synchronized folder and receives all files.


BTSync security is achieved via a “shared secret” strategy. Shared folders are identified by a unique secret key. By default, the secret key is a randomly generated 21 byte sequence. For convenience, it is encoded as base64 for readability. Any user wishing to participate in the synchronization of the shared folder must enter the secret key on the BTSync client on his or her computer.

The secret key itself is never transmitted. It is hashed using SHA256 to identify the node when connecting to BitTorrent trackers or DHT, and used to generate the AES-256 key used to encrypt communication between nodes synchronizing a particular folder.


BTSync has a very robust connection mechanism. If it can communicate with other nodes via a LAN, it will. It will attempt to connect directly over other networks and, if it cannot, will make use of NAT port mapping or a relay server to achieve a connection. In testing, it was quite easy to get BTSync to work despite firewalls and multiple NAT.

By default, BTSync attempts to use a tracker server (like traditional P2P) to connect peers. However, it also supports DHT (though making a connection seems to be less likely due to the mechanism). In addition, if you do not want to use either, you can enter connection information for peers manually (IP address and port).

The Question of Availability

The only major issue encountered was availability of synchronized folders. Since BTSync operates using P2P protocols, files only exist on participating nodes. What if no one participating in a particular synchronized folder was online when someone new wanted access to the folder? With something like DropBox, this wouldn’t matter as a central server is always available to provide access to the files.

To handle this situation, a dedicated server was created on the internal Atomic network to be available as a peer for all synchronized folders. Since BTSync handles creating connections even over the Internet without a VPN connection, anyone with the appropriate secret key for a folder can begin receiving files from the dedicated server even if no other participants are online.

Fortunately, it seems that the folks at BitTorrent foresaw this and created a version of the BTSync client with a web interface specifically for Linux. This makes it very easy to setup a “NAS” which operates as described above.

Other Benefits of BTSync

In addition to allowing members of a team to share files (and file changes) easily among each other, a team can selectively share with outsiders — customers or other project stakeholders. Anyone can be given full access to a synchronized folder with the secret key as described above. However, there are two other special-purpose secret keys: read-only keys, and one-time keys.

The read-only key is fairly self-explanatory: joining a synchronized folder with a read-only key only permits a node to receive files and subsequent update. Any changes made on the node with the read-only key are not propagated.

The one-time key is a bit more curious: a one-time key only works once. Once it has been used to join a node to a synchronized folder, it can not be used again. This could be very useful if you wanted only one person to have access to a synchronized folder, but did not want that person to be able to pass on the information to anyone else. (One-time keys can be created as full access or read-only).

These alternate mechanisms introduce the possibility of creating interesting workflows for sharing and distributing files to people outside a given project team.