Common Issues & Solutions¶

This guide covers the most frequently encountered issues when using Relyr and their solutions.

Installation Issues¶

Permission Denied Errors¶

Problem: Getting permission denied when installing or running Relyr.

Solutions:

Linux/macOS - Binary Installation:

# Fix permissions for binary
sudo chmod +x /usr/local/bin/relyr

# Fix ownership
sudo chown root:root /usr/local/bin/relyr

Configuration Directory:

# Create and fix config directory permissions
mkdir -p ~/.config/relyr
chmod 755 ~/.config/relyr

Service Installation:

# For systemd services
sudo systemctl daemon-reload
sudo systemctl enable relyr

Missing Dependencies¶

Problem: Relyr fails to start due to missing system dependencies.

Solutions:

Ubuntu/Debian:

sudo apt update
sudo apt install build-essential curl wget ca-certificates

CentOS/RHEL:

sudo yum update
sudo yum groupinstall "Development Tools"
sudo yum install curl wget ca-certificates

macOS:

# Install Xcode command line tools
xcode-select --install

# Or using Homebrew
brew install curl wget

Package Manager Issues¶

Problem: Package manager can't find Relyr packages.

Solutions:

Update package sources:

# APT
sudo apt update

# YUM
sudo yum clean all && sudo yum update

# Homebrew
brew update

Verify repository configuration:

# Check if Relyr repository is added
cat /etc/apt/sources.list.d/relyr.list

Configuration Issues¶

Invalid Configuration File¶

Problem: Relyr fails to start with configuration errors.

Diagnosis:

# Validate configuration
relyr config validate

# Check configuration syntax
relyr config check --file /path/to/relyr.yml

Solutions:

YAML Syntax Errors:

# Use a YAML validator
python -c "import yaml; yaml.safe_load(open('/path/to/relyr.yml'))"

Common YAML mistakes:

# ❌ Wrong indentation
server:
host: 0.0.0.0
port: 8080

# ✅ Correct indentation
server:
  host: 0.0.0.0
  port: 8080

# ❌ Missing quotes for special characters
password: p@ssw0rd!

# ✅ Quoted special characters
password: "p@ssw0rd!"

Port Already in Use¶

Problem: Relyr can't bind to the configured port.

Diagnosis:

# Check what's using the port
sudo netstat -tulpn | grep :8080
sudo lsof -i :8080

# On macOS
lsof -i :8080

Solutions:

Change port in configuration:

server:
  port: 8081  # Use a different port

Kill conflicting process:

# Find and kill the process
sudo kill -9 <PID>

# Or stop the service
sudo systemctl stop <service-name>

Use a different port:

# Start with custom port
relyr server --port 8081

Connection Issues¶

Proxy Connection Failures¶

Problem: Clients can't connect through the proxy.

Diagnosis:

# Test proxy connectivity
curl -x http://localhost:8080 https://httpbin.org/ip

# Check if Relyr is listening
netstat -tulpn | grep :8080

# Test with verbose output
curl -v -x http://localhost:8080 https://httpbin.org/ip

Solutions:

Firewall blocking connections:

# Ubuntu/Debian
sudo ufw allow 8080

# CentOS/RHEL
sudo firewall-cmd --add-port=8080/tcp --permanent
sudo firewall-cmd --reload

# Check iptables
sudo iptables -L -n

Binding to wrong interface:

server:
  host: 0.0.0.0  # Listen on all interfaces
  port: 8080

Authentication issues:

# Test with authentication
curl -x http://username:password@localhost:8080 https://httpbin.org/ip

SSL/TLS Certificate Issues¶

Problem: HTTPS proxy connections fail with certificate errors.

Diagnosis:

# Test SSL connection
openssl s_client -connect localhost:8443 -servername localhost

# Check certificate validity
openssl x509 -in /path/to/cert.pem -text -noout

Solutions:

Self-signed certificate issues:

# Generate new self-signed certificate
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

Certificate path configuration:

server:
  tls:
    enabled: true
    cert_file: /path/to/cert.pem
    key_file: /path/to/key.pem

Trust certificate on client:

# Add to system trust store (Ubuntu)
sudo cp cert.pem /usr/local/share/ca-certificates/relyr.crt
sudo update-ca-certificates

Upstream Proxy Issues¶

Problem: Connection to upstream proxy fails.

Diagnosis:

# Test upstream proxy directly
curl -x http://upstream.proxy.com:8080 https://httpbin.org/ip

# Check DNS resolution
nslookup upstream.proxy.com
dig upstream.proxy.com

Solutions:

DNS resolution issues:

upstream:
  proxy: http://192.168.1.100:8080  # Use IP instead of hostname

Authentication with upstream:

upstream:
  proxy: http://upstream.proxy.com:8080
  auth:
    username: "user"
    password: "pass"

Timeout configuration:

upstream:
  proxy: http://upstream.proxy.com:8080
  timeout: 60s

Performance Issues¶

High Memory Usage¶

Problem: Relyr consuming too much memory.

Diagnosis:

# Check memory usage
ps aux | grep relyr
top -p $(pgrep relyr)

# Check for memory leaks
valgrind --tool=memcheck --leak-check=full relyr server

