Troubleshooting Guide

Troubleshooting Guide

This guide helps diagnose and resolve common issues with Bifrost.

Quick Diagnostics

Check Service Status

# Server health
curl http://localhost:7082/api/v1/health

# Server status
curl http://localhost:7082/api/v1/status

# Backend status
curl http://localhost:7082/api/v1/backends

Enable Debug Logging

Set the log level to debug in your configuration:

logging:
  level: debug
  format: text  # Use 'text' for human-readable output

Or via CLI:

bifrost-server -c config.yaml --log-level debug

---

Connection Issues

”Connection Refused”

Symptoms: Clients cannot connect to the proxy.

Causes and Solutions:

1. Service not running

   # Check if process is running
   ps aux | grep bifrost
   
   # Check service status
   systemctl status bifrost-server

2. Wrong bind address

   # Wrong: only localhost can connect
   server:
     http:
       listen: "127.0.0.1:7080"
   
   # Correct: all interfaces
   server:
     http:
       listen: ":7080"

3. Firewall blocking

   # Linux: Check iptables
   sudo iptables -L -n | grep 8080
   
   # Allow port
   sudo ufw allow 8080/tcp

”Connection Timeout”

Symptoms: Connections hang and eventually timeout.

Causes and Solutions:

1. Backend unreachable

   # Test backend connectivity
   curl -x http://localhost:7080 https://example.com
   
   # Check backend health
   curl http://localhost:7082/api/v1/backends

2. DNS resolution issues

   # Test DNS
   nslookup example.com
   
   # For WireGuard, check DNS config

3. Timeout too short

   server:
     http:
       read_timeout: "60s"   # Increase if needed
       write_timeout: "60s"

”Proxy Authentication Required” (407)

Symptoms: Browser shows authentication prompt.

Solutions:

1. Check credentials

   # Test with curl
   curl -x http://user:password@localhost:7080 https://example.com

2. Verify auth configuration

   auth:
     mode: native
     native:
       users:
         - username: myuser
           password_hash: "$2a$12$..."  # bcrypt hash

3. Generate correct password hash

   # Using htpasswd
   htpasswd -nbBC 12 "" "mypassword" | cut -d: -f2

---

Backend Issues

WireGuard Tunnel Not Working

Symptoms: Traffic through WireGuard backend fails.

Diagnostics:

# Check WireGuard interface
sudo wg show

# Check routing
ip route show

# Test connectivity through tunnel
ping 10.0.0.1  # Peer IP

Common Issues:

1. Missing kernel module (for kernel mode)

   sudo modprobe wireguard

2. Permission denied

   # Run with sufficient privileges or use userspace mode
   sudo setcap cap_net_admin+ep /usr/local/bin/bifrost-server

3. Key mismatch

   • Verify public/private key pairs match between peers
   • Check for typos in configuration

4. Firewall blocking UDP

   sudo ufw allow 51820/udp

OpenVPN Tunnel Not Working

Symptoms: OpenVPN backend shows unhealthy status.

Diagnostics:

# Check OpenVPN process
ps aux | grep openvpn

# View OpenVPN logs
tail -f /var/log/openvpn.log

Common Issues:

1. Config file not found

   backends:
     - name: vpn
       type: openvpn
       config:
         config_file: "/etc/openvpn/client.ovpn"  # Must be absolute path

2. Authentication failed

   # Use inline credentials
   config:
     config_content: |
       client
       dev tun
       ...
     username: "myuser"
     password: "mypassword"

3. OpenVPN binary not found

   # Install OpenVPN
   sudo apt install openvpn
   
   # Or specify path
   config:
     binary: "/usr/sbin/openvpn"

HTTP/SOCKS5 Upstream Proxy Issues

Diagnostics:

# Test upstream proxy directly
curl -x http://upstream-proxy:7380 https://example.com

# Check connectivity
nc -zv upstream-proxy 3128

---

Performance Issues

High Latency

Diagnostics:

# Measure request time
time curl -x http://localhost:7080 https://example.com -o /dev/null

# Check active connections
curl http://localhost:7082/api/v1/stats

Solutions:

1. Enable connection keep-alive

   server:
     http:
       idle_timeout: "120s"

