Troubleshooting Guide

Quick Diagnostics

System Health Check

# Check if Sauron is running
sudo systemctl status sauron

# View recent logs
sudo journalctl -u sauron -n 50

# Check port availability
sudo netstat -tlnp | grep :443

# Verify domain resolution
nslookup your-domain.com

# Test SSL certificate
openssl s_client -connect your-domain.com:443 -servername your-domain.com
✅ Healthy
All systems operational
⚠️ Warning
Minor issues detected
❌ Error
Service not responding

Common Issues

❌ Service Won't Start

Symptoms:

  • • systemctl start sauron fails
  • • Service shows "failed" status
  • • Cannot connect to domain

Diagnosis:

# Check detailed status
sudo systemctl status sauron -l

# Check logs for errors
sudo journalctl -u sauron --since "10 minutes ago"

# Verify binary exists and is executable
ls -la /usr/local/bin/sauron

Solutions:

  • • Check .env file exists and has correct permissions
  • • Verify all required environment variables are set
  • • Ensure binary has execute permissions: chmod +x /usr/local/bin/sauron
  • • Check for port conflicts on 443
  • • Verify database file permissions

⚠️ SSL Certificate Issues

Symptoms:

  • • "Certificate not found" errors in logs
  • • Browser shows SSL warnings
  • • HTTPS connections fail

Diagnosis:

# Check certificate files
ls -la tls/cert.pem tls/key.pem

# Verify certificate details
openssl x509 -in tls/cert.pem -text -noout

# Test Cloudflare API
curl -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
     "https://api.cloudflare.com/client/v4/user/tokens/verify"

Solutions:

  • • Verify Cloudflare API token has correct permissions
  • • Check domain DNS points to your server
  • • Ensure Cloudflare proxy is enabled (orange cloud)
  • • Wait for DNS propagation (up to 24 hours)
  • • Restart service after DNS changes

🔗 Slug Not Working

Symptoms:

  • • "slug missing" or "slug not found" errors
  • • URLs return 400 Bad Request
  • • Statistics not updating

Diagnosis:

# Check if slug exists in database
sqlite3 config.db "SELECT * FROM user_links WHERE slug='your-slug';"

# Test slug URL directly
curl -v "https://your-domain.com/your-slug"

# Check slug format validation
echo "your-slug" | grep -E "^[A-Za-z0-9_-]{4,16}$"

Solutions:

  • • Verify slug exists in database user_links table
  • • Check slug format meets validation rules (4-16 chars, alphanumeric + _ -)
  • • Ensure slug is associated with correct user ID
  • • Clear browser cookies and try again
  • • Test with different slug formats (UUID vs short)

📡 WebSocket Connection Issues

Symptoms:

  • • Cannot connect to dashboard
  • • Authentication failures
  • • No real-time updates received

Diagnosis:

# Test WebSocket endpoint
curl --include \
     --no-buffer \
     --header "Connection: Upgrade" \
     --header "Upgrade: websocket" \
     --header "Sec-WebSocket-Key: SGVsbG8sIHdvcmxkIQ==" \
     --header "Sec-WebSocket-Version: 13" \
     https://your-domain.com/ws

# Check admin key configuration
echo $ADMIN_KEY

Solutions:

  • • Verify admin key is set correctly in environment
  • • Check firewall allows WebSocket connections
  • • Ensure SSL certificate is valid for WebSocket
  • • Test with simple WebSocket client first
  • • Check for proxy or CDN interference

🗃️ Database Issues

Symptoms:

  • • "database locked" errors
  • • Statistics not saving
  • • Configuration not persisting

Diagnosis:

# Check database file permissions
ls -la config.db

# Verify database integrity
sqlite3 config.db "PRAGMA integrity_check;"

# Check for database locks
lsof config.db

Solutions:

  • • Ensure database file has correct permissions (644)
  • • Check disk space is available
  • • Restart service to release database locks
  • • Backup and recreate database if corrupted
  • • Verify no multiple processes accessing database

Performance Issues

Slow Response Times

📊 Monitoring Commands

# Check system resources
htop
free -h
df -h

# Monitor network connections
ss -tulpn | grep :443

# Check service performance
sudo systemctl status sauron

⚡ Optimization Tips

  • • Increase server RAM if using swap
  • • Use SSD storage for better I/O
  • • Optimize database with VACUUM
  • • Clean up old logs regularly
  • • Monitor CPU usage patterns
  • • Check for memory leaks

Memory Issues

High Memory Usage

Sauron includes secure memory storage that may use significant RAM for credential storage.

Memory Management Commands:

# Check memory usage by process
ps aux | grep sauron

# Monitor memory over time
watch -n 5 'free -h && ps aux | grep sauron'

# Clear memory caches (if needed)
sudo sync && sudo sysctl -w vm.drop_caches=3

Log Analysis

Log Locations and Commands

System Logs:

# Service logs (systemd)
sudo journalctl -u sauron -f

# Application logs
tail -f logs/system.log
tail -f logs/bot.log
tail -f logs/emits.log

# Error filtering
grep -i error logs/system.log
grep -i panic logs/system.log

Log Patterns to Look For:

  • • Certificate errors: "certificate not found", "SSL handshake failed"
  • • Database errors: "database locked", "no such table"
  • • Network errors: "connection refused", "timeout"
  • • Authentication errors: "invalid admin key", "unauthorized"
  • • Slug errors: "slug missing", "invalid slug format"

Recovery Procedures

🚨 Emergency Recovery

Complete Service Reset

# Stop service
sudo systemctl stop sauron

# Backup current data
cp config.db config.db.backup
cp -r logs logs.backup

# Reset configuration
./configure-env.sh setup

# Reinstall service
sudo ./install-production.sh

# Restore data if needed
cp config.db.backup config.db

Database Recovery

# Backup corrupted database
mv config.db config.db.corrupted

# Create fresh database
./sauron --init-db

# Restore data from backup if available
sqlite3 config.db < backup.sql

📋 Maintenance Checklist

Daily Checks:

  • • Service status: systemctl status sauron
  • • Disk space: df -h
  • • Memory usage: free -h
  • • SSL certificate validity
  • • Recent error logs

Weekly Maintenance:

  • • Log cleanup and rotation
  • • Database vacuum and optimization
  • • Security updates
  • • Configuration backup
  • • Performance monitoring review

Getting Help

Support Resources

📚 Documentation

  • • Complete setup guide
  • • Configuration reference
  • • API documentation
  • • This troubleshooting guide

🔍 Self-Diagnosis

  • • System health checks
  • • Log analysis tools
  • • Configuration validation
  • • Performance monitoring

🐛 Bug Reports

  • • Include system information
  • • Provide relevant log excerpts
  • • Document reproduction steps
  • • Specify environment details

💬 Community Support

  • • GitHub Issues and Discussions
  • • Community forums
  • • Professional support options
  • • Security research collaboration

Preventive Measures

✅ Best Practices

  • • Regular system updates and security patches
  • • Automated backup of configuration and data
  • • Monitoring and alerting setup
  • • Resource usage tracking
  • • SSL certificate renewal automation
  • • Log rotation and cleanup automation
  • • Performance baseline establishment

🛡️ Security Measures

  • • Strong authentication credentials
  • • Network security and firewall rules
  • • Regular security audits
  • • Access logging and monitoring
  • • Secure configuration management
  • • Incident response procedures
  • • Data protection and privacy measures