qBittorrent has a feature-rich Web UI allowing users to control qBittorrent remotely. This is ideal for headless servers without the X window system such as Ubuntu Server.
Since Ubuntu (Server) 15.04, upstart was replaced with systemd. Thus, this guide only applies to Ubuntu 15.04 and newer. This change only affects how qbittorrent is started (init scripts) and how logging happens.
A little about qBittorent-nox vs qBittorrent:
The main binary file (executable file) for qBittorrent has two variants and is usually located at /usr/bin/:
- qbittorrent which is qBittorrent with Graphical user interface and
- qbittorrent-nox which is same as the above but compiled without the desktop graphical user interface, and only a web-interface.
Since this guide focuses on servers that normally don’t have a desktop user interface, we will use the qbittorrent-nox binary, but we still call it by it’s regular name – qbittorrent.
qBittorrent is now available in official Ubuntu repositories.
More up-to-date packages are published on our stable and unstable PPAs.
The stable PPA supports Ubuntu 14.04 LTS (only the libtorrent-rasterbar package), 16.04 LTS, 17.04, 17.10, 18.04 LTS, and 19.10.
To use these PPAs please use the following command and make sure your version is supported:
$ sudo add-apt-repository ppa:qbittorrent-team/qbittorrent-stable
Then install qBittorrent by doing this:
$ sudo apt-get update && sudo apt-get install qbittorrent-nox
Assuming you want qbittorent to run as its own user (better for security purposes), let’s create the user that qbittorrent will run under and give it a password when prompted. Just press
Return for values you want to leave blank:
sudo adduser qbtuser Adding user `qbtuser' ... Adding new group `qbtuser' (1003) ... Adding new user `qbtuser' (1003) with group `qbtuser' ... Creating home directory `/home/qbtuser' ... Copying files from `/etc/skel' ... Enter new UNIX password: Retype new UNIX password: passwd: password updated successfully Changing the user information for qbtuser Enter the new value, or press ENTER for the default Full Name : Room Number : Work Phone : Home Phone : Other : Is the information correct? [Y/n] y
First, create a file:
[Unit] Description=qBittorrent Daemon Service Documentation=man:qbittorrent-nox(1) Wants=network-online.target After=network-online.target nss-lookup.target [Service] # if you have systemd >= 240, you probably want to use Type=exec instead Type=simple User=qbtuser ExecStart=/usr/bin/qbittorrent-nox TimeoutStopSec=infinity [Install] WantedBy=multi-user.target
Normally after editing services we’d issue a reload command but since it will also invoke qbittorrent before we initialized the configuration, we’ll give it a skip for now. If you ever make changes to the services file, update systemctl with:
$ sudo systemctl daemon-reload
Before we continue, let’s run qbittorrent so that it can ask us to accept the disclaimer, and save and create the config file to remember this setting. Doing this will create and save the configuration files under:
First we impersonate the qbtuser:
$ sudo su qbtuser
And run qbittorrent:
You should see the following:
*** Legal Notice *** qBittorrent is a file sharing program. When you run a torrent, its data will be made available to others by means of upload. Any content you share is your sole responsibility. No further notices will be issued. Press 'y' key to accept and continue...
Press y key and you should see:
******** Information ******** To control qBittorrent, access the Web UI at http://localhost:8080 The Web UI administrator user name is: admin The Web UI administrator password is still the default one: adminadmin This is a security risk, please consider changing your password from program preferences. 03/02/2016 15:51:03 - The Web UI is listening on port 8080 03/02/2016 15:51:04 - qBittorrent is successfully listening on ...
Without doing anything further, you should be able to point a web browser (on the same network) to the IP of your server: http://ip-of-server:8080 and log in with:
User: admin Password: adminadmin
You should now see the web interface.
Back at the server’s command line, exit out of qbittorrent-nox instance with
Now, stop impersonating the qbittorrent user to return to our account with sudo access:
Now start the service,
$ sudo systemctl start qbittorrent
Verify it is running:
$ sudo systemctl status qbittorrent
Quit out of the above screen by pressing
Enable it to start up on boot:
$ sudo systemctl enable qbittorrent
and you should see:
Created symlink from /etc/systemd/system/multi-user.target.wants/qbittorrent.service to /etc/systemd/system/qbittorrent.service.
That’s it, we are done!
After the above, systemd should have indexed and invoked our init script so qbittorrent should be running. qBittorrent should now start automatically with reboots.
Disable account login
You may also want to issue the following command to disable login for the account (from SSH) for security reasons. The account will still be usable locally:
$ sudo usermod -s /usr/sbin/nologin qbtuser
This can be reversed if necessary with the command:
$ sudo usermod -s /bin/bash qbtuser
$ sudo systemctl start qbittorrent
$ sudo systemctl stop qbittorrent
$ sudo systemctl status qbittorrent
This should yield something like this:
● qbittorrent.service - qBittorrent Daemon Service Loaded: loaded (/etc/systemd/system/qbittorrent.service; disabled; vendor preset: enabled) Active: active (running) since Wed 2016-02-03 16:02:06 SAST; 6s ago Process: 15469 ExecStart=/usr/bin/qbittorrent-nox -d (code=exited, status=0/SUCCESS) Main PID: 15470 (qbittorrent-nox) CGroup: /system.slice/qbittorrent.service └─15470 /usr/bin/qbittorrent-nox -d
To determine the status of qBittorrent, pay special attention to:
Active: active (running) since Wed 2016-02-03 16:02:06 SAST; 6s ago'
Logging and debugging:
With the advent of systemd replacing upstart, logging also changed. qbittorrent doesn’t have a straightforward logging facility. When it runs it outputs to syslog, but when it doesn’t run, like if the disclaimer hasn’t been answered yet, you won’t see anything in the log files. The best way to see this is to impersonate the qbtuser and run qbittorent-nox to see if the disclaimer comes up again.
Another way of working around how qbittorrent logs/doesn’t log is to modify the init script as a ‘oneshot’ command execution and pipe the output to a file such as
/var/log/qbittorrent.log, but I haven’t tried this yet. Possibly the process identifier will need to be specified as well as the stop command so that status and stop commands also work. This is still a work in progress and I’ll update this guide when I have it working.
You can also view output of qbittorrent with journalctl:
This will show the entire log in a pager that can be scrolled through:
$ sudo journalctl -u qbittorrent.service
This will show the live version of the log file as things are happening:
$ sudo journalctl -f -u qbittorrent.service
Remove the startup script:
$ sudo rm /etc/systemd/system/qbittorrent.service
Remove the qBittorrent package:
$ sudo apt-get remove --purge "qbittorrent*"
Remove log files:
$ sudo rm /var/log/qbittorrent.log
Remove qbtuser’s home folder and config files. If you want to re-install qbittorrent or something you might want to keep this or back it up:
$ sudo rm -R /home/qbtuser
$ sudo userdel qbtuser
(Optional) Service Dependencies
Let’s say that you configured qbittorrent-nox to download files to a directory that is in another drive, for example, mounted on ‘/media/volume’. It’s important that you edit the service created above and add some systemd dependencies to prevent qbittorrent from writing files on a directory that it should not, in case your drive fails to mount or is accidentally unmounted.
After you added the mount point to the
/etc/fstab, it should have a line like this:
UUID=c987355d-0ddf-4dc7-bbbc-bab8989d0690 /media/volume ext4 defaults,nofail 0 0
The ‘nofail’ option prevents the system from stopping the boot process in case the drive can’t mount on startup.
You should edit
/etc/systemd/system/qbittorrent.service to add ‘local-fs.target’ to the line ‘After=network.target’ and add the line ‘BindsTo=media-volume.mount’ to bind the qbittorrent service to the mount point that you want it to write the files. Your service file should look like this:
[Unit] Description=qBittorrent Daemon Service After=network.target local-fs.target BindsTo=media-volume.mount [Service] User=qbtuser Group=qbtuser ExecStart=/usr/bin/qbittorrent-nox TimeoutStopSec=infinity [Install] WantedBy=multi-user.target
The ‘media-volume.mount’ is a systemd unit created dynamically at boot, based on the entries found on
and is used by systemd to mount and manage the status of the respective drive. Systemd.mount reference
It follows a simple logic: if your drive is mounted on ‘/media/volume’, the unit name will be ‘media-volume.mount’, if it’s on ‘/mnt/disk’, the unit will be ‘mnt-disk.mount’.
This way, if the drive can’t mount on boot or if the drive is unmounted after qbittorrent started, it will not allow it to start or force it to stop, preventing from writing when the drive is not ready or present.