2. Increase file descriptor limit

   # Check current limit
   ulimit -n
   
   # Increase (in systemd service file)
   LimitNOFILE=65536

3. Use load balancing

   routes:
     - domains: ["*"]
       backends:
         - backend1
         - backend2
       load_balance: least_conn

High Memory Usage

Diagnostics:

# Check memory usage
ps aux | grep bifrost | awk '{print $6/1024 " MB"}'

# Monitor over time
watch -n 5 'ps aux | grep bifrost'

Solutions:

1. Limit request log size

   api:
     request_log_size: 500  # Reduce from default 1000

2. Disable request logging if not needed

   api:
     enable_request_log: false

---

Configuration Issues

”Invalid Configuration” Error

Diagnostics:

# Validate configuration
bifrost-server validate -c config.yaml

Common Issues:

1. Missing required fields

   # Backend needs name and type
   backends:
     - name: mybackend    # Required
       type: direct       # Required

2. Invalid YAML syntax

   • Check indentation (use spaces, not tabs)
   • Quote strings with special characters

3. Unknown backend type

   • Valid types: direct, wireguard, openvpn, http_proxy, socks5_proxy

Configuration Hot-Reload Not Working

Symptoms: Changes not applied after reload.

Check:

1. Verify reload signal received

   # Send SIGHUP
   kill -HUP $(pgrep bifrost-server)
   
   # Or via API
   curl -X POST http://localhost:7082/api/v1/config/reload

2. Check logs for reload errors

   journalctl -u bifrost-server -f

3. Some changes require restart

   • Listener addresses
   • TLS configuration
   • Authentication mode

---

Authentication Issues

Windows System Authentication Not Working

Symptoms: Server fails to start with error about system authentication not being supported on Windows.

Cause: System authentication (auth.mode: system) uses OS-level authentication (PAM on Linux, Directory Services on macOS). Windows is not currently supported.

Error Message:

authentication method not supported: system authentication is not supported on Windows - use native, ldap, or oauth instead

Solution:

Use a different authentication mode on Windows:

1. Native Authentication (recommended for simple setups):

   auth:
     mode: native
     native:
       users:
         - username: admin
           password_hash: "$2a$12$..."  # bcrypt hash

2. LDAP Authentication (for Active Directory):

   auth:
     mode: ldap
     ldap:
       url: "ldap://your-dc.domain.com:389"
       base_dn: "dc=domain,dc=com"
       user_filter: "(sAMAccountName=%s)"

3. OAuth/OIDC (for SSO):

   auth:
     mode: oauth
     oauth:
       issuer_url: "https://auth.example.com"
       client_id: "..."

See the Authentication Guide for more details.

LDAP Authentication Failing

Diagnostics:

# Test LDAP connection
ldapsearch -x -H ldap://ldap.example.com -D "cn=admin,dc=example,dc=com" -W -b "dc=example,dc=com"

Common Issues:

1. Wrong bind DN or password
2. User filter not matching

   ldap:
     user_filter: "(uid=%s)"        # For Unix-style
     user_filter: "(sAMAccountName=%s)"  # For Active Directory

3. TLS certificate issues

   ldap:
     tls: true
     insecure_skip_verify: true  # Only for testing!

OAuth/OIDC Issues

Diagnostics:

1. Check redirect URL matches exactly
2. Verify client ID and secret
3. Check issuer URL is reachable

---

Logging and Debugging

View Logs

# Systemd
journalctl -u bifrost-server -f

# Docker
docker logs -f bifrost-server

# File-based
tail -f /var/log/bifrost/server.log

Structured JSON Logs

logging:
  level: info
  format: json
  output: /var/log/bifrost/server.log

Parse with jq:

cat server.log | jq 'select(.level == "error")'

Request Debugging

Enable request logging to see individual requests:

api:
  enable_request_log: true
  request_log_size: 1000

View via API:

curl http://localhost:7082/api/v1/requests | jq

---

Getting Help

If you’re still stuck:

1. Check the logs - Most issues are explained in log messages
2. Enable debug logging - More verbose output helps identify issues
3. Search existing issues - GitHub Issues
4. Open a new issue - Include:
   • Bifrost version (bifrost-server version)
   • OS and version
   • Configuration (sanitized)
   • Relevant log output
   • Steps to reproduce