Bayesian SSH

An ultra-fast and intelligent SSH session manager with Bayesian-ranked search, fuzzy matching, Kerberos support, bastion hosts, and advanced history management.

What is Bayesian SSH?

Bayesian SSH transforms your SSH experience with intelligent automation:

• Bayesian-ranked search - connections ranked by frequency, recency, and match quality
• Intelligent fuzzy search across all commands - find connections by partial names, tags, or patterns
• One-click connections to your servers
• Automatic Kerberos ticket management
• Smart bastion host routing
• Tag-based organization for easy management
• Complete connection history with statistics
• SQLite database for persistence
• Full-screen TUI for browsing and managing connections

Documentation Overview

This documentation is organized into the following sections:

• Getting Started - Installation, quick start, and initial configuration
• User Guide - Day-to-day usage and features
• Advanced Usage - Enterprise environments, cloud infrastructure, and complex scenarios
• Reference - Technical architecture, troubleshooting, and changelog

Installation

Option 1: One-liner Install (Recommended)

# Install latest release automatically (non-interactive)
curl -fsSL https://raw.githubusercontent.com/abdoufermat5/bayesian-ssh/main/install.sh | bash

# Interactive installation (choose options)
curl -fsSL https://raw.githubusercontent.com/abdoufermat5/bayesian-ssh/main/install.sh | bash -s -- --interactive

Option 2: Manual Build

Prerequisites

rustup install stable

Build and Install

# Clone and build
git clone https://github.com/abdoufermat5/bayesian-ssh.git
cd bayesian-ssh

# Build and install using Makefile
make release
make install

# Or build manually
cargo build --release
sudo cp target/release/bayesian-ssh /usr/local/bin/

Verify Installation

bayesian-ssh --version

Enable Tab Completion

Generate and source a completion script for your shell:

# Bash
bayesian-ssh completions bash > bayesian-ssh-completion.bash
source bayesian-ssh-completion.bash

# Zsh
bayesian-ssh completions zsh > _bayesian-ssh
# Move to your zsh completions directory

# Fish
bayesian-ssh completions fish > bayesian-ssh.fish
# Move to your fish completions directory

To make completions permanent, add the source line to your shell’s rc file (e.g. ~/.bashrc).

Quick Start

Add Your First Server

bayesian-ssh add "My Server" server.company.com

Connect to It

bayesian-ssh connect "My Server"

Browse All Connections

# List view
bayesian-ssh list

# Interactive TUI
bayesian-ssh tui

Core Commands at a Glance

Fuzzy Search

All commands support intelligent fuzzy search:

bayesian-ssh connect "webprod"     # Finds "web-prod-server"
bayesian-ssh connect "prod"        # Shows all production servers
bayesian-ssh show "dbprod"         # Show connection details
bayesian-ssh edit "apigateway"     # Edit connection settings

Search is Bayesian-ranked by default, combining:

• Usage frequency (with Laplace smoothing)
• Match quality (exact, prefix, word-boundary, contains)
• Recency (exponential decay based on last use)
• Success rate (connections that work get boosted)

Configuration

Configuration File Location

Bayesian SSH automatically creates its configuration directory at:

~/.config/bayesian-ssh/
├── config.json          # Application configuration
└── history.db           # SQLite database

Viewing and Updating Configuration

# View current configuration
bayesian-ssh config

# Update configuration
bayesian-ssh config --use-kerberos --default-user customuser

# Set default bastion
bayesian-ssh config --default-bastion bastion.company.com

# Clear default bastion
bayesian-ssh config --clear-bastion

# Set search mode
bayesian-ssh config --search-mode bayesian   # Smart ranking (default)
bayesian-ssh config --search-mode fuzzy      # Simple pattern matching

Configuration Options

{
  "default_user": "current-system-user",
  "default_bastion": "bastion.company.com",
  "default_bastion_user": "current-system-user",
  "use_kerberos_by_default": false,
  "log_level": "info",
  "auto_save_history": true,
  "max_history_size": 1000,
  "search_mode": "bayesian"
}

Multi-Environment Configuration

Manage separate configs per environment:

# Use a specific environment
bayesian-ssh --env production connect "Server"
bayesian-ssh --env staging list

Connection Management

Adding Connections

# Basic connection
bayesian-ssh add "Server Name" hostname.com

