Skip to main content

Daemon Mode

Daemon Mode lets you harness the full power of cross-seed by continuously running and enabling the following features:

  • instantly searching for cross-seeds for finished downloads
  • watching for new releases:
    • scanning RSS feeds periodically (rssCadence) for matching content
    • listening for new release announces and snatching them if you already have the data (e.g. autobrr -> announce API endpoint)
  • Running batch searches on your full collection of torrents periodically (searchCadence)
tip

In theory, after you run a full-collection search for the first time, the first two features should be able to find all cross-seeds as soon as possible. However there are applications for the third feature as well. If improvements in the matching algorithm are made to cross-seed, or your daemon is down for an amount of time, running searches very infrequently will find cross-seeds which fell through the cracks.

In this doc, we'll go through strategies to run the daemon continuously and start automatically on reboot, ways to trigger searches for torrents that just finished downloading, and ways to watch for new releases.

danger

cross-seed has an apiAuth option to require authorization on requests, but we still recommend that you do not expose its port to untrusted networks (such as the Internet).

Running the daemon continuously​

The easiest way to run the daemon is just to leave a terminal open after running the following command:

cross-seed daemon

However, that's not very sustainable.

  • If you run cross-seed on a server that you use ssh to log into, then cross-seed will stop whenever your ssh session closes.
  • If the server restarts, then you'll have to start cross-seed manually.

Below are a few ways you can set up cross-seed daemon to run on its own:

Docker​

You can use Docker Compose. Create or open your existing docker-compose.yml file and add the cross-seed service:

version: "2.1"
services:
    cross-seed:
        image: ghcr.io/cross-seed/cross-seed
        container_name: cross-seed
        user: 1000:1000 # optional but recommended
        ports:
            - "2468:2468" # you'll need this if your torrent client runs outside of Docker
        volumes:
            - /path/to/config/folder:/config
            - /path/to/torrent_dir:/torrents:ro # your torrent clients .torrent cache, can and should be mounted read-only (e.g. qbit: `BT_Backup` | deluge: `state` | transmission: `transmission/torrents` | rtorrent: session dir from `.rtorrent.rc`)
            - /path/to/output/folder:/cross-seeds
            - /path/to/torrent/data:/data # OPTIONAL!!! this is location of your data (used for data-based searches or linking)
              # will need to mirror your torrent client's path (like Arr's do)
        command: daemon # this enables the daemon, change to search to specifically run a search ONLY
        restart: unless-stopped

After that, you can use the following commands to control it:

docker-compose pull # Update the container to the latest version of cross-seed
docker-compose up -d # Create/start the container
docker start cross-seed # Start the daemon
docker stop cross-seed # Stop the daemon
docker restart cross-seed # Restart the daemon
docker logs cross-seed # view the logs

Unraid​

If you are running cross-seed on Unraid you should have installed the "Community App" from ambipro's repository, this is our official container.

Be default, the container runs in daemon mode and no changes are needed.

We recommend you head over to the Unraid Tutorial for specifics and documentation for the container.

systemd (Linux)​

If you want to use systemd to run cross-seed daemon continuously, you can create a unit file in /etc/systemd/system.

touch /etc/systemd/system/cross-seed.service

Open the file in your favorite editor, and paste the following code in. You'll want to customize the following variables and ensure proper permissions are set to allow this user/group to read/write/execute appropriately:

  • {user}: your user, or another user if you want to create a separate user for cross-seed
  • {group}: your group, or another group if you want to create a separate group for cross-seed
  • /path/to/node: run the command which node in your terminal, then paste the output here.
[Unit]
Description=cross-seed daemon
[Service]
User={user}
Group={group}
Restart=always
Type=simple
ExecStart=cross-seed daemon
[Install]
WantedBy=multi-user.target

After installing the unit file, you can use these commands to control the daemon:

sudo systemctl daemon-reload # tell systemd to reindex to discover the unit file you just created
sudo systemctl enable cross-seed # enable it to run on restart
sudo systemctl start cross-seed # start the service
sudo systemctl stop cross-seed # stop the service
sudo systemctl restart cross-seed # restart the service
sudo journalctl -u cross-seed # view the logs

screen​

screen is a terminal multiplexer.