Solutions:

Limit connection pool size:

performance:
  max_connections: 500
  max_connections_per_host: 50

Adjust garbage collection (if applicable):
```
# For Go-based builds
export GOGC=100
```

Monitor and restart if needed:

# Add to systemd service
MemoryMax=1G
Restart=on-failure

Slow Response Times¶

Problem: Proxy responses are slow.

Diagnosis:

# Measure response times
time curl -x http://localhost:8080 https://httpbin.org/ip

# Check network latency
ping target-server.com
traceroute target-server.com

Solutions:

Optimize timeouts:

proxy:
  timeouts:
    connect: 5s
    read: 30s
    write: 30s

Enable connection pooling:

performance:
  connection_pooling:
    enabled: true
    max_idle_connections: 100
    idle_timeout: 90s

Use compression:

proxy:
  compression:
    enabled: true
    level: 6

High CPU Usage¶

Problem: Relyr using excessive CPU resources.

Solutions:

Limit concurrent connections:

performance:
  max_concurrent_requests: 1000
  worker_threads: 4

Optimize logging:

logging:
  level: warn  # Reduce log verbosity
  async: true

Profile CPU usage:

# Use profiling tools
perf top -p $(pgrep relyr)

Authentication Issues¶

API Key Not Working¶

Problem: API requests fail with authentication errors.

Solutions:

Verify API key format:

# Check key format
echo $RELYR_API_KEY | cut -c1-10

Check key permissions:

relyr api-key list
relyr api-key show --id key_123456

Test with curl:

curl -H "X-API-Key: $RELYR_API_KEY" \
     http://localhost:8080/api/v1/health

Token Expiration¶

Problem: Bearer tokens expire too quickly.

Solutions:

Increase token lifetime:

auth:
  jwt:
    access_token_ttl: 3600  # 1 hour
    refresh_token_ttl: 86400  # 24 hours

Implement token refresh:

# Python example
def refresh_token():
    response = requests.post('/api/v1/auth/refresh', 
                            json={'refresh_token': refresh_token})
    return response.json()['access_token']

Logging Issues¶

Missing Log Files¶

Problem: Log files are not being created.

Solutions:

Check log directory permissions:

sudo mkdir -p /var/log/relyr
sudo chown relyr:relyr /var/log/relyr
sudo chmod 755 /var/log/relyr

Verify logging configuration:

logging:
  level: info
  output: file
  file: /var/log/relyr/relyr.log
  rotation:
    enabled: true
    max_size: 100MB
    max_files: 10

Log Rotation Not Working¶

Problem: Log files grow too large.

Solutions:

Configure logrotate:

sudo tee /etc/logrotate.d/relyr <<EOF
/var/log/relyr/*.log {
    daily
    missingok
    rotate 30
    compress
    notifempty
    create 644 relyr relyr
    postrotate
        systemctl reload relyr
    endscript
}
EOF

Network Issues¶

DNS Resolution Problems¶

Problem: Proxy can't resolve hostnames.

Solutions:

Configure DNS servers:

network:
  dns:
    servers:
      - 8.8.8.8
      - 1.1.1.1
    timeout: 5s

Test DNS resolution:

nslookup google.com 8.8.8.8
dig @1.1.1.1 google.com

IPv6 Issues¶

Problem: IPv6 connections fail.

Solutions:

Disable IPv6 if not needed:
```
network:
  ipv6:
    enabled: false
```

Configure IPv6 properly:

network:
  ipv6:
    enabled: true
    prefer_ipv4: true

Docker Issues¶

Container Won't Start¶

Problem: Relyr Docker container fails to start.

Solutions:

Check container logs:

docker logs relyr
docker logs --follow relyr

Verify port mapping:

docker run -p 8080:8080 relyr/relyr:latest

Check volume mounts:

docker run -v $(pwd)/config:/etc/relyr relyr/relyr:latest

Permission Issues in Container¶

Problem: Permission denied errors in Docker container.

Solutions:

Run as non-root user:
```
USER 1000:1000
```
Fix volume permissions:
```
sudo chown -R 1000:1000 ./config
```

Getting Help¶

If you can't resolve your issue:

Check system logs:

# systemd logs
journalctl -u relyr -f

# Application logs
tail -f /var/log/relyr/relyr.log

Enable debug logging:
```
logging:
  level: debug
```

Collect system information:

relyr version
relyr config show
uname -a

Report the issue:
GitHub Issues
Community Forum
Include logs, configuration, and system info

Preventive Measures¶

Regular Maintenance¶

Update regularly:

# Check for updates
relyr version --check-updates

# Update using package manager
sudo apt update && sudo apt upgrade relyr

Monitor resource usage:

# Set up monitoring
watch 'ps aux | grep relyr'

Backup configuration:

cp ~/.config/relyr/relyr.yml ~/.config/relyr/relyr.yml.backup

Health Checks¶

Set up automated health checks:

#!/bin/bash
# health-check.sh
if ! curl -f http://localhost:8080/health > /dev/null 2>&1; then
    echo "Relyr health check failed"
    systemctl restart relyr
fi

Add to crontab:

# Run every 5 minutes
*/5 * * * * /path/to/health-check.sh