# With specific bastion
bayesian-ssh add "Server Name" hostname.com --bastion bastion.company.com

# Force direct connection (no bastion)
bayesian-ssh add "Server Name" hostname.com --no-bastion

# With tags for organization
bayesian-ssh add "Web Prod" web-prod.company.com --tags production,web

# With custom user and key
bayesian-ssh add "EC2 Web" ec2-web.company.com \
  --user ubuntu \
  --kerberos false \
  --key ~/.ssh/ec2-key.pem \
  --tags ec2,production

Connecting to Servers

# Exact match
bayesian-ssh connect "Server Name"

# Fuzzy search
bayesian-ssh connect "webprod"            # Finds "web-prod-server"
bayesian-ssh connect "prod"               # Shows all production servers

# With overrides
bayesian-ssh connect "Server Name" --no-bastion --user customuser

Listing Connections

# List all connections
bayesian-ssh list

# Filter by tag
bayesian-ssh list --tag production
bayesian-ssh list --tag development

Viewing Connection Details

bayesian-ssh show "Server Name"

# Fuzzy search works here too
bayesian-ssh show "dbprod"

Editing Connections

bayesian-ssh edit "Server Name"

# Fuzzy search
bayesian-ssh edit "webprod"

Removing Connections

# With confirmation prompt
bayesian-ssh remove "Server Name"

# Skip confirmation
bayesian-ssh remove "Server Name" --force

Duplicating Connections

Clone an existing connection with a new name:

bayesian-ssh duplicate "Source Server" "New Server"

Grouping Connections

Organize connections into groups:

bayesian-ssh groups

Ping / Latency Check

Test connectivity to a server:

bayesian-ssh ping "Server Name"

Session Management

View Session History

# Recent sessions with stats
bayesian-ssh history

# Filter by connection
bayesian-ssh history --connection prod

# Last 7 days, failures only
bayesian-ssh history --days 7 --failed

# Limit results
bayesian-ssh history --limit 50

Manage Active Sessions

# List active sessions (shows PIDs and stale detection)
bayesian-ssh close

# Close specific session
bayesian-ssh close "Prod Server"

# Clean up stale sessions (PIDs no longer running)
bayesian-ssh close --cleanup

# Force close all
bayesian-ssh close --all --force

View Statistics

bayesian-ssh stats

Statistics include success/failure rates, average session duration, and usage frequency across all connections.

Backup and Restore

Backup

bayesian-ssh backup

Restore

bayesian-ssh restore

This backs up and restores the SQLite database containing all connections, sessions, and aliases.

Connection Aliases

Create shortcuts for frequently used connections.

Adding Aliases

bayesian-ssh alias add p1 Portail01
bayesian-ssh alias add db prod-database
bayesian-ssh alias add staging Portail-staging

Using Aliases

Aliases work transparently with the connect command:

bayesian-ssh connect p1        # Connects to Portail01
bayesian-ssh connect db        # Connects to prod-database

Listing Aliases

# List all aliases
bayesian-ssh alias list

# List aliases for a specific connection
bayesian-ssh alias list Portail01

Removing Aliases

bayesian-ssh alias remove p1

Bastion Hosts

Bayesian SSH provides flexible bastion (jump host) management for enterprise and cloud environments.

Default Bastion

Set a default bastion that all connections will use automatically:

bayesian-ssh config --default-bastion bastion.company.com

Connections added after this will route through the default bastion unless overridden.

Direct Connections (Bypassing Bastion)

Force a direct connection, bypassing the default bastion:

# At connection creation
bayesian-ssh add "Cloud Server" cloud.company.com --no-bastion

# At connection time
bayesian-ssh connect "Cloud Server" --no-bastion

Custom Bastion per Connection

Override the default bastion with a specific one:

bayesian-ssh add "DMZ Server" dmz.company.com \
  --bastion dmz-bastion.company.com

Mixed Environment Example

# Internal servers (use default bastion automatically)
bayesian-ssh add "App Server" app.company.com --tags internal,production

# Cloud servers (direct connection)
bayesian-ssh add "Cloud App" cloud.company.com --no-bastion --tags cloud,production

# Special network (custom bastion)
bayesian-ssh add "Special Server" special.company.com \
  --bastion special-bastion.company.com \
  --tags special,production

