This directory contains detailed architecture documentation for bssh (Backend.AI SSH), organized by component.
bssh is a high-performance parallel SSH command execution tool with SSH-compatible interface. For a high-level overview, see Main Architecture.
- CLI Interface - Command-line interface, pdsh compatibility, hostlist expressions, mode detection
- Configuration Management - Configuration loading, XDG support, environment variable expansion
- Parallel Executor - Concurrent execution, signal handling, fail-fast mode
- SSH Client - SSH connections, authentication, command execution, streaming output
- Terminal User Interface (TUI) - Interactive TUI with views, event handling, progress parsing
- Interactive Mode - PTY implementation, single/multiplex modes, control sequences
- SSH Configuration Parser - SSH config file parsing, Include/Match directives, caching
- SSH Jump Host Support - Jump host chains, authentication, tunnel management
- SSH Port Forwarding - Local, remote, and dynamic (SOCKS) forwarding
- Exit Code Strategy - Main rank detection, exit code strategies, MPI compatibility
- Server Configuration - YAML-based server configuration, environment overrides, validation, SCP protocol handler
- Server CLI (
bssh-server) - Server management commands including host key generation, password hashing, config validation (see main ARCHITECTURE.md) - SSH Server Module - SSH server implementation using russh (see main ARCHITECTURE.md)
- Server Authentication - Authentication providers including public key verification (see main ARCHITECTURE.md)
- SFTP Handler - SFTP subsystem with path traversal prevention and chroot-like isolation (see main ARCHITECTURE.md)
- SCP Handler - SCP protocol with sink/source modes and security controls (see main ARCHITECTURE.md)
- Audit Logging - Audit event types, exporters, and async event processing (see main ARCHITECTURE.md)
Each component document includes:
- Overview - Component purpose and capabilities
- Architecture - Design decisions and structure
- Implementation Details - Code organization and patterns
- Integration Points - How components interact
- Related Documentation - Links to related docs
- CLI options and modes → CLI Interface
- Client configuration file format → Configuration Management
- Server configuration file format → Server Configuration
- Server CLI commands → Main ARCHITECTURE.md (Server CLI Binary section)
- Parallel execution behavior → Parallel Executor
- SSH connection details → SSH Client
- Interactive terminal usage → TUI or Interactive Mode
- Jump host setup → SSH Jump Host Support
- Port forwarding → SSH Port Forwarding
- Exit code behavior → Exit Code Strategy
src/
├── bin/
│ └── bssh_server.rs → Server CLI Binary (bssh-server)
├── cli/ → CLI Interface
├── config/ → Configuration Management
├── executor/ → Parallel Executor
├── ssh/ → SSH Client
├── tui/ → Terminal User Interface
├── interactive/ → Interactive Mode
├── jump/ → Jump Host Support
├── forward/ → Port Forwarding
├── server/ → SSH Server (handler, session, config/, auth/, audit/)
├── shared/ → Shared utilities (validation, rate limiting, auth types, errors)
├── security/ → Security utilities (re-exports from shared for compatibility)
└── commands/ → Command Implementations
When updating architecture documentation:
- Focus on current state - Describe how things work now, not how they evolved
- Avoid changelog content - Don't include dates, issue numbers, or version references
- Keep examples practical - Show real-world usage
- Maintain cross-references - Link to related documentation
- Update the main ARCHITECTURE.md - Keep the overview in sync
For detailed implementation notes, see the code comments and rustdoc documentation.