Transfers and Queues

A transfer is one download or upload: a file over HTTP or FTP, a torrent, an FTP upload, and so on. Every transfer belongs to a queue. The queue decides where its files go, how fast its transfers may run and how many of them run at once.

Adding transfers

You can add transfers in several ways:

Desktop: Transfer → New transfer (Ctrl+N) opens the New transfer dialog, described below.
Web interface: the New Transfer button. See Web Interface.
Terminal: press N in the transfer list of fatrat-tui. See Terminal Interface.
Drop-box: drag links onto the drop-box window. See Drop-box.
Clipboard monitor: FatRat can pick up links you copy that match a pattern. See Clipboard Monitor.
Watch folders: files saved into a queue's watch folder are added to that queue. See Watch Folders.
Command line: pass links as arguments when you start the desktop app. See Command Line.

The New transfer dialog

Desktop: the dialog asks for the following:

Type: Download or Upload.
URIs (downloads): The links to download, one per line. Add special lets you add local files (such as a .torrent file), the contents of a text file, or the links on the clipboard. Set authentication data asks for a user name and password, which FatRat adds to every link in the dialog that has none of its own.
Files (uploads): The local files to upload. Here Destination is the place to upload to, and Set authentication data adds the user name and password to that address.
Destination: The directory to save into. It starts as the target directory of the chosen queue. If you leave it empty, FatRat saves a download into the queue's target directory, or into your home folder if the queue has none.
Download as / Upload as: The engine that handles the transfer, for example "BitTorrent download" or "CURL HTTP(S)/FTP(S)/SFTP download". Leave it at Auto detect to let FatRat choose from the link.
Queue: The queue that gets the new transfers.
Down speed limit / Up speed limit (KiB/s): Speed limits for the new transfers. 0 means no limit.
Add paused: Adds the transfers in the Paused state. Otherwise they are added as Waiting, and the queue starts them when it has room.
Set advanced options: Shows the engine's own options (see Transfer properties below) before the transfers are added.

Web interface: the New Transfer dialog adds downloads only. It has Queue, URLs (one per line), Local files (e.g. .torrent), Target directory, Download as (empty means "Automatically detect"), Max download speed (KB/s), Max upload speed (KB/s) and Add paused.

Queues

A queue is a list of transfers that share settings. FatRat starts with one queue, "Main queue". You can make more queues, for example one for large downloads that may only run one at a time, and another for small files.

The order of the transfers in a queue matters: when the queue picks which transfers to run, it goes from the top of the list. You can change the order with:

Desktop: Move to top, Move up, Move down and Move to bottom in the Transfer menu.
Web interface: Move to Top ({), Move Up ([), Move Down (]) and Move to Bottom (}) in the transfer menu.
Terminal: M (Move), then T, U, D or B for top, up, down or bottom. [ and ] move the transfer up and down directly.

Creating and editing queues

Desktop: Queue → New queue creates a queue. Queue → Properties... edits the selected one. Double-clicking the speed limits in the status bar also opens the properties.
Web interface: New Queue (Shift+N) and Queue Properties (Shift+E).
Terminal: in the queue list, N (New queue) and E (Edit).

Queue properties

Each entry below is headed with the label in the desktop "Queue properties" dialog. The web interface and the terminal labels follow where they differ.

Name: The queue's name.
Destination directory: Web: Target directory. Terminal: Default directory. Where new downloads in this queue save their files, unless you choose another directory when you add them. The desktop fills in your Downloads folder for a new queue, or your home folder if there is no Downloads folder. The web interface and the terminal start with the field empty. If you leave it empty, downloads that are added without a directory, from any of the front ends or from a watch folder, go to your home folder.
Move transfers after completion: Web: Move to directory after completion. Terminal: Move finished to. When a download completes, its data is moved to this directory. Leave it empty to keep the data where it is. Uploads are never moved.
Add files dropped into a watch folder: Web and terminal: Watch folder. A folder that FatRat watches for .torrent, .metalink, .meta4, .txt and .magnet files to add to this queue. See Watch Folders.
Down speed limit / Up speed limit (KiB/s): Web: Download speed limit (KB/s) and Upload speed limit (KB/s). Terminal: Speed limit down and Speed limit up. The total speed of all transfers in the queue. 0 means no limit. See Speed limits below.
Limit active transfer count: Desktop only. When ticked, the queue runs at most Maximum active download transfers downloads and Maximum active upload transfers uploads at once. When unticked, every waiting transfer runs, and the two maximums and Count as downloads can't be changed.
Maximum active download transfers / Maximum active upload transfers: Web: Max active downloads and Max active uploads. Terminal: Active downloads and Active uploads. Here the number itself sets the limit: 0 means that only Forced active transfers run, and -1 (web interface and terminal) means no limit.
Count as downloads: Web: Count uploads as downloads. Terminal: Upload as download. Uploads count against the download limit, so downloads and uploads share one limit and the upload limit is not used.

A queue made on the desktop has no speed limits and runs at most 1 download and 1 upload at a time. In the web interface and the terminal, a new queue has no speed limits either, and the maximum active downloads and uploads start at -1, which means no limit. A queue saved with 0 runs only Forced active transfers, and everything else stays Waiting.

How a queue decides what runs

Once a second, each queue goes through its transfers from top to bottom. Only transfers that are Waiting or Active take part:

While there is a free place under the queue's active-transfer limit, the transfer becomes Active.
When the limit is reached, the remaining transfers become (or stay) Waiting. This also happens to an Active transfer if you lower the limit, or if you move a waiting transfer above it.

Downloads and uploads have separate limits, unless Count as downloads is ticked. What counts is what the transfer does at the moment: a torrent that has finished downloading and is seeding counts as an upload.

Transfers that are Forced active, Paused, Failed or Completed don't take a place under the limit. Forced active transfers still share the queue's speed limit with the Active ones.

Transfer states

State	Meaning
Waiting	Ready to run. The queue starts it as soon as there is room under its limit.
Active	Running, and counted against the queue's limit.
Forced active	Running regardless of the queue's limit. The terminal shows it as "Forced".
Paused	Stopped by you. The queue does not start it.
Failed	Stopped by an error. The transfer's message or log says why.
Completed	Finished.

Changing the state

Desktop	Web interface	Terminal	What it does
Start (Ctrl+R)	Resume	Resume (R)	Makes a Paused or Failed transfer Waiting, so it runs when the queue has room. A Forced active transfer becomes a normal Active one. A Completed transfer can't be resumed.
Force start (Ctrl+F)	Force Resume	Force resume (F)	Makes the transfer Forced active: it starts at once, even when the queue is at its limit.
Pause (Ctrl+P)	Pause	Pause (P)	Stops the transfer and makes it Paused.

On the desktop, these are in the Transfer menu and on the toolbar. The web interface and the terminal work like the desktop here: Resume acts on each selected transfer according to its state.

Desktop: the Queue menu also has Start all, which makes every Paused or Failed transfer in the queue Waiting, and Pause all, which pauses every transfer in the queue that has not completed. FatRat → Pause all transfers pauses the Waiting, Active and Forced active transfers in every queue. Choose it again to put them back in the state they were in. FatRat forgets those states as soon as any transfer changes to a state other than Paused, for example when you start one, a failed one is retried, or a new one is added from a watch folder, RSS or the clipboard. It also forgets them when FatRat is restarted.

Web interface: the queue menu has Resume All, which makes every Paused or Failed transfer in the queue Waiting, and Stop All, which pauses every transfer in the queue that has not completed.

Failed and completed transfers

What happens next is set on the desktop only, in Settings → Settings..., on the Queue page:

If transfer fails: FatRat retries a failed transfer in two cases. One is when Always retry if the transfer has been working before is ticked (the default) and the transfer had moved data at 1 KiB/s or more during its last run. There is no limit on how many times this happens. The other is when the transfer has been retried fewer than the number in Retry … times (default 0). Set that number to retry a transfer that never got going, and untick the check box if you want the number to be a limit for every transfer.
When transfer completes: Remove from the queue (off by default).

To remove completed transfers by hand, use Queue → Remove completed on the desktop, or Delete Completed (C) in the web interface.

Transfer properties

Open the properties of a transfer with:

Desktop: Transfer → Properties... (Ctrl+.).
Web interface: Properties (E) in the transfer menu.
Terminal: E (Edit).

Every transfer has these properties:

Destination

The directory a download saves into. For an upload the field is called Source, and it is the file being uploaded. If you change a download's destination, FatRat moves its data there.

Speed limits

Desktop: Down speed limit (KiB/s) and Up speed limit (KiB/s). Web: Max download speed (KB/s) and Max upload speed (KB/s). 0 means no limit.

Comment

Free text for your own notes.

Command on completion

Desktop: "Run the following command when the transfer completes", on the Actions page. Web: Run on completion. In the command, %N is the transfer's name, %T its type, %D its directory (for an upload, the directory of the source file) and %P the file path. The command runs through /bin/sh, and the values are put in as they are, so put quotes around them in case a name contains spaces, for example:

cp -r "%P" /mnt/backup/

The desktop dialog has these on its Generic options, Comment and Actions pages. A Details page holds the engine's own options. The web interface shows the engine's options under Options.

Engine options

What the engine options offer depends on the kind of transfer. For example:

HTTP and FTP downloads: the Target file name. The desktop also lists the transfer's URLs: you can add mirrors, and edit each link's HTTP referrer, FTP connection mode, user name and password, proxy server and bind IP address.
Torrents: Seeding limits: seed up to a ratio, seed until a given amount (in MB) has been uploaded, and Use super seeding. The desktop also has Files to download, URL seeds and Trackers. See BitTorrent Support.
FTP uploads: the target URL, FTP connection mode, user name and password, proxy server and bind IP address.

Speed limits

You can limit speed in two places:

Per queue: a limit for all transfers in the queue together. On the desktop, the status bar shows the selected queue's limits; right-click them to pick a new limit quickly. In the terminal, press L in the queue list.
Per transfer: a limit for one transfer, set when you add it or in its properties. In the terminal, press L in the transfer list.

A queue's limit is shared between its running transfers. FatRat starts by splitting the limit equally, then adjusts the shares every second so that bandwidth one transfer doesn't use can go to the others. When a transfer has its own limit and that limit is lower than its share, the transfer's own limit applies.

There is no limit across all queues. The Line speed (for the speed graphs) setting on the Network page of Settings → Settings... (desktop) is not a speed limit: it only sets the scale of the speed graphs and bars. To change queue limits at set times, use the Scheduler.