Bastion Troubleshooting

Test Bastion Connectivity

ssh -t -A -K user@bastion.company.com

Override Bastion User

bayesian-ssh connect "Target Server" --bastion-user customuser

Check Connection Configuration

bayesian-ssh show "Server Name"

TUI Mode

Launch a full-screen terminal interface for browsing and managing connections:

bayesian-ssh tui

Keybindings

Features

Detail Pane

Press Enter or d on a connection to open a side panel showing:

• All connection fields
• Full SSH command preview
• Contextual hints

Inline Editing

Press e to edit any connection directly from the TUI:

• 8-field overlay with cursor navigation
• Changes are written back to the database on save

Sorting

• Press s to cycle through sort fields: Name, Host, Last Used, Created
• Press S to toggle ascending/descending order
• The current sort indicator is shown in the header

Compact View

Press v to toggle between:

• Single-line rows - compact view showing key info
• Two-line rows - expanded view with more detail

Visual Indicators

• [B] badge indicates bastion host is configured
• [K] badge indicates Kerberos is enabled
• Alternating row backgrounds for readability
• Mode-coloured status bar

TUI Logging

When the TUI is active, tracing output is routed to ~/.local/share/bayesian-ssh/tui.log to prevent log lines from corrupting the terminal display.

Import & Export

Import from SSH Config

Import existing connections from your ~/.ssh/config file:

# Import from default location
bayesian-ssh import

# Import from a specific file
bayesian-ssh import --file /path/to/ssh/config

This reads your SSH config and creates Bayesian SSH connections for each host entry, preserving hostname, user, port, identity file, and proxy settings.

Export Connections

Export your connections for sharing or backup:

bayesian-ssh export

Enterprise Environments

Enterprise Bastion Configuration

Default Configuration

# Set up default enterprise configuration
bayesian-ssh config \
  --default-user currentuser \
  --default-bastion bastion-server.company.priv \
  --use-kerberos

# Add production servers with tags (will use default bastion)
bayesian-ssh add "Web Prod" web-prod.company.com --tags production,web
bayesian-ssh add "DB Prod" db-prod.company.com --tags production,database
bayesian-ssh add "App Prod" app-prod.company.com --tags production,application

# Quick connection to production
bayesian-ssh connect "Web Prod"

Bastion Management Strategies

1. Default Bastion for Internal Servers

# These will automatically use your default bastion
bayesian-ssh add "Internal Web" internal-web.company.com --tags internal,production
bayesian-ssh add "Internal DB" internal-db.company.com --tags internal,production

2. Direct Connections for Cloud Instances

# Force direct connection, bypassing default bastion
bayesian-ssh add "EC2 Web" ec2-web.company.com \
  --user ubuntu \
  --kerberos false \
  --key ~/.ssh/ec2-key.pem \
  --no-bastion \
  --tags ec2,production,web

3. Custom Bastion for Specific Networks

# Override default bastion with specific one
bayesian-ssh add "DMZ Server" dmz.company.com \
  --bastion dmz-bastion.company.com \
  --tags dmz,production

4. Mixed Environment Setup

# Internal servers (use default bastion)
bayesian-ssh add "App Server" app.company.com --tags internal,production

# Cloud servers (direct connection)
bayesian-ssh add "Cloud App" cloud.company.com --no-bastion --tags cloud,production

# Special network (custom bastion)
bayesian-ssh add "Special Server" special.company.com \
  --bastion special-bastion.company.com \
  --tags special,production

Multi-Environment Management

# Development environment
bayesian-ssh add "Web Dev" web-dev.company.com \
  --user dev-user \
  --bastion dev-bastion.company.com \
  --tags development,web

# Staging environment
bayesian-ssh add "Web Staging" web-staging.company.com \
  --user staging-user \
  --bastion staging-bastion.company.com \
  --tags staging,web

# Production environment
bayesian-ssh add "Web Prod" web-prod.company.com \
  --user prod-user \
  --bastion prod-bastion.company.com \
  --tags production,web

# List by environment
bayesian-ssh list --tag production
bayesian-ssh list --tag development

Network Segmentation

DMZ Servers

# Web servers in DMZ
bayesian-ssh add "DMZ Web" dmz-web.company.com \
  --user web-user \
  --kerberos false \
  --tags dmz,web,production

