Skip to content

systemd.md

Latest commit

 

History

History
507 lines (360 loc) · 9.61 KB

systemd.md

File metadata and controls

507 lines (360 loc) · 9.61 KB

Systemd Service Setup

Run qBitrr as a systemd service on Linux for automatic startup, restart management, and proper logging.

Prerequisites

  • Linux system with systemd (most modern distributions)
  • qBitrr installed via pip (pip install qBitrr2)
  • Python 3.11 or higher
  • Non-root user account (recommended for security)

Quick Start

# Create qBitrr user
sudo useradd -r -s /bin/bash -d /opt/qbitrr -m qbitrr

# Install qBitrr
sudo -u qbitrr pip install qBitrr2

# Create directories
sudo mkdir -p /opt/qbitrr/{config,logs}
sudo chown -R qbitrr:qbitrr /opt/qbitrr

# Create service file
sudo nano /etc/systemd/system/qbitrr.service

# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable --now qbitrr

Installation Steps

1. Create Dedicated User

Create a dedicated user for running qBitrr (recommended for security):

sudo useradd -r -s /bin/bash -d /opt/qbitrr -m qbitrr

!!! tip "Why a dedicated user?" Running qBitrr as a dedicated user improves security by limiting access to system resources and isolating potential issues.

2. Install qBitrr

Install for the qbitrr user:

sudo -u qbitrr pip install qBitrr2

Or install system-wide:

sudo pip install qBitrr2

3. Create Directory Structure

sudo mkdir -p /opt/qbitrr/config
sudo mkdir -p /opt/qbitrr/logs
sudo chown -R qbitrr:qbitrr /opt/qbitrr

4. Generate Configuration

Run qBitrr once to generate the default configuration:

sudo -u qbitrr QBITRR_OVERRIDES_DATA_PATH=/opt/qbitrr/config qbitrr

Press ++ctrl+c++ to stop, then edit:

sudo nano /opt/qbitrr/config/config.toml

See the First Run Guide for configuration details.

5. Create Systemd Service File

Create the service file:

sudo nano /etc/systemd/system/qbitrr.service

Paste this content:

[Unit]
Description=qBitrr - Radarr/Sonarr/Lidarr Torrent Manager
Documentation=https://feramance.github.io/qBitrr/
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=qbitrr
Group=qbitrr
WorkingDirectory=/opt/qbitrr

# Main process
ExecStart=/usr/bin/python3 -m qBitrr.main

# Environment variables
Environment="QBITRR_OVERRIDES_DATA_PATH=/opt/qbitrr/config"

# Restart policy
Restart=always
RestartSec=5

# Logging
StandardOutput=journal
StandardError=journal
SyslogIdentifier=qbitrr

# Security hardening (optional)
NoNewPrivileges=true
PrivateTmp=true

[Install]
WantedBy=multi-user.target

!!! warning "Adjust Python Path" Find your Python path with which python3 and update ExecStart if needed.

6. Enable and Start Service

# Reload systemd
sudo systemctl daemon-reload

# Enable auto-start on boot
sudo systemctl enable qbitrr

# Start immediately
sudo systemctl start qbitrr

# Check status
sudo systemctl status qbitrr

Managing the Service

Check Status

sudo systemctl status qbitrr

Example output:

● qbitrr.service - qBitrr - Radarr/Sonarr/Lidarr Torrent Manager
     Loaded: loaded (/etc/systemd/system/qbitrr.service; enabled)
     Active: active (running) since Mon 2025-11-25 10:00:00 UTC
   Main PID: 1234 (python3)

View Logs

=== "Real-time"

```bash
sudo journalctl -u qbitrr -f
```

=== "Last 100 lines"

```bash
sudo journalctl -u qbitrr -n 100
```

=== "Since boot"

```bash
sudo journalctl -u qbitrr -b
```

=== "Specific time range"

```bash
sudo journalctl -u qbitrr \
  --since "2025-01-01 00:00:00" \
  --until "2025-01-01 23:59:59"
```

=== "Errors only"

```bash
sudo journalctl -u qbitrr -p err -n 50
```

Start/Stop/Restart

# Start
sudo systemctl start qbitrr

# Stop
sudo systemctl stop qbitrr

# Restart
sudo systemctl restart qbitrr

# Reload config (if supported)
sudo systemctl reload qbitrr

Enable/Disable Auto-Start

# Enable auto-start on boot
sudo systemctl enable qbitrr

# Disable auto-start
sudo systemctl disable qbitrr

# Enable and start in one command
sudo systemctl enable --now qbitrr

Auto-Update Behavior

When qBitrr performs an auto-update or manual update via WebUI:

  1. Process replacement: qBitrr calls os.execv() to replace itself with the new version
  2. PID maintained: The process keeps the same PID
  3. Systemd continues monitoring: No service interruption
  4. Automatic restart: Restart=always ensures service continues

The RestartSec=5 setting adds a 5-second delay between restart attempts to prevent rapid restart loops.

Configuration Options

Custom Config Location

To use a different config location, update the service file:

[Service]
Environment="QBITRR_OVERRIDES_DATA_PATH=/etc/qbitrr"
WorkingDirectory=/etc/qbitrr
ExecStart=/usr/bin/python3 -m qBitrr.main

Then create the directory:

