Running on a Server

FatRat can run without any window, on a machine you reach over the network or SSH. You then control it with the web interface in a browser, with fatrat-tui in a terminal, or with scripts through the REST API.

Installing

On Ubuntu, FatRat comes from its own signed apt repository. For a server, install the headless package:

sudo apt install fatrat-nogui

The fatrat-nogui package contains the headless fatrat-nogui program and fatrat-tui. Only this package has fatrat-tui. It pulls in fatrat-common, which holds the web interface, fatrat-conf and the systemd units. The commands that add the repository are on fatrat.dolezel.info.

On macOS, Homebrew builds the desktop application, which also runs headless with fatrat --nogui:

brew install --HEAD lubosd/fatrat/fatrat

See the README for the details, for Docker, and for building from source.

Starting FatRat without a window

There are two programs:

• fatrat-nogui is a build without any desktop code. It never opens a window, so you don't need --nogui.
• fatrat is the desktop build. Start it with --nogui (or -n) to run it without a window.

The options for a server are:

-d, --daemon

Go to the background and detach from the terminal. Implies --nogui.

-p, --pidfile file

Write the process ID to file. With --daemon, it is the ID of the background process. FatRat removes the file when it exits normally.

-u, --user user[:group]

Switch to this user and group. Start FatRat as root to use it. If you leave out the group, FatRat uses the primary group of the user. It also replaces the supplementary groups with those of the user. The process ID file is handed over to the user, so FatRat can remove it on exit. FatRat sets HOME and the working directory to the user's home directory, so it uses that user's settings and data. It does not reset other variables such as XDG_CONFIG_HOME or XDG_RUNTIME_DIR, so don't pass root's environment on (for example with sudo -E).

--syslog

Also send FatRat's log messages to syslog, with the tag fatrat.

-c, --config file

Read and write the settings in file instead of the usual settings file.

--rest-socket path

Also serve the REST API on a unix socket (see below).

The safe ways to run FatRat as another user are the systemd service (see below), or starting it as that user in the first place. For example, to run it in the background as yourself:

fatrat-nogui --daemon --pidfile ~/fatrat.pid

FatRat stops cleanly and saves its queues when it gets SIGTERM or SIGINT:

kill $(cat ~/fatrat.pid)

Run only one FatRat per user at a time. Two would use the same settings and queues. For example, don't start one by hand as the fatrat user while the fatrat service is running.

If you have to start FatRat as root, --user is the fallback:

sudo fatrat-nogui --daemon --user fatrat --pidfile /run/fatrat.pid

fatrat --help lists every option. See also Command Line.

Running as a systemd service

The Ubuntu packages ship two systemd units, both named fatrat.service. Neither is enabled when you install the package. Both start fatrat --nogui if the fatrat package is installed, and fatrat-nogui otherwise.

System service

sudo systemctl enable --now fatrat

It runs as the user and group fatrat, which the package creates, with its home in /var/lib/fatrat. The web interface is off until you turn it on (see below). The service also serves the REST API on the unix socket /run/fatrat/rest.sock, so you can use the terminal client on the server without a password:

sudo -u fatrat fatrat-tui --socket /run/fatrat/rest.sock

FatRat can only write to directories the fatrat user may write to. Give it write access to the directories you download into. The service also keeps /usr, /boot and /etc read-only. To download into a directory under one of them, run sudo systemctl edit fatrat and add the directory to ReadWritePaths= in the [Service] section.

User service

systemctl --user enable --now fatrat

It runs as you, with your normal settings and transfers. It serves the REST API on $XDG_RUNTIME_DIR/fatrat/rest.sock, where fatrat-tui finds it without any options. If the desktop app is already running in your session, the service exits without starting a second FatRat. To keep it running after you log out:

sudo loginctl enable-linger $USER

Turning on the web interface

The web interface is off by default. Its settings are in the [remote] section of the settings file:

On Linux and BSD, the settings file is ~/.config/Dolezel/fatrat.conf in the home directory of the user FatRat runs as, or $XDG_CONFIG_HOME/Dolezel/fatrat.conf if that variable is set. For the system service, that is /var/lib/fatrat/.config/Dolezel/fatrat.conf. With -c, it is the file you gave.

On macOS, FatRat keeps its settings in the system's preferences store, which you can't edit as a text file. For a headless FatRat there, start it with -c file and write the keys into that file in the format shown below.

Always set a password of your own. The default password, fatrat, is the same for everyone.

On Linux and BSD, stop FatRat, then set the keys with fatrat-conf, as the user FatRat runs as:

fatrat-conf -w remote/enable=true remote/port=2233 remote/password=SECRET

For the system service:

sudo systemctl stop fatrat
sudo -u fatrat -H fatrat-conf -w remote/enable=true remote/password=SECRET
sudo systemctl start fatrat

fatrat-conf stores the password as you type it, in plain text, so keep the settings file readable only by its owner. To read a value back, run fatrat-conf remote/port. A password typed on the command line also ends up in your shell history.

