BitTorrent Sync Server Package
BitTorrent Sync Server Package
BitTorrent® Inc. delivers for Linux users only a raw binary file without any deployment concept or setup system. It's up to the user to create a reliable startup and shutdown logic, manage configuration files, internal storage directories and everything else related to file and directory permissions, application update and various other aspects.
The BitTorrent Sync Server Package (
btsync) is the ideal solution for all
users that want to deploy BitTorrent Sync on Linux servers running Debian or
other derived distributions like Ubuntu, Raspbian, Linux Mint or similar.
THIS SERVER PACKAGE IS UNOFFICIAL AND NOT THE WORK OF BITTORRENT® INC. PLEASE DO NOT CONTACT THE BITTORRENT® INC. SUPPORT WITH QUESTIONS OR PROBLEMS RELATED TO THE USE OF THE PACKAGE. YOU WILL FIND COMPETENT HELP AND SUPPORT IN THE SUPPORT FORUM
Typical Use Cases
The BitTorrent Sync Server Package is designed to run one or more BitTorrent Sync background processes (called "instances") on servers where no specific user is usually logged on. Since the server package does not provide any GUI (except for the optional Web UI provided by BitTorrent Sync itself), it can be also installed on headless servers (without any desktop environment).
The server version is particularly suitable for the following use cases:
- BitTorrent Sync is used as a background service, to keep directories in sync between all servers of a distributed infrastructure like a PXE boot system and groups of shared configuration files.
- Always-on instances of BitTorrent Sync for providing an always available external copy and source of replicated data for other BitTorrent Sync clients.
- A content distribution network based on shared folders.
- Customized services built upon the functionality of BitTorrent Sync.
The most easy and fast way to install the repository is to paste that at a terminal prompt:
sh -c "$(curl -fsSL http://debian.yeasoft.net/add-btsync-repository.sh)"
The script explains what it will do and then pauses before it does it asking for your permission. If you encounter any problems or prefer to do it manually, please look here.
Now update the package index and install
btsync by pasting that at a
`which sudo` apt-get update `which sudo` apt-get install btsync
After downloading the packages, the installation begins. The package manager will ask you, if you want a default instance of BitTorrent Sync to be created. If you answer yes, you will be guided through the installation and when finished you will have a fully operational BitTorrent Sync instance maintained by debconf. The configuration can be modified and fine tuned at any time by performing the following command:
`which sudo` dpkg-reconfigure btsync
Here you can also choose to delete the default instance by answering no to the initial question.
The BitTorrent Sync Server Package mainly consists of an init-style startup script that manages every operational aspect of running BitTorrent Sync instances.
Instance Configuration Files
All operational parameters for BitTorrent Sync instances are configured in
configuration files located in the directory
/etc/btsync. These configuration
files basically are JSON Files and follow
a very strict syntax. In addition to the JSON specification, comments are also
supported. The support of commented lines permits to specify additional
parameters that are not directly parsed by the BitTorrent Sync executable itself
but by the init-script.
The naming convention for configuration files defining BitTorrent Sync instances is:
<instance_name> should be a string consisting of alphanumeric
The default instance maintained by debconf has also a configuration file that
debconf-default.conf. This name shall never be used by manually
created configuration files, since it may be deleted or overwritten by
debconf. This file shall also never be edited manually since it is often
rewritten and/or created/deleted by debconf. If you want to manage the default
instance, you must always use the command:
`which sudo` dpkg-reconfigure btsync
Each configuration file in
/etc/btsync defines a separate running BitTorrent
Sync instance (that means: a process). When defining more than one instance
on a system, there are some rules that must be considered:
- The listening ports (parameter
listening_port) must be unique for each BitTorrent Sync instance
- The internal database path (parameter
storage_path) must be unique for each BitTorrent Sync instance
- If the Web UI is enabled, the Web UI bind address and listening port
listen) must be unique for each BitTorrent Sync instance
The syntax and configuration parameters of a BitTorrent Sync configuration file
are partially documented in the example file
and in the official BitTorrent Sync manual
which can be also found in
There are additional parameters that are parsed by the init script upon startup and affect many important aspects. These parameters are not parsed directly by BitTorrent Sync and therefore have to be placed in comment lines. In order to improve the readability of configuration files, they should be grouped together and placed at the beginning of the configuration file. The generic syntax of such parameters is:
// PARAMETER_NAME=<parameter value>
The following parameters are supported:
DAEMON_UID: A uid (user id) for specifying the user under which the BitTorrent Sync instance should run
DAEMON_GID: A gid (group id) for specifying the group under which the BitTorrent Sync instance should run
DAEMON_UMASK: The umask (up to 4 octal digits) for the BitTorrent Sync instance. If omitted the default umask is used.
DAEMON_DEBUG: The debug mask (4 hex digits) for the BitTorrent Sync instance. If omitted the init script will not touch potential settings defined manually. If set to
0000, a potential settings file will be deleted. Full detail is set by specifying
FFFF. The log file can be found in the directory specified by
storage_pathand is named
DAEMON_NICE: The niceness level of the BitTorrent Sync instance, which affects the process scheduling. Nicenesses range from -20 (most favorable scheduling) to 19 (least favorable).
DAEMON_BIND: This parameter works only in conjunction with the package
bind-shim. Please see the specific section below covering the specific interface binding topic.
// // DAEMON_UID=jdoe // DAEMON_UMASK=0002 //
This example will launch the instance running under the credentials of the user "jdoe" using 0002 as umask.
DAEMON_GID it is possible to specify under which
credentials the instance runs. In this case it MUST be assured that the
instance is able to read and write all files it must access:
- The instance must be able to read its own configuration file. Since the
configuration file may contain sensitive data (the userame and password for
the web interface), it is usually owned by the user under which the
instance runs and has the mode
400 (-r--------)in order to limit the access to the specific user. Usually the init script takes care of adjusting the file permissions.
- The instance must be able to read and write in its
storage_path, since all internal control and status files (and the database of file hashes) are kept there. The ideal solution is to keep the
storage_pathsomewhere in the home directory of the user under which the instance will run. Usually the init script takes care of adjusting the file permissions.
- Obviously the instance must be able to read and write the files and directories that will be synchronized.
Some example configuration files are provided under
Modular Configuration Files
I want to have a config file per shared folder. I currently manage 10-20 linux servers. The servers are all connected with btsync. I have created a system that can push scripts to the servers en executed them. But when i need to change one shared folder on one server i just want to push a new file without to touch the other parameters in the config file.
If you want to create a modular configuration file, create a directory in
/etc/btsync named like you would name the configuration file, but with an
.d extension and put the parts of your configuration file in it.
The daemon init script will generate a configuration file at every start by
joining all in alphabetical order. Parts must be text files with the
Default Startup Parameters
The additional configuration file
/etc/default/btsync permits to specify
some default startup parameters that may affect every configured instance of
The variable AUTOSTART defines which instances are started automatically. It can take the following values:
noneNo instance is started automatically
all(default) All instances are started automatically
<list>Only the specified instances are started automatically
Instances not started automatically upon system startup can be managed manually from the command line:
# start a specific instance service btsync start <instance_name> # stop a specific instance service btsync stop <instance_name>
The advanced variable DAEMON_ARGS allows to specify additional command line parameters passed to the daemon. WARNING: Be careful! You should only add things here if you know EXACTLY what you are doing!
The variable DAEMON_BIND has the same purpose as the same parameter in the instance configuration files, but in this scope it will be applied by default to all instances. Please see the specific section below covering the specific interface binding topic.
The variable DAEMON_INIT_DEBUG permits to enable extended debug output of the init-script.
BitTorrent Sync 1.4 supports also SSL connections to the Web UI. The default instance is automatically configured to use a self signed certificate and key created during the installation.
The configuration file does not point directly to the self signed certificate but to the following symbolic links:
The default instance can be operated also with user provided certificates without tampering with the configuration file by deleting the symbolic links and replacing them with files containing the desired certificate and key. Debconf will detect that the files are not symbolic links and leave them untouched during reconfiguration.
The certificate file and key file must be accessible by the BitTorrent Sync daemon.
Binding BitTorrent Sync to a specific interface
Unfortunately BitTorrent Sync currently does not support to bind the main service routine to a specific network interface. Currently only the internal web server providing the Web UI and the BitTorrent Sync API can be specifically bound to a specific address.
In order to limit the operation of BitTorrent Sync to a specific interface in a multihomed environment, a so called preload shim can be used. The BitTorrent Sync repository contains a precompiled version of Daniel Ryde's bind.so shim that must be installed with:
`which sudo` apt-get install bind-shim
The BitTorrent Sync init script does detect the presence of the library and
enables support for the additional parameter DAEMON_BIND that can be
specified either in
/etc/default/btsync or in instance configuration files.
By specifying a valid TCP/IP address assigned to one of the interfaces of the
system, the BitTorrent Sync instance will bind only to that specific address.
This will affect also the Web UI, if
0.0.0.0 is specified as the bind address.
The deb-packages are available for the same architectures as released by BitTorrent Inc.:
- i386 - Intel/AMD 32 Bit
- amd64 - Intel/AMD 64 Bit
- armel - ARM EABI
- armhf - ARM hard float
- powerpc - PowerPC
Since the packages still have not been tested on every platform, any related feedback is highly appreciated.
Bug Reports, Contribution and Sources
If you want to contribute to the development of the packages or if you are curious how this all works, you may find the current sources of the deployment scripts and packaging on GitHub (https://github.com/tuxpoldo/btsync-deb)
If you want to contribute to the localisation by translating changed strings or by adding support for your favourite language, you may join the localisation team on POEditor.com.
If you have experienced a reproducible issue that is related to the packaging and not to BitTorrent Sync itself you are strongly encouraged to open an issue on the project's GitHub Page. Issues related to the native functionality of BitTorrent Sync should instead be discussed by creating a new topic or partecipating to an already existing topic in the BitTorrent Sync Forum.