SABnzbd: Usenet Download Manager
Automated Usenet downloading. Integration with *arr stack and post-processing.
SABnzbd is a powerful, open-source binary newsreader designed to automate downloading from Usenet. With multi-connection support, intelligent queue management, and deep integration with automation tools like Sonarr and Radarr, SABnzbd is the go-to solution for Usenet-based media downloading.
What is SABnzbd?
SABnzbd is a specialized download client that processes NZB files from Usenet, automatically handles repair and extraction, and seamlessly integrates with the arr stack for complete media automation.
Key Features
High-Speed Downloads:
- Multi-connection Usenet downloading
- SSL/TLS encryption support
- Bandwidth throttling and scheduling
- Multiple server support with priority
- Automatic server failover
Automation:
- Automatic par2 repair
- Automatic archive extraction
- Category-based post-processing
- Script execution on completion
- RSS feed monitoring for automation
Integration:
- Native arr stack support
- API for external control
- Notification systems (email, Discord, etc.)
- Web-based interface
- Mobile-friendly design
Quality Control:
- Duplicate detection
- Automated cleanup
- Password detection
- Sample file removal
- Virus scanning integration
Why Choose SABnzbd?
Performance:
- Saturate your connection with multiple Usenet servers
- Efficient resource usage
- Parallel downloading and processing
- Smart cache management
Reliability:
- Automatic retry on failed downloads
- Server health monitoring
- Orphaned job cleanup
- Database corruption recovery
Flexibility:
- Extensive configuration options
- Custom scripts for advanced workflows
- Category-based automation
- Priority queue management
Prerequisites
Before starting, ensure you have:
- Docker and Docker Compose installed
- Usenet provider account with server details
- Usenet indexer accounts for NZB files
- At least 2GB RAM available
- Storage for downloads and incomplete files
- Basic understanding of Usenet concepts
Understanding Usenet
Usenet is a distributed discussion system predating the modern web:
Usenet Workflow:
1. Content posted to Usenet newsgroups
2. Indexers catalog available content
3. You search indexer for content
4. Indexer provides NZB file (like a .torrent)
5. SABnzbd downloads articles from Usenet servers
6. Automatic repair with par2 files
7. Automatic extraction of archives
8. File moved to final destination Components:
- Usenet Provider: Server access (Newshosting, UsenetServer, etc.)
- Indexer: Search engine for Usenet (NZBGeek, DrunkenSlug, etc.)
- Download Client: SABnzbd (this guide)
- Automation: Sonarr, Radarr, etc.
Directory Structure
Create organized directories:
# Create SABnzbd config and download directories
mkdir -p /opt/sabnzbd/{config,downloads/incomplete,downloads/complete}
# Create category-specific directories
mkdir -p /opt/sabnzbd/downloads/complete/{movies,tv,music,books}
# Set ownership
sudo chown -R $USER:$USER /opt/sabnzbd Directory Explanation:
/opt/sabnzbd/config: Application configuration and database/opt/sabnzbd/downloads/incomplete: Active downloads and repair/opt/sabnzbd/downloads/complete: Finished downloads by category
Docker Compose Configuration
Create /opt/sabnzbd/docker-compose.yml:
version: '3.8'
services:
sabnzbd:
image: linuxserver/sabnzbd:latest
container_name: sabnzbd
restart: unless-stopped
environment:
- PUID=1000
- PGID=1000
- TZ=America/New_York
- UMASK=022
volumes:
- /opt/sabnzbd/config:/config
- /opt/sabnzbd/downloads:/downloads
# Optional: Share with media directories for arr stack
- /media:/media
ports:
- 8080:8080
# Optional: Limit resources
deploy:
resources:
limits:
memory: 2G
reservations:
memory: 512M Configuration Notes:
- Replace
PUIDandPGIDwith your user ID (id -uandid -g) - Update
TZto your timezone UMASK=022ensures proper file permissions- Port 8080 is the web interface (change if conflicts)
- Memory limits prevent excessive RAM usage during extraction
Optional VPN Integration:
version: '3.8'
services:
vpn:
image: qmcgaw/gluetun:latest
container_name: vpn
cap_add:
- NET_ADMIN
environment:
- VPN_SERVICE_PROVIDER=nordvpn
- OPENVPN_USER=your_username
- OPENVPN_PASSWORD=your_password
- SERVER_COUNTRIES=Netherlands
ports:
- 8080:8080
restart: unless-stopped
sabnzbd:
image: linuxserver/sabnzbd:latest
container_name: sabnzbd
network_mode: "service:vpn"
depends_on:
- vpn
environment:
- PUID=1000
- PGID=1000
- TZ=America/New_York
volumes:
- /opt/sabnzbd/config:/config
- /opt/sabnzbd/downloads:/downloads Deployment
Start SABnzbd:
cd /opt/sabnzbd
docker-compose up -d Verify container running:
docker-compose ps
docker logs sabnzbd Access the web interface at http://YOUR-SERVER-IP:8080
Initial Setup Wizard
SABnzbd includes a helpful setup wizard on first launch.
Language and Access
- Language: Select your preferred language
- Host:
0.0.0.0(allow external access) or127.0.0.1(localhost only) - Port: 8080 (or your custom port)
- Web Interface: Default (Glitter)
Click Next.
Usenet Server Configuration
Configure your primary Usenet provider:
Server Details:
- Host: Your provider’s server address (e.g.,
news.usenetserver.com) - Port:
- SSL: 563 or 443
- Non-SSL: 119 (not recommended)
- Username: Your Usenet account username
- Password: Your Usenet account password
- Connections:
- Start with 20-30 for unlimited plans
- Adjust based on provider limits and your bandwidth
- Priority: 0 (lowest number = highest priority)
- Server Description: Name for identification
- SSL: Enabled (strongly recommended)
- SSL Ciphers: Leave empty for defaults
- Enable: Checked
Testing: Click Test Server to verify connection.
Additional Settings
SABnzbd Directory: Leave as default (/config)
Temporary Download Folder: /downloads/incomplete
Completed Download Folder: /downloads/complete
Click Next and then Go to SABnzbd to complete setup.
Usenet Server Configuration
Add multiple servers for reliability and speed.
Adding Servers
Settings → Servers → Add Server:
Primary Server (your main provider):
Description: Newshosting Primary
Host: news.newshosting.com
Port: 563
SSL: Enabled
Connections: 30
Username: your_username
Password: your_password
Priority: 0
Retention: 4900 days (check provider specs) Backup Server (different provider for better completion):
Description: UsenetFarm Backup
Host: news.usenetfarm.com
Port: 563
SSL: Enabled
Connections: 20
Username: your_username
Password: your_password
Priority: 1
Retention: 3000 days Block Account (pay-per-GB for rare content):
Description: Blocknews
Host: blocknews.net
Port: 563
SSL: Enabled
Connections: 10
Username: your_username
Password: your_password
Priority: 2
Retention: 3000+ days
Optional: Checked (only used when primary fails) Server Optimization
Connection Count:
- Start conservative: 20-30 connections total
- Monitor speeds and increase if not saturating bandwidth
- Too many connections can trigger throttling
- Respect provider limits
Priority System:
- 0 = Highest priority (unlimited provider)
- 1 = Second priority (backup provider)
- 2+ = Fill servers and block accounts
- Optional servers only used when required
SSL Configuration:
- Always use SSL/TLS for privacy
- Port 563 is standard SSL port
- Port 443 works if 563 is blocked
- Disable SSL only for testing
General Settings
Configure core SABnzbd behavior.
Folders
Settings → Folders:
Temporary Download Folder: /downloads/incomplete
- Where active downloads are stored
- Should be on fast storage (SSD preferred)
Completed Download Folder: /downloads/complete
- Where finished downloads are moved
- Can be slower storage (HDD acceptable)
Watched Folder: Leave empty (use API instead)
Script Folder: /config/scripts (for custom scripts)
Tuning
Settings → General → Tuning:
Article Cache:
- Default: Empty (uses dynamic cache)
- Set manually: 500M-1G for 8GB+ RAM systems
- Lower on memory-constrained systems
Performance:
- Direct Unpack: Enabled (faster extraction)
- Pause Downloading During Post-Processing: Disabled (continue downloading)
- Enable MultiCore Par2: Enabled (faster repair)
- Enable QuickCheck: Enabled (skip unnecessary repairs)
- Extra PAR2 Parameters: Leave empty
Disk Space:
- Minimum Free Space: 10G (abort if less)
- Cleanup List:
.nfo, .sfv, .srr(remove junk files)
Security
Settings → General → Security:
Web Interface Authentication:
- Username:
admin(or custom) - Password: Strong password
- API Key: Automatically generated (save this)
External Access:
- HTTPS: Enabled (if using reverse proxy)
- HTTPS Port: 443
- HTTPS Certificate: Path to cert (if not using proxy)
Additional Security:
- Add NZB Require Authentication: Enabled
- NZB Key: Automatically generated
- External Internet Access: Enabled (if accessing remotely)
Categories Configuration
Categories enable automatic handling based on content type.
Creating Categories
Settings → Categories → Add Category:
Movies Category:
Name: movies
Priority: Normal
Processing: +Delete
Folder/Path: /downloads/complete/movies
Indexer Categories: Movies, Movies HD, Movies UHD TV Category:
Name: tv
Priority: High
Processing: +Delete
Folder/Path: /downloads/complete/tv
Indexer Categories: TV, TV HD, TV UHD Music Category:
Name: music
Priority: Normal
Processing: +Delete
Folder/Path: /downloads/complete/music
Indexer Categories: Audio Books Category:
Name: books
Priority: Low
Processing: +Delete
Folder/Path: /downloads/complete/books
Indexer Categories: Books, Ebooks Processing Options
Post-Processing Flags:
+Delete: Delete files after processing (include NZB, par2, etc.)+Repair: Run par2 repair+Unpack: Extract archives- Default for most categories:
+Delete
Priority Levels:
Force: Always process firstHigh: Important content (TV shows)Normal: Standard priorityLow: Background downloadsPaused: Manual start required
Switches and Post-Processing
Configure how SABnzbd handles completed downloads.
Post-Processing Settings
Settings → Switches:
Post Processing:
- Enable Post-Processing: Checked
- Pause Downloading During Post-Processing: Unchecked
- Only Get Articles for Top of Queue: Unchecked
- Enable Recursive Unpacking: Checked
- Ignore Samples: Checked
- Direct Unpack: Checked (faster)
- Unwanted Extensions:
.exe, .com, .bat, .cmd, .scr(Windows malware)
Cleanup:
- Safe Post-Processing: Unchecked (use atomic moves)
- Enable Par2 Multi-Core: Checked
- Enable QuickCheck: Checked
- Extra PAR2 Parameters: Leave blank
Automation Scripts
Custom Scripts run after download completion.
Example: Notification Script
Create /opt/sabnzbd/config/scripts/notify.sh:
#!/bin/bash
# SABnzbd provides these environment variables:
# SAB_COMPLETE_DIR - Final directory
# SAB_FILENAME - File/folder name
# SAB_CAT - Category
# SAB_STATUS - 0=success, 1=failed verification, 2=failed unpack
DISCORD_WEBHOOK="YOUR-WEBHOOK-URL"
if [ "$SAB_STATUS" -eq 0 ]; then
STATUS="Success"
COLOR="3066993"
else
STATUS="Failed"
COLOR="15158332"
fi
curl -X POST "$DISCORD_WEBHOOK" -H "Content-Type: application/json" -d "{
"embeds": [{
"title": "Download Complete",
"description": "$SAB_FILENAME",
"fields": [
{"name": "Category", "value": "$SAB_CAT", "inline": true},
{"name": "Status", "value": "$STATUS", "inline": true}
],
"color": $COLOR
}]
}"
# Return 0 for success
exit 0 Make executable:
chmod +x /opt/sabnzbd/config/scripts/notify.sh Assign to Category: Settings → Categories → Select Category → Script → notify.sh
arr Stack Integration
Connect SABnzbd to Sonarr, Radarr, and other automation tools.
Radarr Configuration
Radarr → Settings → Download Clients → Add → SABnzbd:
Name: SABnzbd
Enable: Checked
Host: sabnzbd (Docker network) or YOUR-SERVER-IP
Port: 8080
API Key: From SABnzbd Settings → General → Security
Username: Your SABnzbd username
Password: Your SABnzbd password
Category: movies
Priority: Default
Use SSL: Unchecked (unless using reverse proxy) Advanced Settings:
- Recent Priority: Default
- Older Priority: Default
- Remove Completed: Checked (Radarr handles imports)
- Remove Failed: Checked
Click Test then Save.
Sonarr Configuration
Sonarr → Settings → Download Clients → Add → SABnzbd:
Name: SABnzbd
Enable: Checked
Host: sabnzbd or YOUR-SERVER-IP
Port: 8080
API Key: From SABnzbd
Category: tv
Priority: Default
Recent Priority: High (new episodes priority)
Older Priority: Normal (season packs standard) Click Test then Save.
Other arr Apps
Lidarr (Music):
- Category:
music - Same configuration as above
Readarr (Books):
- Category:
books - Same configuration as above
Prowlarr (Indexer Management):
- No direct SABnzbd connection needed
- Prowlarr syncs indexers to Sonarr/Radarr
- Those apps send to SABnzbd
RSS and Automation
Configure RSS feeds for automated content discovery.
RSS Feed Configuration
Settings → RSS:
Add RSS Feed:
- Click Add Feed
- Feed URL: Your indexer RSS URL
- Name: Descriptive name
- Priority: Normal
- Category: Auto-detect or specific
- Filters: Optional (match specific patterns)
RSS Feed Types:
- Indexer RSS: New uploads from your indexer
- Show-Specific: RSS for specific series
- Newzbin Bookmarks: Import bookmarks
Filters and Automation
Create Filter:
- Settings → RSS → Add Filter
- Name: Filter description
- Match: Regular expression or simple text
- Category: Auto-assign category
- Priority: Set download priority
- Accept: Auto-download matching items
Example TV Show Filter:
Name: Download New Episodes
Match: (?i)(1080p|720p).*(AMZN|NF|DSNP)
Reject: (PROPER|REPACK)
Category: tv
Priority: High Example Movie Filter:
Name: New Movies 1080p
Match: (?i)1080p.*(BluRay|WEB-DL)
Min Size: 2G
Max Size: 15G
Category: movies
Priority: Normal Scheduling and Bandwidth
Control when and how fast SABnzbd downloads.
Speed Limiting
Settings → General → Tuning:
Speed Limit:
- Blank = Unlimited (saturate connection)
- Set value in KB/s or % of line speed
- Example:
50Mfor 50 MB/s limit
Scheduling
Settings → Scheduling → Add Schedule:
Daytime Bandwidth Limit (9 AM - 11 PM):
Start Time: 09:00
End Time: 23:00
Action: Speedlimit
Speed: 50% (limit to half speed during daytime)
Days: Monday-Sunday Nighttime Full Speed (11 PM - 9 AM):
Start Time: 23:00
End Time: 09:00
Action: Speedlimit
Speed: 100% (or leave blank for unlimited)
Days: Monday-Sunday Pause During Peak Hours:
Start Time: 18:00
End Time: 20:00
Action: Pause
Days: Monday-Friday Schedule Actions:
Resume: Start downloadsPause: Stop downloadsSpeedlimit: Set speed percentageShutdown: Stop SABnzbdRestart: Restart SABnzbdEnable Server: Activate serverDisable Server: Deactivate server
Monitoring and Queue Management
Effectively manage your download queue.
Queue Controls
Main Interface:
- Pause/Resume: Control entire queue
- Speed Limit: Quick speed adjustment
- Repair: Manual repair trigger
- Sort: Organize by name, size, age, etc.
Individual Item Controls:
- Priority: Drag to reorder or set priority
- Delete: Remove from queue
- Pause: Stop specific download
- Force: Process immediately
History Management
History Tab:
- View completed downloads
- Check failed downloads
- Retry failed items
- Purge history
Failed Download Actions:
- Retry: Attempt download again
- Repair: Run par2 repair manually
- Delete: Remove from history
- Details: View failure reason
Status and Warnings
Status Icons:
- Green Check: Completed successfully
- Red X: Failed download
- Yellow Warning: Warnings (low disk space, etc.)
- Blue Info: Informational messages
Common Warnings:
- Incomplete download (missing articles)
- Duplicate detection
- Password-protected archive
- Disk space low
- Server connection issues
Troubleshooting
Common issues and solutions.
Downloads Not Starting
Symptoms: NZB added but nothing downloads
Diagnostics:
- Check server connections: Status → Server Stats
- Verify server credentials correct
- Review SABnzbd logs: Status → Logs
Solutions:
- Test server connections in Settings → Servers
- Verify Usenet account active and not expired
- Check firewall allowing outbound ports 563/119
- Restart SABnzbd:
docker-compose restart
Slow Download Speeds
Symptoms: Not saturating internet connection
Diagnostics:
- Check connection count per server
- Review server priority settings
- Monitor server speed: Status → Server Stats
Solutions:
- Increase connections (up to 30-50 total)
- Add additional Usenet servers
- Switch to faster server/provider
- Disable speed limits: Settings → General → Speed Limit
- Enable Direct Unpack: Settings → Switches
Failed Verification/Repair
Symptoms: “Failed to verify” or “Repair failed”
Diagnostics:
- Check History for error details
- Review number of par2 files downloaded
- Check if content is old (beyond retention)
Solutions:
- Retry with more par2 files: Enable “Extra PAR2 Parameters”
- Use backup server with longer retention
- Enable “Use All Par2 Files” in Special settings
- Content may be incomplete/beyond retention period
Extraction Failures
Symptoms: “Unpack failed” errors
Diagnostics:
- Check available disk space
- Review post-processing logs
- Verify archive not password-protected
Solutions:
- Increase minimum free space: Settings → General → Tuning
- Enable Recursive Unpacking: Settings → Switches
- Check for password-protected archives (SABnzbd can’t handle)
- Verify unrar installed in container (included by default)
Permission Errors
Symptoms: Can’t write to directories, import failures
Solutions:
# Fix ownership of directories
sudo chown -R 1000:1000 /opt/sabnzbd
# Fix permissions
sudo chmod -R 755 /opt/sabnzbd/downloads
# Verify PUID/PGID in docker-compose.yml
docker-compose down
# Edit docker-compose.yml with correct PUID/PGID
docker-compose up -d API Connection Issues
Symptoms: arr apps can’t connect to SABnzbd
Solutions:
- Verify API key matches: SABnzbd Settings → General → Security
- Check host accessible:
curl http://sabnzbd:8080from arr container - Disable username/password requirement for API (optional)
- Verify External Internet Access enabled
- Check firewall rules
Performance Optimization
Maximize SABnzbd performance.
Memory Optimization
Article Cache:
- Low RAM (4GB): 256M
- Medium RAM (8GB): 512M-1G
- High RAM (16GB+): 1-2G
Settings → General → Tuning → Article Cache: 1024M
CPU Optimization
Enable MultiCore Par2: Settings → Switches → Enable MultiCore Par2: Checked
This uses all CPU cores for par2 verification/repair.
Direct Unpack: Settings → Switches → Direct Unpack: Checked
Unpacks during download instead of after.
Disk Optimization
Separate Incomplete and Complete:
- Incomplete: Fast SSD
- Complete: Slower HDD acceptable
Minimize Disk I/O:
- Enable Direct Unpack
- Use atomic moves (same filesystem)
- Disable “Safe Post-Processing”
Network Optimization
Connection Tuning:
Start with formula: (Bandwidth in Mbps / 2) = Connections
- 100 Mbps = 50 connections
- 500 Mbps = 250 connections (likely capped by provider)
- Most providers cap at 30-60 connections
Server Distribution:
Primary Server: 30 connections (priority 0)
Backup Server: 20 connections (priority 1)
Block Account: 10 connections (priority 2, optional) Security Best Practices
Protect your SABnzbd installation.
Authentication
Enable Login: Settings → General → Security:
- Username: Strong username (not admin)
- Password: Complex password
- API Key: Keep secret
Network Security
Reverse Proxy: Use Nginx/Caddy for SSL and subdomain access:
server {
listen 443 ssl http2;
server_name sabnzbd.yourdomain.com;
ssl_certificate /etc/ssl/certs/cert.pem;
ssl_certificate_key /etc/ssl/private/key.pem;
location / {
proxy_pass http://localhost:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
} Firewall:
# Allow only local network access
sudo ufw allow from 192.168.1.0/24 to any port 8080
# Or allow from specific IP
sudo ufw allow from SPECIFIC-IP to any port 8080 Data Security
Use SSL Connections: Always enable SSL for Usenet connections (port 563).
VPN Integration: Route SABnzbd through VPN for additional privacy (see Docker Compose VPN section).
Backup and Restore
Protect your configuration.
Backup Configuration
Manual Backup:
# Stop SABnzbd
cd /opt/sabnzbd
docker-compose down
# Backup config directory
tar -czf sabnzbd-backup-$(date +%Y%m%d).tar.gz /opt/sabnzbd/config
# Restart
docker-compose up -d Automated Backup Script:
#!/bin/bash
# /opt/scripts/backup-sabnzbd.sh
BACKUP_DIR="/opt/backups/sabnzbd"
DATE=$(date +%Y%m%d)
RETAIN_DAYS=30
mkdir -p "$BACKUP_DIR"
# Stop container
cd /opt/sabnzbd
docker-compose stop sabnzbd
# Backup
tar -czf "$BACKUP_DIR/sabnzbd-$DATE.tar.gz" /opt/sabnzbd/config
# Start container
docker-compose start sabnzbd
# Cleanup old backups
find "$BACKUP_DIR" -name "sabnzbd-*.tar.gz" -mtime +$RETAIN_DAYS -delete Schedule with Cron:
# Run weekly on Sunday at 3 AM
0 3 * * 0 /opt/scripts/backup-sabnzbd.sh Restore Configuration
# Stop SABnzbd
cd /opt/sabnzbd
docker-compose down
# Restore from backup
tar -xzf sabnzbd-backup-YYYYMMDD.tar.gz -C /
# Fix permissions
sudo chown -R 1000:1000 /opt/sabnzbd/config
# Restart
docker-compose up -d Maintenance
Keep SABnzbd running smoothly.
Regular Tasks
Weekly:
- Review failed downloads in History
- Clear orphaned jobs
- Check disk space
- Review server statistics
Monthly:
- Update Docker image
- Review and optimize categories
- Audit server performance
- Backup configuration
Updating SABnzbd
cd /opt/sabnzbd
# Pull latest image
docker-compose pull
# Recreate container with new image
docker-compose up -d
# Verify updated
docker logs sabnzbd | head Database Cleanup
SABnzbd automatically maintains its database, but you can force cleanup:
Settings → General → Tuning:
- Click Restart SABnzbd
Database is automatically optimized on restart.
Advanced Features
Take SABnzbd to the next level.
URL Watching
Monitor clipboard or directory for NZB URLs:
Settings → General → Tuning:
- Enable URL Watching: Checked
- Watch Folder:
/downloads/watch
Drop NZB files in watch folder for auto-import.
Pre-Queue Scripts
Process NZBs before adding to queue:
Example: Size Filter:
#!/bin/bash
# Only accept downloads under 50GB
SIZE_LIMIT=53687091200 # 50GB in bytes
if [ "$SAB_NZB_SIZE" -gt "$SIZE_LIMIT" ]; then
echo "0" # Reject
exit 0
fi
echo "1" # Accept Configure: Settings → Folders → Pre-Queue Script
Notification Integrations
Email Notifications: Settings → Notifications → Email:
- SMTP Server: smtp.gmail.com:587
- From Address: [email protected]
- To Address: [email protected]
- Username/Password: Your credentials
Discord Webhook: Settings → Notifications → Script:
- Use custom notify script (see earlier example)
Pushover, Telegram, etc.: Configure via custom scripts or third-party tools.
Conclusion
You now have a fully configured SABnzbd installation optimized for automated Usenet downloading with complete arr stack integration.
Key Takeaways
- Multi-server support ensures completion and speed
- Category-based automation enables hands-free operation
- arr stack integration provides seamless media management
- Post-processing handles repair and extraction automatically
- Monitoring and scheduling optimize resource usage
Next Steps
- Add Usenet servers with your provider credentials
- Configure categories for your content types
- Integrate with arr stack (Sonarr, Radarr, etc.)
- Set up scheduling to manage bandwidth
- Enable notifications for download completion
- Configure backups to protect your settings
Related Guides
- NZBGet alternative Usenet downloader
- Sonarr TV automation
- Radarr movie automation
- Prowlarr indexer management
- Usenet provider and indexer selection
Enjoy high-speed, automated downloads with SABnzbd!