Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Troubleshooting

Quick Diagnostic

Run bssh doctor before changing connection settings. It checks the active environment, configuration, SQLite database, SSH client, SSH config, ssh-agent socket, and Kerberos helper tools.

bssh doctor
bssh --env staging doctor

Use any FAILED entry as the first fix target. WARN entries are non-blocking, but they explain why features such as ssh-agent, SSH config import, or Kerberos may not work in the current environment.

Kerberos Authentication Problems

No Valid Kerberos Ticket Found

# Check current ticket status
klist

# Create new forwardable ticket
kinit -f -A

# Verify ticket creation
klist -s

Symptoms:

  • Error: “No valid Kerberos ticket found”
  • SSH connection fails with authentication error
  • klist shows no tickets or expired tickets

Solutions:

  1. Check ticket status: klist -s
  2. Create new ticket: kinit -f -A
  3. Verify realm configuration: Check /etc/krb5.conf
  4. Check DNS resolution: Ensure realm DNS is working

Ticket Expired or Invalid

# Check ticket expiration
klist

# Renew existing ticket
kinit -R

# Create new ticket if renewal fails
kinit -f -A

Symptoms:

  • Error: “Ticket expired”
  • Authentication fails after some time
  • klist shows expired tickets

Solutions:

  1. Automatic renewal: kinit -R
  2. Manual renewal: kinit -f -A
  3. Check clock sync: Ensure system time is correct
  4. Verify KDC: Check KDC server availability

SSH Connection Issues

Connection Refused

# Test basic connectivity
telnet server.company.com 22

# Check SSH service status
ssh -v server.company.com

# Verify firewall rules
sudo iptables -L

Symptoms:

  • Error: “Connection refused”
  • SSH connection times out
  • Port 22 unreachable

Solutions:

  1. Check SSH service: systemctl status sshd
  2. Verify port: Ensure SSH is listening on correct port
  3. Check firewall: Verify firewall allows SSH traffic
  4. Network connectivity: Test basic network reachability

Authentication Failed

# Test with verbose output
ssh -v user@server.company.com

# Check key permissions
ls -la ~/.ssh/
chmod 600 ~/.ssh/id_rsa

# Test specific key
ssh -i ~/.ssh/id_rsa user@server.company.com

Symptoms:

  • Error: “Permission denied”
  • Authentication fails with valid credentials
  • Key-based authentication fails

Solutions:

  1. Check key permissions: chmod 600 ~/.ssh/id_rsa
  2. Verify key format: Ensure key is in correct format
  3. Check server configuration: Verify authorized_keys setup
  4. Test manually: Use standard SSH command to test

Bastion Host Problems

Bastion Connection Fails

# Test bastion connectivity
ssh -t -A -K user@bastion.company.com

# Test with specific port
ssh -p 2222 user@bastion.company.com

# Verify bastion configuration
bayesian-ssh show "Server Name"

# Force direct connection (bypass bastion)
bayesian-ssh connect "Target Server" --no-bastion

# Check if connection is using default bastion
bayesian-ssh show "Target Server"

Symptoms:

  • Error: “Bastion connection failed”
  • Cannot reach target through bastion
  • Bastion authentication fails

Solutions:

  1. Test bastion directly: ssh user@bastion.company.com
  2. Check bastion port: Verify correct port (default: 22)
  3. Verify user permissions: Ensure bastion user has access
  4. Check network path: Verify bastion is reachable

Target Host Unreachable via Bastion

# Test from bastion to target
ssh -t -A -K user@bastion.company.com "ssh user@target.company.com"

# Check routing on bastion
ssh user@bastion.company.com "route -n"

# Verify target accessibility
ssh user@bastion.company.com "ping target.company.com"

Symptoms:

  • Bastion connects but target is unreachable
  • Error: “No route to host”
  • Connection times out to target

Solutions:

  1. Check bastion routing: Verify bastion can reach target
  2. Verify target firewall: Ensure target allows bastion traffic
  3. Check network segmentation: Verify network policies
  4. Test manually: Connect to bastion and test target manually

Unexpected Bastion Usage

# Check if connection is using default bastion
bayesian-ssh show "Server Name"

# Force direct connection
bayesian-ssh connect "Server Name" --no-bastion

# Re-add connection with explicit no-bastion flag
bayesian-ssh remove "Server Name"
bayesian-ssh add "Server Name" hostname.com --no-bastion --tags production

Symptoms:

  • Connection unexpectedly goes through bastion
  • Want direct connection but getting bastion routing
  • Default bastion being used when not intended

Solutions:

  1. Use --no-bastion flag: Explicitly disable bastion for specific connections
  2. Check connection details: Use bayesian-ssh show to see bastion configuration
  3. Re-add connection: Remove and re-add with correct bastion settings
  4. Verify configuration: Check if default bastion is set in config

Database Issues

Database Connection Failed

# Check database file
ls -la ~/.config/bayesian-ssh/

# Verify permissions
chmod 755 ~/.config/bayesian-ssh/
chmod 644 ~/.config/bayesian-ssh/history.db

# Recreate database
rm ~/.config/bayesian-ssh/history.db
bayesian-ssh stats

Symptoms:

  • Error: “Database connection failed”
  • Cannot save or retrieve connections
  • Application crashes on database operations