# API servers in DMZ
bayesian-ssh add "DMZ API" dmz-api.company.com \
  --user api-user \
  --kerberos false \
  --tags dmz,api,production

Internal Network

# Internal application servers
bayesian-ssh add "Internal App" internal-app.company.com \
  --user app-user \
  --bastion internal-bastion.company.com \
  --tags internal,application,production

# Database servers
bayesian-ssh add "Internal DB" internal-db.company.com \
  --user db-user \
  --bastion internal-bastion.company.com \
  --tags internal,database,production

High Availability and Load Balancing

Load Balancer Backends

# Primary load balancer
bayesian-ssh add "LB Primary" lb-primary.company.com \
  --user currentuser \
  --tags loadbalancer,primary,production

# Secondary load balancer
bayesian-ssh add "LB Secondary" lb-secondary.company.com \
  --user currentuser \
  --tags loadbalancer,secondary,production

# Backend servers
bayesian-ssh add "Backend 1" backend-1.company.com \
  --user app-user \
  --bastion lb-primary.company.com \
  --tags backend,production,web

bayesian-ssh add "Backend 2" backend-2.company.com \
  --user app-user \
  --bastion lb-secondary.company.com \
  --tags backend,production,web

Backup and Recovery

# Primary backup server
bayesian-ssh add "Backup Primary" backup-primary.company.com \
  --user backup \
  --kerberos true \
  --tags backup,primary,production

# Secondary backup server
bayesian-ssh add "Backup Secondary" backup-secondary.company.com \
  --user backup \
  --kerberos true \
  --tags backup,secondary,production

# Disaster recovery server
bayesian-ssh add "DR Server" dr.company.com \
  --user dr-user \
  --kerberos true \
  --tags disaster-recovery,production

Cloud Infrastructure

AWS EC2

Direct EC2 Instances

# Web server instance
bayesian-ssh add "Web EC2" ec2-web.company.com \
  --user ubuntu \
  --kerberos false \
  --key ~/.ssh/ec2-web-key.pem \
  --tags ec2,production,web

# Database instance
bayesian-ssh add "DB EC2" ec2-db.company.com \
  --user ec2-user \
  --kerberos false \
  --key ~/.ssh/ec2-db-key.pem \
  --tags ec2,production,database

# Application instance
bayesian-ssh add "App EC2" ec2-app.company.com \
  --user currentuser \
  --kerberos false \
  --key ~/.ssh/ec2-app-key.pem \
  --tags ec2,production,application

EC2 via Bastion (Private Subnets)

# Private subnet instances
bayesian-ssh add "Private Web" private-web.company.com \
  --user ubuntu \
  --kerberos false \
  --key ~/.ssh/private-key.pem \
  --bastion bastion.company.com \
  --tags ec2,private,production,web

# VPC instances
bayesian-ssh add "VPC App" vpc-app.company.com \
  --user ec2-user \
  --kerberos false \
  --key ~/.ssh/vpc-key.pem \
  --bastion vpc-bastion.company.com \
  --tags ec2,vpc,production,application

Multi-Cloud Setup (AWS + Azure + GCP)

# AWS instances (direct connection)
bayesian-ssh add "AWS Web" aws-web.company.com \
  --user ubuntu \
  --kerberos false \
  --key ~/.ssh/aws-key.pem \
  --no-bastion \
  --tags aws,production,web

# Azure VMs (direct connection)
bayesian-ssh add "Azure DB" azure-db.company.com \
  --user azureuser \
  --kerberos false \
  --key ~/.ssh/azure-key.pem \
  --no-bastion \
  --tags azure,production,database

# GCP instances (direct connection)
bayesian-ssh add "GCP App" gcp-app.company.com \
  --user gcp-user \
  --kerberos false \
  --key ~/.ssh/gcp-key.pem \
  --no-bastion \
  --tags gcp,production,application

Kubernetes and Container Environments

Pod Access

# Access to Kubernetes pods
bayesian-ssh add "K8s Web Pod" web-pod.namespace.svc.cluster.local \
  --user root \
  --kerberos false \
  --tags kubernetes,pod,web

# Service access
bayesian-ssh add "K8s Service" web-service.namespace.svc.cluster.local \
  --user currentuser \
  --kerberos false \
  --tags kubernetes,service,web

Docker Containers