A Terminal multiplexer is a program that can be used to multiplex login sessions inside the Terminal. This allows users to have multiple sessions inside a single Terminal window. One of the important features of the Terminal multiplexer is that users can attach and detach these sessions.

Source: https://linuxhint.com/tmux_vs_screen/

Running a long-lived cross-seed daemon process in screen is very easy.

screen -S cross-seed -d -m cross-seed daemon

The above command will start a screen instance named cross-seed in detached mode, running the cross-seed daemon command at launch.

To attach to the screen, run the following command:

screen -r cross-seed

Once attached, you can detach with ctrl-A, D.

Set up automatic searches for finished downloads​

The most powerful feature of Daemon Mode is the ability to search for cross-seeds as soon as a torrent finishes downloading. However, it requires some manual setup.

info

If you plan on using the path webhook API call, you will need to set up data-based matching in your config file.

Step 1: Find your API key​

If you have not defined your apiKey explicitly, cross-seed will generate a key for you automatically. You will need to supply an API key with your curl commands. API keys can be included with your requests in one of two ways:

  • an X-Api-Key HTTP header
  • an apikey query param

In this doc we will use the query param version.

Docker

Start by shelling into your container:

docker exec -it cross-seed sh

You can find your API key with the following command:

cross-seed api-key

In the rest of this doc, we will refer to this as YOUR_API_KEY.

rTorrent​

For rTorrent, you'll have to edit your .rtorrent.rc file.

  1. cd to the directory where .rtorrent.rc lives.

  2. Create a file called rtorrent-cross-seed.sh. It should contain the following contents:

    #!/bin/sh
    curl -XPOST http://localhost:2468/api/webhook?apikey=YOUR_API_KEY --data-urlencode "infoHash=$2"
    # curl -XPOST http://localhost:2468/api/webhook?apikey=YOUR_API_KEY --data-urlencode "path=$3"
    Docker

    You can use http://cross-seed:2468 instead of http://localhost:2468 with Docker networks. localhost will not work for Docker. You will need to use your host's IP (e.g. 192.x or 10.x) if not using custom Docker networks.

    tip

    You will need to pick a method of search, infoHash is recommended - but requires your session directory from .rtorrent.rc to be mounted (Docker) and set to torrentDir in the config.

  3. Uncomment/Comment the appropriate lines to decide how you wish to use search.

    • The hashtag/pound-sign # is used to "comment" the line - commented lines will not be executed.

  4. Run the following command (this will give rTorrent permission to execute your script):

    chmod +x rtorrent-cross-seed.sh

  5. Run the following commands (this will add variables and tell rTorrent to execute your script):

    echo 'method.insert=d.data_path,simple,"if=(d.is_multi_file),(cat,(d.directory),/),(cat,(d.directory),/,(d.name))"' >> .rtorrent.rc
    echo 'method.set_key=event.download.finished,cross_seed,"execute={'`pwd`/rtorrent-cross-seed.sh',$d.name=,$d.hash=,$d.data_path=}"' >> .rtorrent.rc

  6. Restart rTorrent

qBittorrent​

  1. In the qBittorrent Web UI, navigate to Tools > Options > Downloads.

  2. Check the Run external program on torrent completion box and enter one of the following in the box:

    tip

    You will need to pick a method of search, infoHash is recommended - but requires the BT_Backup folder from qBittorrent to be mounted (Docker) and/or set to torrentDir in the config or it will not function properly.

    Search/CriteriaCommand
    InfoHashcurl -XPOST http://localhost:2468/api/webhook?apikey=YOUR_API_KEY --data-urlencode "infoHash=%I"
    Data (Path)curl -XPOST http://localhost:2468/api/webhook?apikey=YOUR_API_KEY --data-urlencode "path=%F"
Docker

You can use http://cross-seed:2468 instead of http://localhost:2468 with Docker networks. localhost will not work for Docker. You will need to use your host's IP (e.g. 192.x or 10.x) if not using custom Docker networks.

  1. Click "Save".
tip

If you are already using the Run external program on torrent completion box, you should create a shell script with your preferred commands and parameters.

Multiple Commands​

If you're already using the following in the Run external program on torrent completion box

<curl command> %N