Solutions:

  1. Check file permissions: Ensure proper ownership and permissions
  2. Verify disk space: Check available disk space
  3. Recreate database: Remove corrupted database file
  4. Check SQLite version: Ensure compatible SQLite version

Database Schema Issues

# Check database schema
sqlite3 ~/.config/bayesian-ssh/history.db ".schema"

# Verify table structure
sqlite3 ~/.config/bayesian-ssh/history.db "SELECT * FROM connections LIMIT 1;"

Symptoms:

  • Error: “Table not found”
  • Database operations fail with schema errors
  • Missing tables or columns

Solutions:

  1. Check schema: Verify table structure
  2. Recreate database: Remove and recreate database
  3. Check migrations: Ensure schema is up to date
  4. Verify SQLite: Check SQLite version compatibility

Configuration Problems

Configuration File Not Found

# Check configuration directory
ls -la ~/.config/bayesian-ssh/

# Create default configuration
bayesian-ssh config

# Verify configuration
cat ~/.config/bayesian-ssh/config.json

Symptoms:

  • Error: “Configuration file not found”
  • Application uses default values
  • Configuration changes not saved

Solutions:

  1. Create directory: mkdir -p ~/.config/bayesian-ssh/
  2. Generate config: Run bayesian-ssh config to create default
  3. Check permissions: Ensure directory is writable
  4. Verify path: Check configuration file path

Invalid Configuration Values

# View current configuration
bayesian-ssh config

# Reset to defaults
rm ~/.config/bayesian-ssh/config.json
bayesian-ssh config

# Validate configuration
cat ~/.config/bayesian-ssh/config.json | jq .

Symptoms:

  • Error: “Invalid configuration”
  • Application fails to start
  • Configuration values ignored

Solutions:

  1. Validate JSON: Check JSON syntax
  2. Reset configuration: Remove and recreate config file
  3. Check values: Verify configuration parameter values
  4. Use defaults: Start with minimal configuration

Performance Issues

Slow Connection Establishment

# Check DNS resolution time
time nslookup server.company.com

# Test connection speed
time ssh -o ConnectTimeout=10 user@server.company.com

# Profile application
bayesian-ssh --log-level debug connect "Server Name"

Symptoms:

  • Long connection times
  • Slow response to commands
  • High latency

Solutions:

  1. Check DNS: Verify DNS resolution speed
  2. Network latency: Test network performance
  3. Server load: Check target server performance
  4. Optimize configuration: Review connection settings

High Memory Usage

# Check memory usage
ps aux | grep bayesian-ssh

# Monitor resource usage
top -p $(pgrep bayesian-ssh)

Symptoms:

  • High memory consumption
  • Application becomes unresponsive
  • System memory pressure

Solutions:

  1. Check for leaks: Monitor memory usage over time
  2. Optimize queries: Review database query efficiency
  3. Limit connections: Reduce concurrent connections
  4. Update dependencies: Ensure latest library versions

Network and Firewall Issues

Firewall Blocking Connections

# Check local firewall
sudo ufw status
sudo iptables -L

# Test port accessibility
telnet server.company.com 22
nmap -p 22 server.company.com

Symptoms:

  • Connection blocked by firewall
  • Port 22 unreachable
  • Network policy violations

Solutions:

  1. Check local firewall: Verify local firewall settings
  2. Corporate policies: Contact network administrator
  3. Alternative ports: Use non-standard SSH ports
  4. VPN access: Connect through corporate VPN

DNS Resolution Issues

# Check DNS resolution
nslookup server.company.com
dig server.company.com

# Test with IP address
ssh user@192.168.1.100

# Check /etc/hosts
cat /etc/hosts

Symptoms:

  • Hostname not found
  • DNS resolution failures
  • Connection timeouts

Solutions:

  1. Check DNS servers: Verify DNS configuration
  2. Use IP addresses: Connect directly with IP
  3. Check /etc/hosts: Verify local host entries
  4. Network configuration: Check network settings

Application Crashes

Panic Errors

# Enable backtrace
RUST_BACKTRACE=1 bayesian-ssh connect "Server"

# Check logs
tail -f ~/.config/bayesian-ssh/bayesian-ssh.log

# Run with verbose output
bayesian-ssh --log-level debug

Symptoms:

  • Rust panic errors
  • Application terminates unexpectedly
  • Error messages with backtraces

Solutions:

  1. Enable backtraces: Set RUST_BACKTRACE=1
  2. Check logs: Review application logs
  3. Update to latest version: Bug may be fixed in newer release
  4. Report issue: File a bug report with backtrace on GitHub Issues

Getting Help

Debug Information

When reporting issues, include:

  • Error messages: Complete error output
  • Environment: OS version, Rust version, dependencies
  • Configuration: Relevant configuration files (redact sensitive data)
  • Steps to reproduce: Detailed reproduction steps
  • Logs: Application and system logs

Useful Diagnostic Commands

# Enable debug logging
bayesian-ssh --log-level debug

# Check system information
uname -a
rustc --version
cargo --version

# Verify dependencies
ldd $(which bayesian-ssh)

# Check file permissions
ls -la ~/.config/bayesian-ssh/
ls -la ~/.ssh/