ruTorrent

Feature-rich PHP web interface for rTorrent

ruTorrent is a powerful PHP-based web frontend for the rTorrent BitTorrent client. It provides a familiar µTorrent-like interface with extensive plugin support, file management, RSS feeds, and real-time monitoring. QuickBox Pro installs ruTorrent once at /srv/rutorrent with QuickBox-curated plugins and custom themes, and gives each account its own SCGI socket configuration.

Installation

If the account does not have rTorrent yet, ruTorrent installs it for that account first as its backend (the latest available version while the server has no rTorrent, otherwise the version the server already runs). If that rTorrent install fails, the ruTorrent install stops.

Install from the Dashboard

Open App Dashboard → Package Management (/dashboard?mode=packages), find ruTorrent in the catalog (browse Download Clients or search), and click Install. The dashboard installs the latest stable release, streams the install log live, and ruTorrent appears in your Application Control panel when it finishes. Reinstall and Remove are in the same Package Management panel. To update, use the amber Update badge on the ruTorrent row in the App Dashboard.

ruTorrent follows rTorrent, so the rTorrent rules decide who can install it. If you are a regular user and the server does not have rTorrent yet, the button reads Request install: an administrator approves the request with the rTorrent version they pick, and the install then sets up rTorrent for your account first and ruTorrent after it. Once rTorrent is on the server, you install ruTorrent directly, and rTorrent uses the server’s version. You never choose a version. See Install requests.

What you see and can manage is gated by your account: admins manage any user’s apps; regular users manage their own. For the full package flow see App Management.

Install from the CLI (automation)

The CLI runs the same install and is suited to automation and scripting. -u names the account being set up. It also exposes the edge/beta release via --beta (the Dashboard installs the stable release):

qb install rutorrent -u username

CLI Commands

Per-account setup

The application itself is shared: one copy at /srv/rutorrent with one set of plugins, the theme, and a PHP-FPM pool. Each account that installs ruTorrent adds only its own configuration in /srv/rutorrent/conf/users/username/ and its own profile data in /srv/rutorrent/share/users/username/.

In the dashboard, a user whose group allows ruTorrent installs it for their own account, provided the group also allows rTorrent or the account already has it. Updating it, and reinstalling or removing it when theirs is the last account using it, are administrator actions. See rTorrent for the same rules on the rTorrent side.

Managing Plugins (Server-Wide)

ruTorrent runs as a single global web instance, so its plugins are shared. Installing or removing a plugin changes ruTorrent for every user on the server, not just your own account. QuickBox Pro lets an administrator manage that shared plugin set from the dashboard or the CLI.

Manage from the Dashboard

Open the App Dashboard and stay on the Application Control tab (not Package Management, which is for installing and removing packages). Find the ruTorrent row and expand it, then in its Operations section click Plugins to open the plugin manager:

• Search the plugin list, then toggle a plugin on to install it or off to remove it, server-wide.
• Removing a plugin asks for confirmation in place, because it affects every user.
• Core plugins — the ones ruTorrent needs to load — are marked with a Core badge and cannot be removed.
• Any system dependencies a plugin relies on (for example the tools behind the screenshots or spectrogram plugins) are installed automatically.
• A success message confirms each change, and the plugin is available to all users immediately.

This control is admin-only. The sysop can grant or revoke it per administrator from User Management → User Admin: expand the administrator’s row and, in the App Management section, set the ruTorrent plugins permission (“Manage ruTorrent plugins (install/remove server-wide)”) to Allow or Deny. Access is gated by who you are, not by which surface you use.

Manage from the CLI

The CLI performs the same server-wide install and remove, one plugin per command:

# Install a plugin server-wide
qb manage software -o rutorrent -o install -rup screenshots
 
# Remove a plugin server-wide
qb manage software -o rutorrent -o remove -rup screenshots

Available Plugins

Installable plugins come from the server’s built-in ruTorrent plugin store. The core plugins that ruTorrent needs to function — httprpc, _getdir, _noty, _noty2, _task, theme, data, edit, source, datadir, diskspace, and filemanager — are always present and cannot be removed. Everything else can be installed or removed as needed.

