Watch Folders

Each queue can watch a folder. Any supported file you put into that folder is added to the queue automatically, and no one needs to click anything. This is handy on servers, with scripts, with shared folders on your network, and with programs such as Sonarr and Radarr, which can save the files they find into a folder ("torrent blackhole").

On a server without a window, a watch folder is an easy way to hand files over to FatRat: copy them in over the network or SSH. See Running on a Server.

What is picked up

• .torrent files
• .metalink and .meta4 files
• .txt files with one link per line. Blank lines and lines starting with # are skipped. The file may be at most 1 MiB.
• .magnet files, which are text files holding a magnet link. They are handled like a .txt file with one line.

File extensions are not case-sensitive. Hidden files and all other kinds of files are ignored. Subfolders are not scanned.

A file is processed once its size and modification time have not changed for 2 seconds, so a file that is still being copied in is not read half-written, as long as the copy doesn't stall for longer than that. Writing the file somewhere else and then moving it into the folder is always safe. A list of links that keeps growing while it is being added may have its first links added twice.

Setting it up

A folder must be given as an absolute path, and two queues cannot watch the same folder. Leave the field empty to turn watching off.

• Desktop: choose Queue → Properties..., then check Add files dropped into a watch folder and enter the folder (or use the browse button).
• Web interface: select the queue and click Queue Properties in the toolbar (or right-click the queue and choose Properties). Enter the folder in the Watch folder field, or use Browse…. See Web Interface.
• Terminal: in fatrat-tui, select the queue and press E to edit it. Enter the folder in the Watch folder field. Ctrl-B browses for a folder. See Terminal Interface.
• REST API: send watchDirectory when creating a queue (POST /queues) or changing one (PATCH /queues/{uuid}). The read-only watchStatus field reports the state.

What happens to the files

New transfers are added to the queue and saved to the queue's Destination directory (Target directory in the web interface, Default directory in the terminal). See Transfers and Queues. They start as soon as the queue allows it; until then they are in the Waiting state.

After a file is processed, it is renamed in the same folder:

• name.ext.added if at least one transfer was created,
• name.ext.failed if nothing could be added.

If a file with that name already exists, .1, .2, and so on is appended. In a list of links, links that no transfer type accepts, or that fail to start, are skipped and logged. The file still counts as added if at least one link worked.

FatRat needs write access to the folder, including the permission to enter it, to be able to rename files. A folder it cannot write to is not watched at all.

Don't use a queue's destination directory as its watch folder: a .torrent that FatRat itself is still downloading there could be picked up half-written.

Network folders

On local disks FatRat is told about new files by the operating system. Network mounts (NFS, SMB, sshfs) often do not report changes made from other machines, so every watch folder is also rescanned every 60 seconds. A file dropped into a network folder may therefore take up to a minute to be noticed.

Problems

Every queue with a watch folder has a status:

• OK - the folder is being watched.
• Missing - the folder does not exist (yet). FatRat keeps checking and starts watching it within a minute of it appearing.
• Not writable - FatRat cannot rename files in the folder, so nothing is picked up. Fix the folder's permissions.
• Duplicate - another queue already watches the same folder, and this queue's setting is ignored.

The desktop dialog shows a warning text. The web interface shows a warning in the queue properties and an icon in the queue list. The terminal interface marks the queue with "!" and shows Watch <folder> (<status>) in the queue info panel.

Everything the watch folders do is written to the log with the sender "Watch folder".