# Development container
bayesian-ssh add "Dev Container" dev-container.company.com \
  --user developer \
  --port 2222 \
  --kerberos false \
  --tags docker,development

# Production container
bayesian-ssh add "Prod Container" prod-container.company.com \
  --user operator \
  --port 2222 \
  --kerberos false \
  --tags docker,production

Development Workflows

Feature Branch Development

# Feature development server
bayesian-ssh add "Feature Dev" feature-dev.company.com \
  --user developer \
  --bastion dev-bastion.company.com \
  --tags development,feature

# Integration testing
bayesian-ssh add "Integration Test" integration.company.com \
  --user tester \
  --bastion test-bastion.company.com \
  --tags testing,integration

# Staging for QA
bayesian-ssh add "QA Staging" qa-staging.company.com \
  --user qa-user \
  --bastion qa-bastion.company.com \
  --tags testing,staging,qa

CI/CD Pipeline Access

# Jenkins server
bayesian-ssh add "Jenkins" jenkins.company.com \
  --user jenkins \
  --kerberos false \
  --tags ci,jenkins,production

# GitLab server
bayesian-ssh add "GitLab" gitlab.company.com \
  --user git \
  --kerberos false \
  --tags ci,gitlab,production

# Artifactory server
bayesian-ssh add "Artifactory" artifactory.company.com \
  --user artifact \
  --kerberos false \
  --tags ci,artifactory,production

Environment Workflow

Use tags to organize connections by environment and quickly switch contexts:

# Add servers for each environment
bayesian-ssh add "Web Dev" web-dev.company.com --tags development,web
bayesian-ssh add "Web Staging" web-staging.company.com --tags staging,web
bayesian-ssh add "Web Prod" web-prod.company.com --tags production,web

# List all development servers
bayesian-ssh list --tag development

# List all staging servers
bayesian-ssh list --tag staging

# Quickly connect to any environment
bayesian-ssh connect "Web Dev"
bayesian-ssh connect "Web Staging"
bayesian-ssh connect "Web Prod"

Troubleshooting Connections

# Test basic connectivity
bayesian-ssh connect "Test Server" --debug

# Test with specific user
bayesian-ssh connect "Test Server" --user test-user

# Test with specific key
bayesian-ssh connect "Test Server" --key ~/.ssh/test-key

Security & Compliance

Kerberos Authentication

Bayesian SSH integrates with Kerberos for enterprise authentication:

# Enable Kerberos by default
bayesian-ssh config --use-kerberos

# Per-connection Kerberos
bayesian-ssh add "Secure Server" secure.company.com --kerberos true

Kerberos Ticket Management

# Check current ticket status
klist

# Create new forwardable ticket
kinit -f -A

# Verify ticket creation
klist -s

Bayesian SSH will automatically verify tickets before connecting and create new ones when needed.

Audit and Monitoring

# Audit servers
bayesian-ssh add "Audit Server" audit.company.com \
  --user auditor \
  --kerberos true \
  --tags audit,compliance,production

# Monitoring servers
bayesian-ssh add "Monitoring" monitoring.company.com \
  --user monitor \
  --kerberos true \
  --tags monitoring,production

# Log servers
bayesian-ssh add "Log Server" logs.company.com \
  --user logger \
  --kerberos true \
  --tags logging,production

Compliance Environments

SOX Compliance

bayesian-ssh add "SOX Server" sox.company.com \
  --user sox-user \
  --kerberos true \
  --tags sox,compliance,production

PCI Compliance

bayesian-ssh add "PCI Server" pci.company.com \
  --user pci-user \
  --kerberos true \
  --tags pci,compliance,production

HIPAA Compliance

bayesian-ssh add "HIPAA Server" hipaa.company.com \
  --user hipaa-user \
  --kerberos true \
  --tags hipaa,compliance,production

Security Features

Authentication

• Kerberos integration - Enterprise authentication with automatic ticket management
• SSH key management - Secure key handling per connection
• Bastion support - Secure jump host connections

Access Control

• Audit logging - Complete connection history with timestamps and outcomes
• Tag-based organization - Categorize servers by compliance requirements
• Session tracking - Monitor active sessions with PID-level tracking

Best Practices