sudo mkdir -p /etc/qbitrr
sudo chown qbitrr:qbitrr /etc/qbitrr

Environment Variables

Add environment variables to the service file:

[Service]
Environment="QBITRR_OVERRIDES_DATA_PATH=/opt/qbitrr/config"
Environment="QBITRR_SETTINGS_CONSOLE_LEVEL=DEBUG"
Environment="TZ=America/New_York"

Resource Limits

Limit CPU and memory usage:

[Service]
# Limit to 2GB RAM
MemoryMax=2G

# Limit to 50% CPU
CPUQuota=50%

# Limit open files
LimitNOFILE=65536

Security Hardening

For enhanced security, add these options to the [Service] section:

[Service]
# Prevent privilege escalation
NoNewPrivileges=true

# Use private /tmp
PrivateTmp=true

# Protect system directories
ProtectSystem=strict
ProtectHome=true

# Only allow writes to specific directories
ReadWritePaths=/opt/qbitrr

# Restrict network access
RestrictAddressFamilies=AF_INET AF_INET6

# Disable other namespaces
ProtectKernelTunables=true
ProtectKernelModules=true
ProtectControlGroups=true

!!! warning "Test Before Enabling" Some hardening options may interfere with qBitrr's operation. Test thoroughly before deploying.

Multiple Instances

Run multiple qBitrr instances for different configurations:

1. Create Service Files

sudo cp /etc/systemd/system/qbitrr.service \
        /etc/systemd/system/qbitrr-movies.service

sudo cp /etc/systemd/system/qbitrr.service \
        /etc/systemd/system/qbitrr-tv.service

2. Modify Each Service

Edit qbitrr-movies.service:

[Service]
User=qbitrr-movies
WorkingDirectory=/opt/qbitrr-movies
Environment="QBITRR_OVERRIDES_DATA_PATH=/opt/qbitrr-movies/config"

Edit qbitrr-tv.service:

[Service]
User=qbitrr-tv
WorkingDirectory=/opt/qbitrr-tv
Environment="QBITRR_OVERRIDES_DATA_PATH=/opt/qbitrr-tv/config"

3. Create Users and Directories

# Movies instance
sudo useradd -r -s /bin/bash -d /opt/qbitrr-movies -m qbitrr-movies
sudo mkdir -p /opt/qbitrr-movies/{config,logs}
sudo chown -R qbitrr-movies:qbitrr-movies /opt/qbitrr-movies

# TV instance
sudo useradd -r -s /bin/bash -d /opt/qbitrr-tv -m qbitrr-tv
sudo mkdir -p /opt/qbitrr-tv/{config,logs}
sudo chown -R qbitrr-tv:qbitrr-tv /opt/qbitrr-tv

4. Enable and Start

sudo systemctl daemon-reload
sudo systemctl enable qbitrr-movies qbitrr-tv
sudo systemctl start qbitrr-movies qbitrr-tv

!!! tip "Different WebUI Ports" Configure different WebUI ports in each instance's config.toml: toml [Settings] WebUIPort = 6969 # movies WebUIPort = 6970 # tv

Troubleshooting

Service Fails to Start

Check status and logs:

sudo systemctl status qbitrr
sudo journalctl -u qbitrr -n 50 --no-pager

Common issues:

Issue Solution
Permission denied sudo chown -R qbitrr:qbitrr /opt/qbitrr
Python not found Update ExecStart path in service file
Config errors Check syntax in config.toml
Port already in use Change WebUIPort in config

Service Restarts Repeatedly

Check for crash logs:

sudo journalctl -u qbitrr -p err -n 100

Temporarily stop to investigate:

sudo systemctl stop qbitrr
sudo -u qbitrr python3 -m qBitrr.main

Update Not Working

Manual update:

sudo -u qbitrr pip install --upgrade qBitrr2
sudo systemctl restart qbitrr

Permission Issues

Fix ownership and permissions:

sudo chown -R qbitrr:qbitrr /opt/qbitrr
sudo chmod -R 755 /opt/qbitrr
sudo chmod 644 /opt/qbitrr/config/*.toml

Can't Connect to WebUI

Check if qBitrr is listening:

sudo netstat -tlnp | grep 6969

Check firewall:

sudo ufw allow 6969/tcp

Complete Service File Example

Here's a production-ready service file with security hardening:

[Unit]
Description=qBitrr - Radarr/Sonarr/Lidarr Torrent Manager
Documentation=https://feramance.github.io/qBitrr/
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=qbitrr
Group=qbitrr
WorkingDirectory=/opt/qbitrr

# Main process
ExecStart=/usr/bin/python3 -m qBitrr.main

# Environment
Environment="QBITRR_OVERRIDES_DATA_PATH=/opt/qbitrr/config"
Environment="TZ=America/New_York"

# Restart policy
Restart=always
RestartSec=5

# Logging
StandardOutput=journal
StandardError=journal
SyslogIdentifier=qbitrr

# Resource limits
MemoryMax=2G
CPUQuota=50%
LimitNOFILE=65536

# Security hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/opt/qbitrr
RestrictAddressFamilies=AF_INET AF_INET6
ProtectKernelTunables=true
ProtectKernelModules=true
ProtectControlGroups=true

[Install]
WantedBy=multi-user.target

Next Steps