Accessing ruTorrent

After installation, access ruTorrent at:

Login credentials:

• Username: Your QuickBox username
• Password: Your QuickBox password (htpasswd authentication)

Initial Configuration

1. SCGI Socket Connection

QuickBox automatically configures ruTorrent to connect to your rTorrent instance:

• Socket: /var/run/username/.rtorrent.sock
• Connection method: Unix socket SCGI
• Per-user isolation: Each user has their own socket and configuration

2. Enable Plugins

ruTorrent comes with several plugins pre-installed:

Core Plugins:

• diskspace - Monitor disk usage and available space
• filemanager - Browse, move, rename, and delete files
• filemanager-share - Share files via direct links
• _cloudflare - Cloudflare integration support
• _task - Background task management

Enable/Disable Plugins:

1. Navigate to Settings → Plugins in ruTorrent
2. Check/uncheck plugins to enable/disable them
3. Settings are saved per-user automatically

3. Theme Customization

QuickBox Pro uses the club-QuickBox theme by default:

• Integrated with QuickBox dashboard design
• Dark theme optimized for extended use
• Custom color scheme matching QuickBox branding

Change themes via Settings → General → Theme

Updating the theme

The club-QuickBox theme is published as tagged releases, and QuickBox Pro installs the newest one. A normal ruTorrent update also brings the theme to its latest release. When a newer release is out, ruTorrent tells you in three places:

• An Update pill with the new version number, next to Help in the top bar.
• A one-time notice with What’s new and, for admins, Update buttons.
• A Theme badge on the ruTorrent row of the App Dashboard, shown to admins only.

To update from the dashboard, open the App Dashboard, find the Theme badge on the ruTorrent row and click Update theme. Or open the Update pill in ruTorrent, then press Update now in the What’s new window. Inside ruTorrent, the page reloads when the update finishes. The theme is shared, so the update applies to every ruTorrent user.

To update from the CLI, run this as an admin:

qb update rutorrent -u username --theme

This changes only the theme and leaves ruTorrent, your plugins and your settings alone. If the update does not finish, the theme you already have stays in place.

Service Management

ruTorrent runs as a PHP application served by nginx and PHP-FPM. It communicates with rTorrent via SCGI sockets.

# Check PHP-FPM status
systemctl status php*-fpm
 
# Check nginx status
systemctl status nginx
 
# Restart services
systemctl restart nginx php*-fpm
 
# Check rTorrent status (backend)
systemctl status rtorrent@username

ruTorrent runs in its own PHP-FPM pool, /etc/php/{version}/fpm/pool.d/rutorrent.conf, on the PHP version it runs on ({version} is that PHP version, so the service is php{version}-fpm). A new install uses the newest PHP version your package source offers within the 8.1 to 8.4 range ruTorrent supports. An existing install on an older PHP is moved up to the newest one automatically when you update QuickBox or run qb fix php; the new pool is checked before the old one is removed, and ruTorrent stays where it was if anything fails. Install and update bring that PHP version up to its security floor, and qb fix php --security --check shows where it stands. If ruTorrent returns 502 errors, qb fix php repairs its pool (see Fix PHP).

Several ruTorrent plugins run the php command, so on a server with the v4 dashboard a QuickBox update points php at the PHP version ruTorrent runs on.

Troubleshooting

ruTorrent Cannot Connect to rTorrent

Plugins Not Working

# Check plugin permissions
ls -la /srv/rutorrent/plugins/
 
# Fix permissions
chown -R www-data:www-data /srv/rutorrent
 
# Restart PHP-FPM
systemctl restart php*-fpm

File Manager Permission Issues

# Fix file permissions for user's torrent directory
qb fix permissions -u username
 
# Ensure www-data can access user files
chmod 755 /home/username
chmod 755 /home/username/torrents

UI Not Loading / Blank Page

# Check PHP-FPM logs
journalctl -u php*-fpm -f
 
# Check nginx logs
tail -f /var/log/nginx/error.log
 
# Clear browser cache and reload
# Check for JavaScript errors in browser console

Best Practices

Related Applications

Additional Resources