1. Always use Kerberos for internal/enterprise servers
2. Use separate SSH keys per environment (dev, staging, production)
3. Route internal servers through bastion hosts
4. Review session history regularly with bayesian-ssh history
5. Use --force carefully on destructive operations
6. Backup your database regularly with bayesian-ssh backup

Performance Optimization

Connection Pooling

# High-performance servers
bayesian-ssh add "Perf Server 1" perf-1.company.com \
  --user perf-user \
  --kerberos false \
  --tags performance,production

bayesian-ssh add "Perf Server 2" perf-2.company.com \
  --user perf-user \
  --kerberos false \
  --tags performance,production

Load Distribution

# Round-robin load distribution
bayesian-ssh add "Load 1" load-1.company.com \
  --user load-user \
  --kerberos false \
  --tags load,production

bayesian-ssh add "Load 2" load-2.company.com \
  --user load-user \
  --kerberos false \
  --tags load,production

bayesian-ssh add "Load 3" load-3.company.com \
  --user load-user \
  --kerberos false \
  --tags load,production

Database Optimization

Bayesian SSH uses SQLite with several optimizations:

• Indexed queries - Fast lookups by name and tags
• Connection pooling - Efficient database connection reuse
• Batch operations - Grouped database operations for bulk changes

Memory Management

The Rust implementation provides:

• Zero-copy operations - Minimized memory allocations
• Efficient serialization - Fast JSON operations via serde
• Resource cleanup - Proper cleanup of file descriptors and processes

Release Build Optimizations

The release binary is built with:

• opt-level=3 - Maximum optimization
• Thin LTO - Link-time optimization
• Single codegen unit - Better whole-program optimization
• Stripped symbols - Smaller binary size
• panic=abort - Reduced binary size

Monitoring Connection Performance

# Check latency
bayesian-ssh ping "Server Name"

# View connection statistics
bayesian-ssh stats

# Review session history for patterns
bayesian-ssh history --days 30

Technical Architecture

Overview

Bayesian SSH is built with a modular architecture that separates concerns and provides a clean, maintainable codebase.

Core Components

1. CLI Layer (src/cli/)

• Command parsing: Uses clap for robust command-line argument handling
• Command modules: Each command is implemented in its own module
• Shell completions: Automatic generation for bash, zsh, fish, and more
• Shared utilities: Common CLI patterns extracted into src/cli/utils.rs

2. Configuration Management (src/config/)

• AppConfig: Central configuration structure
• File-based config: JSON configuration stored in ~/.config/bayesian-ssh/
• Environment overrides: Support for environment variable configuration

3. Data Models (src/models/)

• Connection: Represents SSH connection configuration
• Session: Tracks active SSH sessions
• Serialization: Full serde support for JSON operations

4. Database Layer (src/database/)

• SQLite integration: Using rusqlite for data persistence
• Modular design: Split into submodules - connection, alias, session, search
• Migration support: Schema versioning and updates

5. Services (src/services/)

• SSH Service: Core SSH connection logic
• Kerberos integration: Automatic ticket management
• Process management: Safe process spawning and monitoring

6. TUI (src/tui/)

• ratatui-based: Full-screen terminal interface
• Application state: Managed in app.rs
• Rendering: UI layout and drawing in ui.rs

Database Schema

Connections Table

CREATE TABLE connections (
    id TEXT PRIMARY KEY,
    name TEXT NOT NULL UNIQUE,
    host TEXT NOT NULL,
    user TEXT NOT NULL,
    port INTEGER NOT NULL,
    bastion TEXT,
    bastion_user TEXT,
    use_kerberos BOOLEAN NOT NULL,
    key_path TEXT,
    created_at TEXT NOT NULL,
    last_used TEXT,
    tags TEXT NOT NULL
);

Sessions Table

CREATE TABLE sessions (
    id TEXT PRIMARY KEY,
    connection_id TEXT NOT NULL,
    started_at TEXT NOT NULL,
    ended_at TEXT,
    status TEXT NOT NULL,
    pid INTEGER,
    exit_code INTEGER
);

Connection Workflow

1. Parse command line arguments
2. Load application configuration
3. Search for connection in database (Bayesian-ranked or fuzzy)
4. Check aliases if no direct match
5. Verify Kerberos ticket (if enabled)
6. Automatically create ticket if needed
7. Build SSH command with proper flags
8. Execute SSH process
9. Monitor session status
10. Update database with results
11. Handle cleanup on exit