You can also edit the file with a text editor while FatRat is stopped. On Linux and BSD, fatrat-conf is the safer way, because it quotes the values for you. When you write a value by hand, put it in double quotes if it contains , ; " or \, and write \" for a quote and \\ for a backslash inside. Quoting is the portable way: an unquoted comma in the password is read as part of it, but a ; cuts the rest of an unquoted value off. If FatRat cannot read the password value as text, it refuses every login:

[remote]
enable=true
port=2233
password="SECRET"

fatrat-conf writes to the usual settings file; if you run FatRat with -c, give fatrat-conf the same -c file option, for example fatrat-conf -c /path/to/file -w remote/enable=true.

Once FatRat runs again, open http://server:port/ in a browser, for example http://myserver:2233/. The browser asks for a user name and a password: the user name can be anything, the password is remote/password. See Web Interface.

When FatRat is already running, you can change these settings on the Web Interface page of the settings, in the desktop app, the web interface or fatrat-tui. FatRat applies them without a restart.

FatRat listens on the port on all IPv4 addresses of the machine. There is no setting to limit it to one address, so use a firewall if the port must not be reachable from everywhere.

HTTPS

Without HTTPS, the password and everything else go over the network unencrypted. For HTTPS, FatRat needs one PEM file that holds the private key (without a passphrase) followed by the certificate. To make a self-signed certificate valid for ten years, run this in the directory where you want to keep it, putting your server's name after CN=:

openssl req -x509 -newkey rsa:4096 -nodes -days 3650 -subj "/CN=myserver" -keyout key.pem -out cert.pem
cat key.pem cert.pem > fatrat.pem
rm key.pem cert.pem
chmod 600 fatrat.pem

A certificate you already have from a certificate authority works too: put its key and its certificate (with any intermediate certificates after it) into one file the same way.

Then point FatRat at the file and restart it (on macOS, put the two keys into your -c file instead):

fatrat-conf -w remote/ssl=true remote/ssl_pem=/full/path/to/fatrat.pem

The file must be readable by the user FatRat runs as. Open https://server:port/. With a self-signed certificate, the browser warns you the first time. Plain http:// no longer works on that port.

If the PEM file doesn't exist, FatRat logs "SSL key file not found, disabling HTTPS" and serves plain HTTP instead. If the file exists but is not a valid PEM file with both the private key and the certificate, FatRat does not listen at all, and logs an error that names the file. It logs an error too if it cannot listen on the port, for example because another program already uses it. Look at the log in the web interface or fatrat-tui, or in syslog if you use --syslog.

The Web Interface settings page in the desktop app, the web interface and fatrat-tui can also generate a self-signed certificate. This needs openssl and sed on the server. The file is saved as ~/.local/share/fatrat/data/fatrat-webui.pem, readable only by its owner.

A unix socket for local scripts

With --rest-socket path, FatRat also serves the REST API on a unix socket:

fatrat-nogui --rest-socket "$XDG_RUNTIME_DIR/fatrat/rest.sock"

The socket asks for no password. It is created with mode 0600, so only the user FatRat runs as can use it. It works whether the web interface is on or off. For example:

curl --unix-socket "$XDG_RUNTIME_DIR/fatrat/rest.sock" http://localhost/api/v1/queues

Over the network, the same API is at /api/v1/ on the web interface's port, with the same password:

curl -u x http://myserver:2233/api/v1/queues

With -u x and no password, curl asks for it, so it does not show up in your shell history or in the process list.

See REST API for what it can do.

Handing files to the server

• Web interface: add links and upload .torrent files in the browser.
• Watch folders: give a queue a folder to watch. Copy .torrent files or lists of links into it, for example over SFTP or a shared folder, and FatRat adds them. See Watch Folders.
• REST API: add transfers from scripts, over the network or the unix socket. See REST API.

Where things are

~ is the home directory of the user FatRat runs as (/var/lib/fatrat for the system service). The data directory is always under ~/.local/share, even if XDG_DATA_HOME is set. With the systemd units, FatRat's own diagnostic output on the console goes to the journal: journalctl -u fatrat, or journalctl --user -u fatrat for the user service.

Connecting with fatrat-tui

On the server itself, fatrat-tui uses the unix socket (see the systemd sections above). From another machine, give it the address of the web interface. It asks for the password:

fatrat-tui --url http://myserver:2233

To give it the password without typing, put it in a file that only you can read. fatrat-tui refuses a password file that others can read:

chmod 600 ~/.fatrat-pw
fatrat-tui --url https://myserver:2233 --password-file ~/.fatrat-pw

Or set the FATRAT_PASSWORD environment variable.

On the server, against the system service, add --no-start so that fatrat-tui fails instead of starting a FatRat of its own when the service is not running:

sudo -u fatrat fatrat-tui --socket /run/fatrat/rest.sock --no-start

See Terminal Interface.