You can add infoHash searching using the following script:

    #!/bin/bash
    oldcommand ${1}
    curl -XPOST http://localhost:2468/api/webhook?apikey=YOUR_API_KEY --data-urlencode "infoHash=${2}"

Then add this in qBittorrent's settings to execute the script:

/bin/bash ./qBittorrent/yourscriptname.sh "%N" "%I"
info

You may need to adjust the variables above that qBittorrent sends to the script.

Transmission​

  1. cd to the directory where settings.json lives.

  2. Create a file called transmission-cross-seed.sh. It should contain the following contents:

    #!/bin/sh
    curl -XPOST http://localhost:2468/api/webhook?apikey=YOUR_API_KEY --data-urlencode "infoHash=$TR_TORRENT_HASH"
    Docker

    You can use http://cross-seed:2468 instead of http://localhost:2468 with Docker networks. localhost will not work for Docker. You will need to use your host's IP (e.g. 192.x or 10.x) if not using custom Docker networks.

    tip

    cross-seed requires your torrents directory from /.config/transmission be mounted (Docker) and/or set to torrentDir in the config or it will not function properly.

  3. Run the following command (this will give Transmission permission to execute your script):

    chmod +x transmission-cross-seed.sh

  4. In the settings of Transmission set it to call the script when download completes:

    sh ./transmission-cross-seed.sh

Deluge​

  1. Create a file called deluge-cross-seed.sh, it should contain the following:

    #!/bin/bash
    torrentid=$1
    torrentname=$2
    torrentpath=$3
    curl -XPOST http://localhost:2468/api/webhook?apikey=YOUR_API_KEY --data-urlencode "infoHash=$torrentid"
    # curl -XPOST http://localhost:2468/api/webhook?apikey=YOUR_API_KEY --data-urlencode "path=$torrentpath/$torrentname"
    Docker

    You can use http://cross-seed:2468 instead of http://localhost:2468 with Docker networks. localhost will not work for Docker. You will need to use your host's IP (e.g. 192.x or 10.x) if not using custom Docker networks.

    tip

    You will need to pick a method of search, infoHash is recommended - but requires the state folder from Deluge to be mounted (Docker) and/or set to torrentDir in the config or it will not function properly.

  2. Uncomment/Comment the appropriate lines to decide how you wish to use search.

    • The hastag/pound-sign # is used to "comment" the line - commented lines will not be executed.

  3. Run the following command (this will give Deluge permission to execute your script):

    chmod +x deluge-cross-seed.sh

  4. In the settings of Deluge:

    • Enable the Execute plugin
    • Under Add Command select event of Torrent Complete and input the Command: /path/to/deluge-cross-seed.sh
    • Press Add and Apply
    • Restart your Deluge client/daemon (this is required to hook torrent completion calls)

Set up RSS​

Setting up RSS is very easy. Just open your config file, and set the rssCadence option. I recommend 10 minutes:

rssCadence: "10 minutes",

Set up periodic searches​

Setting up periodic searches is very easy. Just open your config file, and set the searchCadence option. I recommend at least 26 weeks (biannual) for FULL searches, however, you can schedule smaller searches more often with further configuration:

searchCadence: "1 week",
caution

New (fresh) instances of cross-seed will often take time to even out the searching performed during a searchCadence. This is unavoidable, and the best way to mitigate any negative effects is to utilize searchLimit somewhat aggressively after the initial "full-search" is performed.

Combining searchCadence with excludeRecentSearch and excludeOlder - and even searchLimit will result in a more frequent and smoother search load. This results in searching with the following criteria applied:

  • excludeRecentSearch will exclude any torrents searched for from the current moment back the specified time.

  • excludeOlder will exclude any torrents that were first discovered and indexed in cross-seed a longer time ago than the specified time.

searchCadence: "1 day",
excludeRecentSearch: "3 days",
excludeOlder: "2 weeks",

This will search daily for any torrents that cross-seed first searched less than 2 weeks ago that have not been searched in the last 3 days.

For an even longer duration of searching with more spread out searching behavior, something like the following can be used.

searchCadence: "1 day",
excludeRecentSearch: "90 days",
excludeOlder: "1 year",
tip

If your cross-seed runs continuously with an rssCadence or autobrr integration, consider reducing the frequency of, or eliminating, searching via searchCadence. RSS/announce is capable of catching all releases if ran 24/7.