Error Handling

Error Types

• Configuration errors: Invalid settings or missing files
• Database errors: Connection issues or schema problems
• SSH errors: Connection failures or authentication issues
• Kerberos errors: Ticket creation or renewal failures

Error Recovery

• Graceful degradation: Fallback to basic SSH if features fail
• Automatic retry: Retry failed operations with exponential backoff
• User feedback: Clear error messages with suggested solutions

Performance Considerations

Database Optimization

• Indexed queries for fast lookups by name and tags
• Efficient connection reuse
• Batch operations for grouped database operations

Memory Management

• Zero-copy operations to minimize memory allocations
• Efficient serialization with serde
• Proper cleanup of file descriptors and processes

Security Features

Kerberos Integration

• Ticket verification before use
• Automatic renewal when needed
• Forwardable ticket support

SSH Security

• Secure handling of SSH keys
• Bastion host support for jump connections
• Safe process spawning and monitoring

Testing Strategy

Unit Tests

• Model validation and data structure integrity
• Service logic tested in isolation
• Error condition and recovery testing

Integration Tests

• Full database workflow testing
• SSH connection testing
• Configuration file handling

Future Architecture

Plugin System

• Extension points with hook system for custom functionality
• Stable plugin API for third-party extensions
• Runtime plugin loading and management

API Layer

• REST API for remote management
• WebSocket support for real-time session monitoring
• Secure API access control

Troubleshooting

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/

Changelog

All notable changes to Bayesian SSH will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[1.4.0] - 2026-03-05

Added

• New commands: bssh backup, bssh restore, bssh duplicate, bssh env, bssh export, bssh groups, bssh ping — expand the CLI with backup/restore, connection cloning, environment management, export, grouping, and latency checks
• Multi-environment configuration: Manage separate configs per environment with the --env flag; environment name shown in TUI header and logs
• TUI detail pane: Side panel (toggled with Enter/d) displaying all connection fields, full SSH command preview, and contextual hints
• TUI inline editing: Edit any connection directly from the TUI with e — 8-field overlay with cursor navigation, written back to the database on save
• TUI sorting: Cycle sort field with s (Name -> Host -> Last Used -> Created) and toggle direction with S; indicator shown in header
• TUI compact view: Toggle single-line vs two-line row display with v
• Optimized release profile: opt-level=3, thin LTO, single codegen unit, stripped symbols, panic=abort

Changed

• Database module split: database/ refactored into separate submodules (connection, alias, session, search) for better organisation
• Core error handling: Internal refactoring of error types and propagation across modules
• TUI visual refresh: Alternating row backgrounds, [B]/[K] bastion/Kerberos badges, mode-coloured status bar badge, improved help overlay (50-col popup)

Fixed

• TUI log corruption: Tracing output is now routed to ~/.local/share/bayesian-ssh/tui.log when the TUI is active, preventing log lines from corrupting the alternate-screen display

Removed

• SCP command: Removed bssh scp and the associated config fields bastion_scp_mode and bastion_scp_wrapper

[1.3.2] - 2025-12-31

Fixed

• Log level configuration ignored: The log_level setting in config file was not being applied because logging was initialized before loading the configuration. Now the config is loaded first and the tracing subscriber respects the configured log level (trace, debug, info, warn, error, off/none).

[1.3.1] - 2025-12-30

Added

• Bayesian-ranked search: Smart connection ranking combining:
  • Prior probability (usage frequency with Laplace smoothing)
  • Likelihood (match quality: exact, prefix, word-boundary, contains)
  • Recency (exponential decay based on last use)
  • Success rate (connections that work get boosted)
• Configurable search mode (bssh config --search-mode bayesian|fuzzy)
  • bayesian: Smart ranking based on usage patterns (default)
  • fuzzy: Simple pattern matching
• Assets: SVG icons, banner, architecture and workflow diagrams

Changed

• Default search mode is now “bayesian” for smarter results

[1.3.0] - 2025-12-30

Added

• Interactive TUI mode (bssh tui): Full-screen terminal interface with ratatui
  • Browse, search, and connect to servers
  • Keyboard navigation (vim-style j/k, arrows, PgUp/PgDn)
  • Tag filtering, help overlay, confirmation dialogs
• Session history command (bssh history): View connection history with statistics
  • Success/failure rates, average duration
  • Filter by connection, days, failed-only
• Connection aliases (bssh alias): Create shortcuts for connections
  • bssh alias add db prod-database -> bssh connect db
  • Aliases work transparently with connect command
• Close/kill sessions (bssh close): Manage active SSH sessions
  • List active sessions with PID and stale detection
  • Close specific sessions or all at once
  • --cleanup to remove stale sessions (PIDs no longer running)
• Configurable search mode (bssh config --search-mode bayesian|fuzzy)
  • bayesian: Smart ranking based on usage patterns (default)
  • fuzzy: Simple pattern matching

Changed

• Connect command now checks aliases before fuzzy search
• Session tracking improved with accurate active/stale detection
• Default search mode is now “bayesian” for smarter results

Dependencies

• Added ratatui and crossterm for TUI
• Enabled signal feature in nix for process management

[1.2.0] - 2025-12-22

Added

• --force flag for remove command: Skip confirmation prompt with -f or --force
• --clear-bastion flag for config command: Clear default bastion settings
• Shared CLI utilities module: New src/cli/utils.rs for consistent UX across commands
• Working “search again” feature: The ‘s’ option in interactive selection now performs actual recursive search
• Contextual help messages: Suggestions like “Use ‘bssh list’ to see all connections” when no matches found

Changed

• Single-match auto-connect: Connect and show commands now auto-select when only one fuzzy match is found (improved UX)
• Default yes for non-destructive operations: Confirmation prompts now default to Yes [Y/n] for show/connect
• Simplified remove confirmation: Changed from typing full connection name to simple y/n prompt (use --force to skip)

Fixed

• Config update bug: Fixed double-wrapping of Option<Option<String>> for bastion settings that prevented clearing values
• DateTime parsing panic: Graceful handling of malformed dates in database instead of crashing
• Home directory panic: Better error message when $HOME is not set during SSH config import

Technical

• Major code deduplication: Extracted ~300 lines of duplicated code from connect.rs, edit.rs, remove.rs, show.rs into shared utilities
• Reduced file sizes: connect.rs (257->65 lines), edit.rs (360->70 lines), remove.rs (235->70 lines), show.rs (246->35 lines)

[1.1.1] - 2025-08-29

Fixed

• Configuration defaults: Changed default user from hardcoded “admin” to current system user
• Kerberos default: Disabled Kerberos by default (changed from true to false)
• Documentation: Updated all examples to reflect new sensible defaults

Changed

• Default configuration: Application now uses current Linux username instead of “admin”
• Kerberos behavior: Kerberos authentication is now opt-in rather than default
• Documentation examples: Updated configuration commands and JSON examples across all docs

Technical

• Dependencies: Added whoami crate for system user detection
• Configuration: Updated AppConfig::default() implementation

[1.1.0] - 2025-08-28

Added

• Intelligent fuzzy search across all commands - Find connections by partial names, tags, or patterns
  • Enhanced connect command with fuzzy search and interactive selection
  • Enhanced edit command with fuzzy search for connection management
  • Enhanced show command with fuzzy search for connection details
  • Enhanced remove command with fuzzy search and extra confirmation

Fuzzy Search Features

• Smart pattern matching: Handles hyphens, underscores, and separators (webprod -> web-prod-server)
• Tag-based search: Search within connection tags
• Recent connections fallback: Shows recently used connections when no matches found
• Interactive selection: Numbered menus for multiple matches with user-friendly prompts
• Relevance ranking: Prioritizes recently used and exact matches

Enhanced Safety

• Extra confirmation for destructive operations: remove command requires typing full connection name
• Graceful error handling: Clear messages and helpful suggestions
• Backwards compatibility: All existing functionality preserved

Technical Improvements

• Enhanced database layer with fuzzy search algorithms
• Improved error handling and user feedback
• Better code organization and maintainability

[1.0.0] - 2024-08-23

Added

• Initial release of Bayesian SSH
• Basic SSH connection management
• Kerberos authentication support
• Bastion host routing
• Tag-based organization
• SQLite database persistence
• Connection history and statistics

Core Features

• One-click connections to servers
• Automatic Kerberos ticket management
• Smart bastion host routing
• Tag-based organization for easy management
• Complete connection history with statistics
• SQLite database for persistence