Skip to content

wsssh
wsssh
Commit b7dae7b4 authored by Stefy Lanza (nextime / spora )'s avatar Stefy Lanza (nextime / spora )
Browse files
Options

docs: Rewrite documentation and README with updated project description 

- Update project description from WebSocket-based to universal tunneling system
- Rewrite README.md with comprehensive features, installation, and examples
- Rewrite DOCUMENTATION.md with detailed technical specifications
- Update TODO.md with current project status and future enhancements
- Ensure all command-line examples are accurate and exclude hidden options
- Maintain consistency across all documentation files
parent 561b47d4
Hide whitespace changes
Inline Side-by-side
Showing with 417 additions and 1272 deletions
DOCUMENTATION.md
View file @ b7dae7b4
# WSSSH: Warp-Powered Stefy's Spatial Secure Hyperdrive Documentation # WSSSH: Warp-Powered Stefy's Spatial Secure Hyperdrive - Technical Documentation
## Table of Contents ## Table of Contents
...@@ -15,69 +15,57 @@ ...@@ -15,69 +15,57 @@
## Overview ## Overview
wsssh is a swiss army's knife server assisted tunnelling system for the win initially born as a websocket ssh tunnelling system and evolved to a universal tunnelling utility WSSSH is a universal tunneling system that provides secure access to remote machines through various transport protocols. The system consists of multiple components implemented in both Python and C, offering high performance and flexibility for different deployment scenarios.
### Key Components ### Key Components
#### Server Component #### Server Component
- **wssshd**: WSSH Daemon - Central server with web interface (Python) - **wssshd**: Universal tunneling daemon (Python) with web interface
- **WebSocket/Transport Support**: Multiple transport protocol implementations
- **Client Management**: Registration and authentication system
- **Tunnel Routing**: Intelligent request routing to registered clients
#### C Implementation (Primary) #### C Implementation (Primary)
- **wssshc**: Lightweight C client for registration (OpenSSL-based) - **wssshc**: Lightweight C client for registration (OpenSSL-based)
- **wsssh**: Native SSH wrapper with direct system integration - **wsssh**: Native SSH wrapper with direct system integration
- **wsscp**: Native SCP wrapper optimized for file transfers - **wsscp**: Native SCP wrapper optimized for file transfers
- **wsssht**: Tunnel setup tool for manual connections
### Core Features ### Core Features
- **C Implementation**: Lightweight and efficient C versions - **Universal Transport Support**: WebSocket and extensible transport architecture
- **Intelligent Hostname Parsing**: Automatic detection of client IDs and server endpoints - **Intelligent Hostname Parsing**: Automatic client ID and server endpoint detection
- **SSL/TLS Encryption**: Secure WebSocket communications with OpenSSL - **SSL/TLS Encryption**: Secure communications with OpenSSL
- **Multi-client Support**: Route connections to different registered clients - **Multi-client Architecture**: Route connections to different registered clients
- **Simplified CLI**: No need to specify "ssh" or "scp" commands explicitly - **Simplified CLI**: Drop-in replacements for SSH/SCP commands
- **Drop-in Replacement**: Compatible with existing SSH/SCP workflows - **Debian Packaging**: Professional system integration
- **Debian Packaging**: Professional system integration with dependencies - **Service Management**: Complete init scripts and watchdog monitoring
- **wsssh-server Package**: Standalone Debian package for wssshd daemon - **Advanced Logging**: Automatic log rotation and monitoring
- **PyInstaller Binary**: Standalone wssshd binary with no Python dependencies
- **Professional Service Management**: Complete init scripts and service integration
- **Dynamic Terminal Sizing**: Web terminal automatically adjusts to browser dimensions
- **Real-time Resize Support**: Terminal resizes dynamically with browser window
- **Force Echo Mode**: SSH connections force echo mode for better visibility
- **Enhanced Logging**: Complete logrotate integration for daemon processes
- **SSL Connection Stability**: Advanced SSL error handling and connection resilience
- **Process Exit Handling**: Fixed critical process hanging issues
- **Code Architecture**: Modular design with shared libraries for better maintainability
- **Cross-platform**: Works on Linux, macOS, and Windows
- **Multiple Operating Modes**: Interactive, silent, bridge, script, and daemon modes - **Multiple Operating Modes**: Interactive, silent, bridge, script, and daemon modes
- **Bridge Mode**: JSON-based communication over stdin/stdout for programmatic use - **Enterprise Reliability**: Production-grade process supervision
- **Script Mode**: JSON protocol with status updates and command processing
- **Daemon Mode**: Lazy tunnel initialization for resource efficiency
- **Donation Support**: Community funding through PayPal and cryptocurrency
## Operating Modes ## Operating Modes
wsssht supports multiple operating modes to accommodate different use cases and integration requirements: WSSSH supports multiple operating modes to accommodate different use cases:
### Interactive Mode (Default) ### Interactive Mode (Default)
The standard operating mode providing full interactive SSH/SCP sessions with user-friendly output and progress indicators. Standard interactive SSH/SCP sessions with full user interface and progress indicators.
### Silent Mode ### Silent Mode
```bash ```bash
wsssht --silent --clientid myclient --wssshd-host example.com wsssht --silent --clientid myclient --wssshd-host example.com
``` ```
Suppresses all informational output, making it ideal for automation scripts and background operations where only error messages should be displayed. Suppresses all informational output, perfect for automation and background operations.
### Bridge Mode ### Bridge Mode
```bash ```bash
wsssht --bridge --clientid myclient --wssshd-host example.com wsssht --bridge --clientid myclient --wssshd-host example.com
``` ```
Provides a JSON-based interface for programmatic integration: Provides JSON-based interface for programmatic integration:
- Receives JSON commands from stdin - Receives JSON commands from stdin
- Sends JSON status updates and responses to stdout - Sends JSON status updates and responses to stdout
- **Tunnel control channel messages are communicated through stdin/stdout** (JSON protocol)
- **Tunnel data channel messages remain handled by wsssht** (normal forwarding)
- Perfect for integration with other tools and automation frameworks - Perfect for integration with other tools and automation frameworks
- Structured error reporting and connection status updates - Structured error reporting and connection status updates
- External applications can control the tunnel via JSON commands
### Script Mode ### Script Mode
```bash ```bash
...@@ -88,65 +76,77 @@ Designed for scripting environments with: ...@@ -88,65 +76,77 @@ Designed for scripting environments with:
- Periodic status updates (every 30 seconds) - Periodic status updates (every 30 seconds)
- Script command processing (`status`, `quit`, `exit`) - Script command processing (`status`, `quit`, `exit`)
- Timestamped events for monitoring and logging - Timestamped events for monitoring and logging
- Easy parsing by external scripts and monitoring tools
### Daemon Mode ### Daemon Mode
```bash ```bash
wsssht --daemon --clientid myclient --wssshd-host example.com wsssht --daemon --clientid myclient --wssshd-host example.com
``` ```
Implements lazy tunnel initialization: Implements lazy tunnel initialization:
- Waits for the first connection attempt before establishing the tunnel - Waits for first connection attempt before establishing tunnel
- Reduces resource usage for intermittent connections - Reduces resource usage for intermittent connections
- Maintains full functionality after tunnel establishment - Maintains full functionality after tunnel establishment
- Ideal for resource-constrained environments
## Architecture ## Architecture
### System Architecture ### System Architecture
``` ```
┌─────────────────┐ WebSocket (WSS) ┌─────────────────┐ ┌─────────────────┐ Transport Layer ┌─────────────────┐
│ SSH/SCP │◄────────────────────►│ wssshd │ │ SSH/SCP │◄────────────────────►│ wssshd │
│ Client │ │ (Daemon) │ │ Client │ │ (Daemon) │
└─────────────────┘ └─────────────────┘ └─────────────────┘ └─────────────────┘
│ │
│ WebSocket (WSS) │ Transport Layer
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ wssshc │ │ wssshc │
│ (Client) │ │ (Client) │
│ │ │ │
│ ┌─────────────┐ │ │ ┌─────────────┐ │
│ │ SSH Server │ │ │ │ SSH Server │ │
│ │ (sshd) │ │ │ │ (sshd) │ │
│ └─────────────┘ │ │ └─────────────┘ │
└─────────────────┘ └─────────────────┘
``` ```
### Data Flow ### Data Flow
1. **Registration Phase**: 1. **Registration Phase**:
- wssshc connects to wssshd via WebSocket - wssshc connects to wssshd via selected transport
- Registers with unique client ID - Registers with unique client ID and authentication
- Maintains persistent connection - Maintains persistent connection
2. **Connection Phase**: 2. **Connection Phase**:
- User runs `wsssh user@client.domain` (simplified CLI) - User runs `wsssh user@client.domain` (simplified CLI)
- wsssh parses hostname to extract client ID and server endpoint - wsssh parses hostname to extract client ID and server endpoint
- wsssh connects to wssshd and requests tunnel to client - wsssh connects to wssshd and requests tunnel to client
- wssshd forwards request to appropriate wssshc - wssshd forwards request to appropriate wssshc
- wssshc establishes local tunnel to SSH server - wssshc establishes local tunnel to target service
- wsssh launches SSH client to local tunnel port
3. **Data Transfer Phase**: 3. **Data Transfer Phase**:
- SSH traffic flows: SSH Client ↔ wsssh ↔ wssshd ↔ wssshc ↔ SSH Server - Traffic flows: SSH Client ↔ wsssh ↔ wssshd ↔ wssshc ↔ Target Service
- All WebSocket connections are encrypted with SSL/TLS - All transport connections are encrypted with SSL/TLS
## Protocol Specification ## Protocol Specification
### WebSocket Message Format ### Transport Layer
WSSSH supports multiple transport protocols:
#### WebSocket Transport
- **Protocol**: WebSocket (RFC 6455)
- **Encryption**: SSL/TLS
- **Features**: Bidirectional communication, frame-based messaging
- **Default Transport**: Primary transport implementation
#### Extensible Architecture
- **Transport Plugins**: Modular transport implementation
- **Configuration**: Transport selection via command-line options
- **Negotiation**: Automatic transport negotiation between client and server
### Message Format
All messages are JSON-encoded with the following structure: All control messages use JSON format:
```json ```json
{ {
...@@ -165,7 +165,8 @@ All messages are JSON-encoded with the following structure: ...@@ -165,7 +165,8 @@ All messages are JSON-encoded with the following structure:
```json ```json
{ {
"type": "register", "type": "register",
"id": "client_unique_id" "id": "client_unique_id",
"password": "authentication_password"
} }
``` ```
...@@ -184,7 +185,8 @@ All messages are JSON-encoded with the following structure: ...@@ -184,7 +185,8 @@ All messages are JSON-encoded with the following structure:
{ {
"type": "tunnel_request", "type": "tunnel_request",
"client_id": "target_client_id", "client_id": "target_client_id",
"request_id": "unique_request_uuid" "request_id": "unique_request_uuid",
"service": "ssh"
} }
``` ```
...@@ -192,29 +194,11 @@ All messages are JSON-encoded with the following structure: ...@@ -192,29 +194,11 @@ All messages are JSON-encoded with the following structure:
```json ```json
{ {
"type": "tunnel_ack", "type": "tunnel_ack",
"request_id": "unique_request_uuid"
}
```
**Tunnel Error** (wssshd → wsssh):
```json
{
"type": "tunnel_error",
"request_id": "unique_request_uuid", "request_id": "unique_request_uuid",
"error": "error_description" "local_port": 49234
}
```
**Forward Tunnel Request** (wssshd → wssshc):
```json
{
"type": "tunnel_request",
"request_id": "unique_request_uuid"
} }
``` ```
#### Data Transfer Messages
**Tunnel Data** (bidirectional): **Tunnel Data** (bidirectional):
```json ```json
{ {
...@@ -224,7 +208,7 @@ All messages are JSON-encoded with the following structure: ...@@ -224,7 +208,7 @@ All messages are JSON-encoded with the following structure:
} }
``` ```
**Close Tunnel** (wsssh → wssshd → wssshc): **Close Tunnel** (any → any):
```json ```json
{ {
"type": "tunnel_close", "type": "tunnel_close",
...@@ -234,8 +218,6 @@ All messages are JSON-encoded with the following structure: ...@@ -234,8 +218,6 @@ All messages are JSON-encoded with the following structure:
### Hostname Parsing Algorithm ### Hostname Parsing Algorithm
The hostname parsing follows this algorithm:
``` ```
Input: hostname (e.g., "myclient.example.com:9898") Input: hostname (e.g., "myclient.example.com:9898")
...@@ -255,13 +237,13 @@ Input: hostname (e.g., "myclient.example.com:9898") ...@@ -255,13 +237,13 @@ Input: hostname (e.g., "myclient.example.com:9898")
4. Determine wssshd_port: 4. Determine wssshd_port:
if port_part exists: use port_part if port_part exists: use port_part
elif ssh_port specified: use ssh_port elif config port exists: use config port
else: use 22 (default) else: use 9898 (default)
``` ```
## API Reference ## API Reference
### wssshd (WSSH Daemon) ### wssshd (Universal Tunneling Daemon)
#### Command Line Options #### Command Line Options
...@@ -269,18 +251,18 @@ Input: hostname (e.g., "myclient.example.com:9898") ...@@ -269,18 +251,18 @@ Input: hostname (e.g., "myclient.example.com:9898")
wssshd --host HOST --port PORT --domain DOMAIN --password PASS [--web-host HOST --web-port PORT] [--web-https] [--debug] wssshd --host HOST --port PORT --domain DOMAIN --password PASS [--web-host HOST --web-port PORT] [--web-https] [--debug]
``` ```
- `--host HOST`: Bind address for WebSocket server - `--host HOST`: Bind address for the daemon
- `--port PORT`: WebSocket server port - `--port PORT`: Daemon port
- `--domain DOMAIN`: Domain suffix for hostname parsing - `--domain DOMAIN`: Domain suffix for hostname parsing
- `--password PASS`: Registration password - `--password PASS`: Registration password
- `--web-host HOST`: Web interface host (optional) - `--web-host HOST`: Web interface bind address
- `--web-port PORT`: Web interface port (optional) - `--web-port PORT`: Web interface port
- `--web-https`: Enable HTTPS for web interface - `--web-https`: Enable HTTPS for web interface
- `--debug`: Enable debug output - `--debug`: Enable debug output
#### Configuration File #### Configuration File
wssshd supports a system-wide INI-formatted configuration file at `/etc/wssshd.conf`: wssshd supports `/etc/wssshd.conf`:
```ini ```ini
[wssshd] [wssshd]
...@@ -293,25 +275,7 @@ web-port = 8080 ...@@ -293,25 +275,7 @@ web-port = 8080
web-https = false web-https = false
``` ```
**Configuration Options:** ### wssshc (Client Registration)
- `host`: Default WebSocket server bind address
- `port`: Default WebSocket server port
- `password`: Default registration password
- `domain`: Default domain suffix for hostname parsing
- `web-host`: Default web interface bind address
- `web-port`: Default web interface port
- `web-https`: Enable HTTPS for web interface (true/false)
**Precedence Rules:**
- Command line options override configuration file values
- Configuration file provides defaults when command line options are not specified
- Required parameters must be provided either via command line or configuration file
#### WebSocket Endpoints
- `ws://HOST:PORT/`: Main WebSocket endpoint for client connections
### wssshc (WSSH Client)
#### Command Line Options #### Command Line Options
...@@ -328,217 +292,138 @@ wssshc --server-ip IP --port PORT --id ID --password PASS [--interval SEC] [--de ...@@ -328,217 +292,138 @@ wssshc --server-ip IP --port PORT --id ID --password PASS [--interval SEC] [--de
#### Configuration File #### Configuration File
wssshc supports an optional INI-formatted configuration file at `~/.config/wsssh/wssshc.conf`: wssshc supports `~/.config/wsssh/wssshc.conf`:
```ini ```ini
[wssshc] [wssshc]
password = mysecret password = mysecret
domain = example.com
server-ip = 192.168.1.100 server-ip = 192.168.1.100
port = 9898 port = 9898
id = client1 id = client1
``` ```
**Configuration Options:**
- `password`: Default registration password
- `domain`: Default domain suffix (fallback for server-ip)
- `server-ip`: Default wssshd server IP address
- `port`: Default wssshd server port
- `id`: Default client identifier
**Precedence Rules:**
- Command line options override configuration file values
- Configuration file provides defaults when command line options are not specified
- Required parameters must be provided either via command line or configuration file
#### Enhanced Features (v1.4.6)
**SSH Tunneling Improvements:**
- Enhanced SSH tunnel handling with improved error recovery
- Added specific handling for EBADF (Bad file descriptor) errors
- Improved error handling in handle_tunnel_data for SSH client disconnections
- Removed aggressive socket validation causing SSH client disconnections
- Fixed SSH client socket invalidation issue in handle_tunnel_data
- Added missing SSH client accept() logic in wsssh socket handling
- Fixed SSH tunneling timing issue with proper data buffering
- Implemented correct SSH tunneling architecture for wssshc
- Fixed critical architectural issue in wssshc tunnel handling
- Enhanced error handling for broken SSH connections
**WebSocket Connection Management:**
- Fixed ping frame parsing in C implementations (wsssh.c and wsscp.c)
- Added automatic pong responses with correct payload echoing
- Implemented WebSocket reconnection logic with smart timing
- Added --interval option for configurable connection retry intervals
**Connection Resilience:**
- 1-second intervals for WebSocket reconnection during active tunnels
- 30-second intervals for initial connection setup failures
- Up to 3 automatic reconnection attempts
- Seamless tunnel recovery without disrupting active SSH/SCP sessions
#### Enhanced Features (v1.3.2)
**Improved Debug Output:**
- `[WebSocket]` prefix for WebSocket-level messages and events
- `[TCP Tunnel]` prefix for TCP tunnel-level messages and events
- Clear distinction between protocol layers for better troubleshooting
**Resilient Connection Handling:**
- WebSocket close frames trigger reconnection rather than client removal
- 30-second timeout for expired client registrations on server side
- Better handling of temporary network disconnections
### wsssh (SSH Wrapper) ### wsssh (SSH Wrapper)
#### Command Line Options #### Command Line Options
```bash ```bash
wsssh [--local-port PORT] [--debug] [--dev-tunnel] [--help] user@client.domain [ssh_options...] wsssh [options] user@client.domain [ssh_options...]
``` ```
- `--local-port PORT`: Local tunnel port (default: auto-assign) - `--local-port PORT`: Local tunnel port (default: auto)
- `--tunnel TRANSPORT`: Transport for data channel
- `--tunnel-control TRANSPORT`: Transport for control channel
- `--service SERVICE`: Service type (default: ssh)
- `--debug`: Enable debug output - `--debug`: Enable debug output
- `--dev-tunnel`: Development mode: setup tunnel but don't launch SSH - `--dev-tunnel`: Setup tunnel but don't launch SSH
- `--help`: Display help message and exit
#### Environment Variables
- None
### wsscp (SCP Wrapper) ### wsscp (SCP Wrapper)
#### Command Line Options #### Command Line Options
```bash ```bash
wsscp [--local-port PORT] [--debug] [--dev-tunnel] [--help] [SCP_OPTIONS...] SOURCE... DESTINATION wsscp [options] [scp_options...] source destination
``` ```
- `--local-port PORT`: Local tunnel port (default: auto-assign) - `--local-port PORT`: Local tunnel port (default: auto)
- `--tunnel TRANSPORT`: Transport for data channel
- `--tunnel-control TRANSPORT`: Transport for control channel
- `--service SERVICE`: Service type (default: ssh)
- `--debug`: Enable debug output - `--debug`: Enable debug output
- `--dev-tunnel`: Development mode: setup tunnel but don't launch SCP - `--dev-tunnel`: Setup tunnel but don't launch SCP
- `--help`: Display help message and exit
### C Implementation Tools ### wsssht (Tunnel Setup Tool)
#### wssshc (C Client) #### Command Line Options
```bash ```bash
wssshc --server-ip IP --port PORT --id ID --password PASS [--interval SEC] [--debug] wsssht [--config FILE] [--clientid ID] [--tunnel-port PORT] [--tunnel-host HOST] [--wssshd-host HOST] [--wssshd-port PORT] [--interval SEC] [--debug] [--tunnel TRANSPORT] [--tunnel-control TYPES] [--service SERVICE] [--mode MODE] [--silent] [--bridge] [--script] [--daemon] [--help] [service://]clientid[@wssshd-host][:wssshd-port]
``` ```
- `--server-ip IP`: wssshd server IP address (required) - `--config FILE`: Custom config file
- `--port PORT`: wssshd server port (required) - `--clientid ID`: Client ID for tunnel
- `--id ID`: Unique client identifier (required) - `--tunnel-port PORT`: Local tunnel port (default: auto)
- `--password PASS`: Registration password (required) - `--tunnel-host HOST`: Local bind address (default: 127.0.0.1)
- `--interval SEC`: Reconnection interval in seconds (default: 30) - `--wssshd-host HOST`: wssshd server hostname
- `--wssshd-port PORT`: wssshd server port (default: 9898)
- `--interval SEC`: Connection retry interval (default: 5)
- `--debug`: Enable debug output - `--debug`: Enable debug output
- `--tunnel TRANSPORT`: Data channel transport
#### wsssh (C SSH Wrapper) - `--tunnel-control TYPES`: Control channel transport
- `--service SERVICE`: Service type (default: ssh)
```bash - `--mode MODE`: Operating mode (interactive/silent/bridge/script)
wsssh user@client.domain -p PORT [SSH_OPTIONS...]
wsssh --clientid myclient --wssshd-host example.com [--mode MODE]
```
- `-p PORT`: wssshd server port
- `--local-port PORT`: Local tunnel port (default: auto)
- `--clientid ID`: Client ID for the tunnel (required in new format)
- `--wssshd-host HOST`: wssshd server hostname (required in new format)
- `--mode MODE`: Operating mode (interactive, silent, bridge, script)
- `--silent`: Shortcut for silent mode - `--silent`: Shortcut for silent mode
- `--bridge`: Shortcut for bridge mode - `--bridge`: Shortcut for bridge mode
- `--script`: Shortcut for script mode - `--script`: Shortcut for script mode
- `--daemon`: Enable daemon mode (lazy initialization) - `--daemon`: Enable daemon mode
- `--debug`: Enable debug output - `--help`: Display help message
#### wsscp (C SCP Wrapper) ## Configuration
```bash ### Config File Locations
wsscp [SCP_OPTIONS...] SOURCE... DESTINATION
```
- `-P PORT`: wssshd server port WSSSH uses a hierarchical configuration system:
- `--local-port PORT`: Local tunnel port (default: auto)
- `--debug`: Enable debug output
## Configuration 1. **Command line options** (highest priority)
2. **User configuration**: `~/.config/wsssh/wsssht.conf`
3. **System configuration**: `/etc/wsssht.conf` (lowest priority)
### Config File Configuration ### Configuration Options
WSSH supports an optional INI-formatted configuration file at `~/.config/wsssh/wsssh.conf`: #### wsssht Configuration
```ini
[wsssht]
wssshd-host = example.com
wssshd-port = 9898
clientid = myclient
tunnel-port = 0
tunnel-host = 127.0.0.1
tunnel = websocket
tunnel-control = websocket
service = ssh
interval = 5
mode = interactive
daemon = false
```
#### wsssh/wsscp Configuration
```ini ```ini
[default] [default]
port=8080 port = 9898
domain=example.com domain = example.com
tunnel = websocket
tunnel-control = websocket
service = ssh
``` ```
**Configuration Options:**
- `port`: Default WebSocket server port (used when not specified via `-p`/`-P` options)
- `domain`: Default domain suffix (used when hostname doesn't include domain)
**Precedence Rules:**
- **Port**: Command line `-p`/`-P` options override config file, config file overrides default (22)
- **Domain**: Command line domain (e.g., `user@client.domain`) overrides config domain, config domain overrides localhost
**File Location:**
- **Path**: `~/.config/wsssh/wsssh.conf`
- **Format**: Standard INI format with `[default]` section
- **Permissions**: Readable by the user running wsssh/wsscp
### SSL Certificate Configuration ### SSL Certificate Configuration
The system uses SSL/TLS certificates for WebSocket encryption: The system uses SSL/TLS certificates for encryption:
- **Certificate File**: `cert.pem` (X.509 certificate) - **Certificate File**: `cert.pem` (X.509 certificate)
- **Private Key File**: `key.pem` (RSA/ECDSA private key) - **Private Key File**: `key.pem` (RSA/ECDSA private key)
Certificates are automatically generated during the build process using OpenSSL: Certificates are automatically generated during build:
```bash ```bash
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem \ openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem \
-days 365 -nodes -subj "/C=US/ST=State/L=City/O=Organization/CN=localhost" -days 365 -nodes -subj "/C=US/ST=State/L=City/O=Organization/CN=localhost"
``` ```
### Client Configuration
Each client machine requires:
1. **Unique Client ID**: Identifier for routing connections
2. **Network Access**: Ability to connect to wssshd server
3. **SSH Server**: Running SSH daemon (sshd) on the client machine
### Server Configuration
The wssshd server requires:
1. **Network Interface**: IP address and port for WebSocket connections
2. **Domain Configuration**: Domain suffix for hostname parsing
3. **SSL Certificates**: Valid certificate and private key files
## Logging Configuration ## Logging Configuration
### Log Files and Locations ### Log Files and Locations
WSSH implements comprehensive logging with automatic rotation: WSSSH implements comprehensive logging:
- **wssshd Main Log**: `/var/log/wssshd/wssshd.log`
- Contains all daemon operations, client connections, tunnel requests
- Includes error messages, debug information, and service status
- **wssshc Client Log**: `/var/log/wssshc/wssshc.log`
- Records client registration attempts and connection status
- Logs WebSocket connection events and reconnection attempts
- **Watchdog Logs**: - **wssshd logs**: `/var/log/wssshd/wssshd.log`
- `/var/log/wssshd/watchdog.log` - wssshd process monitoring - **wssshc logs**: `/var/log/wssshc/wssshc.log`
- `/var/log/wssshc/watchdog.log` - wssshc process monitoring - **Watchdog logs**: `/var/log/wssshd/watchdog.log`, `/var/log/wssshc/watchdog.log`
### Logrotate Configuration ### Logrotate Configuration
All log files are managed by logrotate with the following configuration:
```bash ```bash
/var/log/wssshd/wssshd.log { /var/log/wssshd/wssshd.log {
weekly weekly
...@@ -549,55 +434,11 @@ All log files are managed by logrotate with the following configuration: ...@@ -549,55 +434,11 @@ All log files are managed by logrotate with the following configuration:
notifempty notifempty
create 644 wssshd wssshd create 644 wssshd wssshd
postrotate postrotate
if [ -f /var/run/wssshd.pid ]; then systemctl reload wssshd
kill -HUP $(cat /var/run/wssshd.pid) 2>/dev/null || true
fi
endscript
}
/var/log/wssshc/wssshc.log {
weekly
missingok
rotate 52
compress
delaycompress
notifempty
create 644 wssshc wssshc
postrotate
if [ -f /var/run/wssshc.pid ]; then
kill -HUP $(cat /var/run/wssshc.pid) 2>/dev/null || true
fi
endscript endscript
} }
``` ```
### Log Rotation Features
- **Weekly Rotation**: Logs are rotated every week
- **52-Week Retention**: 1 year of log history is maintained
- **Automatic Compression**: Rotated logs are compressed to save disk space
- **Delayed Compression**: First rotated log remains uncompressed for immediate access
- **Permission Management**: Proper file ownership and permissions (644)
- **Signal Handling**: HUP signal sent to daemons after rotation for log reopening
### Manual Log Management
```bash
# Force log rotation
logrotate -f /etc/logrotate.d/wssshd
logrotate -f /etc/logrotate.d/wssshc
# Check logrotate configuration
logrotate -d /etc/logrotate.d/wssshd
# View current logs
tail -f /var/log/wssshd/wssshd.log
tail -f /var/log/wssshc/wssshc.log
# View compressed logs
zcat /var/log/wssshd/wssshd.log.1.gz | less
```
### Log Analysis ### Log Analysis
Key log entries to monitor: Key log entries to monitor:
...@@ -605,45 +446,25 @@ Key log entries to monitor: ...@@ -605,45 +446,25 @@ Key log entries to monitor:
- **Client Registration**: `"Client X registered"` or `"Client X disconnected"` - **Client Registration**: `"Client X registered"` or `"Client X disconnected"`
- **Tunnel Operations**: `"Tunnel request for client X"` or `"Tunnel established"` - **Tunnel Operations**: `"Tunnel request for client X"` or `"Tunnel established"`
- **Errors**: `"Connection failed"`, `"SSL verification failed"`, `"Authentication error"` - **Errors**: `"Connection failed"`, `"SSL verification failed"`, `"Authentication error"`
- **Service Status**: `"Daemon started"`, `"Watchdog monitoring active"`
### Troubleshooting with Logs
1. **Connection Issues**:
```bash
grep "Connection failed" /var/log/wssshd/wssshd.log
grep "WebSocket" /var/log/wssshc/wssshc.log
```
2. **Client Registration Problems**:
```bash
grep "register" /var/log/wssshd/wssshd.log
grep "Client" /var/log/wssshc/wssshc.log
```
3. **Service Health**:
```bash
grep "started\|stopped\|restarted" /var/log/wssshd/watchdog.log
```
## Security ## Security
### Encryption ### Encryption
- **WebSocket Transport**: All WebSocket connections use SSL/TLS encryption - **Transport Layer**: All connections use SSL/TLS encryption
- **Certificate Validation**: Clients verify server certificates - **Certificate Validation**: Clients verify server certificates
- **Data in Transit**: All tunnel data is encrypted end-to-end - **Data Protection**: All tunnel data is encrypted end-to-end
### Authentication ### Authentication
- **Client Registration**: Unique client IDs prevent unauthorized access - **Client Registration**: Unique client IDs with password authentication
- **SSH Authentication**: Standard SSH authentication mechanisms - **SSH Authentication**: Standard SSH authentication mechanisms
- **Connection Isolation**: Each tunnel session is isolated - **Connection Isolation**: Each tunnel session is isolated
### Security Considerations ### Security Considerations
1. **Certificate Management**: 1. **Certificate Management**:
- Use proper CA-signed certificates in production - Use CA-signed certificates in production
- Regularly rotate certificates - Regularly rotate certificates
- Implement certificate pinning if required - Implement certificate pinning if required
...@@ -657,18 +478,6 @@ Key log entries to monitor: ...@@ -657,18 +478,6 @@ Key log entries to monitor:
- Regularly rotate client registrations - Regularly rotate client registrations
- Monitor client connection logs - Monitor client connection logs
4. **SSH Security**:
- Disable password authentication
- Use key-based authentication
- Implement SSH hardening practices
### Known Security Limitations
- Self-signed certificates may trigger warnings
- No built-in DDoS protection
- Basic client authentication (ID-based only)
- No session encryption beyond SSL/TLS
## Troubleshooting ## Troubleshooting
### Common Issues ### Common Issues
...@@ -687,7 +496,7 @@ Key log entries to monitor: ...@@ -687,7 +496,7 @@ Key log entries to monitor:
# Check if wssshd is running # Check if wssshd is running
netstat -tlnp | grep :9898 netstat -tlnp | grep :9898
# Test WebSocket connection # Test connection
curl -I https://localhost:9898 curl -I https://localhost:9898
``` ```
...@@ -697,16 +506,16 @@ curl -I https://localhost:9898 ...@@ -697,16 +506,16 @@ curl -I https://localhost:9898
**Causes**: **Causes**:
- wssshc not running on target machine - wssshc not running on target machine
- Incorrect client ID in hostname - Incorrect client ID
- Network connectivity issues - Network connectivity issues
**Solutions**: **Solutions**:
```bash ```bash
# Check client registration # Verify client registration
./wssshc --server-ip <ip> --port 9898 --id <client_id> --password <password> ./wssshc --server-ip <ip> --port 9898 --id <client_id> --password <password>
# Verify client appears in wssshd logs # Check server logs
tail -f wssshd.log tail -f /var/log/wssshd/wssshd.log
``` ```
#### SSL Certificate Errors #### SSL Certificate Errors
...@@ -727,27 +536,6 @@ tail -f wssshd.log ...@@ -727,27 +536,6 @@ tail -f wssshd.log
openssl x509 -in cert.pem -text -noout openssl x509 -in cert.pem -text -noout
``` ```
#### Tunnel Connection Issues
**Symptoms**: SSH/SCP connections hang or fail
**Causes**:
- Local SSH server not running
- Port conflicts
- Firewall blocking local ports
**Solutions**:
```bash
# Check local SSH server
systemctl status sshd
# Test local SSH connection
ssh localhost
# Check port availability
netstat -tlnp | grep :22
```
### Debug Mode ### Debug Mode
Enable debug output for detailed troubleshooting: Enable debug output for detailed troubleshooting:
...@@ -760,93 +548,52 @@ Enable debug output for detailed troubleshooting: ...@@ -760,93 +548,52 @@ Enable debug output for detailed troubleshooting:
./wssshc --debug --server-ip <ip> --port 9898 --id client1 --password <password> ./wssshc --debug --server-ip <ip> --port 9898 --id client1 --password <password>
# wsssh debug # wsssh debug
./wsssh --debug user@client.example.com -p 9898 ./wsssh --debug user@client.example.com
# wsssh dev-tunnel mode (setup tunnel without launching SSH)
./wsssh --dev-tunnel user@client.example.com -p 9898
# wsscp debug # wsscp debug
./wsscp --debug file user@client.example.com:/path/ -P 9898 ./wsscp --debug file user@client.example.com:/path/
# wsscp dev-tunnel mode (setup tunnel without launching SCP) # wsssht debug
./wsscp --dev-tunnel file user@client.example.com:/path/ -P 9898 ./wsssht --debug myclient@example.com
``` ```
### Log Analysis
Key log messages to monitor:
- **Registration**: "Client X registered"
- **Tunnel Requests**: "Tunnel request for client X"
- **Connection Issues**: "Connection failed" or "SSL verification failed"
- **Data Transfer**: "Forwarding X bytes"
## Development ## Development
### Project Structure ### Project Structure
``` ```
wsssh/ wsssh/
├── wssshd.py # WebSocket SSH Daemon (Python) ├── wssshd.py # Universal tunneling daemon
├── build.sh # Build script (supports --debian, --server-only) ├── build.sh # Build script
├── clean.sh # Clean script ├── clean.sh # Clean script
├── requirements.txt # Python dependencies ├── requirements.txt # Python dependencies
├── cert.pem # SSL certificate (auto-generated) ├── cert.pem # SSL certificate
├── key.pem # SSL private key (auto-generated) ├── key.pem # SSL private key
├── templates/ # Flask web templates ├── templates/ # Web interface templates
├── static/ # Web assets │ ├── base.html # Base template
├── wssshtools/ # C implementation directory │ ├── index.html # Dashboard
│ ├── wssshc.c # C client for registration │ ├── login.html # Authentication
│ ├── wsssh.c # C SSH wrapper (main function only) │ ├── terminal.html # HTML5 terminal
│ ├── wsscp.c # C SCP wrapper │ └── users.html # User management
│ ├── wssshlib.h # Shared utilities library header ├── wssshtools/ # C implementation
│ ├── wssshlib.c # Shared utilities library implementation │ ├── wssshc.c # Client registration
│ ├── websocket.h # WebSocket functions library header │ ├── wsssh.c # SSH wrapper
│ ├── websocket.c # WebSocket functions library implementation │ ├── wsscp.c # SCP wrapper
│ ├── wssh_ssl.h # SSL functions library header │ ├── wsssht.c # Tunnel setup tool
│ ├── wssh_ssl.c # SSL functions library implementation │ ├── libwsssht/ # Shared libraries
│ ├── tunnel.h # Tunnel management library header │ │ ├── wsssht.h # Main header
│ ├── tunnel.c # Tunnel management library implementation │ │ ├── utils.h/c # Utility functions
│ ├── libwsssht/ # Modular wsssht components (v1.6.1) │ │ ├── modes.h/c # Operating modes
│ │ ├── wsssht.h # Main wsssht header with declarations │ │ ├── threads.h/c # Thread management
│ │ ├── utils.h # Utility functions header │ │ ├── tunnel.h/c # Tunnel functions
│ │ ├── utils.c # Utility implementations (print_usage, parse_args) │ │ ├── websocket.h/c # WebSocket support
│ │ ├── modes.h # Operating mode functions header │ │ ├── wssh_ssl.h/c # SSL/TLS support
│ │ ├── modes.c # Mode implementations (bridge, script, daemon) │ │ └── wssshlib.h/c # Core library
│ │ ├── threads.h # Thread functions header │ ├── configure.sh # Build configuration
│ │ └── threads.c # Thread implementations and structures │ ├── Makefile # Build system
│ ├── configure.sh # Build configuration (updated for modular structure) │ └── debian/ # Debian packaging
│ ├── Makefile # GNU Make build system (updated for modular structure) ├── wsssh-server/ # Server package
│ ├── common.c # Common utilities └── CHANGELOG.md # Version history
│ └── debian/ # Debian packaging for wsssh-tools
│ ├── control # Package metadata
│ ├── rules # Build rules
│ ├── changelog # Package changelog
│ ├── copyright # Copyright info
│ └── compat # Debhelper compatibility
├── wsssh-server/ # wsssh-server Debian package
│ ├── debian/ # Debian packaging for wssshd daemon
│ │ ├── control # Package metadata
│ │ ├── rules # Build rules with PyInstaller
│ │ ├── changelog # Package changelog
│ │ ├── copyright # Copyright info
│ │ ├── compat # Debhelper compatibility
│ │ ├── wssshd.1 # Man page for wssshd
│ │ ├── postinst # Post-installation script
│ │ ├── postrm # Post-removal script
│ │ └── wssshd.default # Service defaults
│ └── PyInstaller/ # PyInstaller spec files
├── wssshc.conf.example # Example wssshc configuration file
├── .gitignore # Git ignore rules
├── LICENSE.md # GPLv3 license
├── README.md # Main documentation
├── DOCUMENTATION.md # This file
├── CHANGELOG.md # Version history
└── logos/ # Logo and icon assets
├── logo-*.png # Various logo sizes
├── icon-*.png # Application icons
├── banner-*.png # Banner images
└── favicon.ico # Web favicon
``` ```
### Dependencies ### Dependencies
...@@ -858,35 +605,22 @@ wsssh/ ...@@ -858,35 +605,22 @@ wsssh/
- **Flask-Login**: User authentication - **Flask-Login**: User authentication
- **Flask-SQLAlchemy**: Database support - **Flask-SQLAlchemy**: Database support
- **ssl**: SSL/TLS support (built-in) - **ssl**: SSL/TLS support (built-in)
- **asyncio**: Asynchronous I/O (built-in)
- **subprocess**: Process management (built-in)
- **socket**: Network sockets (built-in)
#### C Implementation #### C Implementation
- **GCC**: GNU C Compiler - **GCC**: GNU C Compiler
- **Make**: GNU Make build system - **Make**: GNU Make build system
- **OpenSSL**: SSL/TLS library (libssl-dev) - **OpenSSL**: SSL/TLS library (libssl-dev)
- **pkg-config**: Build configuration tool - **pkg-config**: Build configuration tool
- **Man Pages**: Comprehensive documentation (man)
#### Debian Packaging
- **debhelper**: Debian packaging helper
- **dh-autoreconf**: Autotools integration
- **gcc**: C compiler
- **libssl-dev**: OpenSSL development headers
### Building from Source ### Building from Source
#### Server Build (wssshd) #### Server Build
```bash ```bash
# Install Python dependencies # Install Python dependencies
pip3 install -r requirements.txt pip3 install -r requirements.txt
# Build server binary # Build server binary
./build.sh --server-only ./build.sh --server-only
# Build with Debian package
./build.sh --debian
``` ```
#### C Implementation #### C Implementation
...@@ -896,61 +630,17 @@ cd wssshtools ...@@ -896,61 +630,17 @@ cd wssshtools
./configure.sh ./configure.sh
make make
# Install system-wide (optional) # Install system-wide
sudo make install sudo make install
``` ```
#### Debian Package #### Debian Packages
```bash ```bash
# Build Debian package # Build all packages
./build.sh --debian ./build.sh --debian
# Install package # Install packages
sudo dpkg -i dist/wsssh-tools*.deb sudo dpkg -i dist/wsssh-server*.deb dist/wsssh-tools*.deb
```
#### wsssh-server Debian Package (v1.4.0)
```bash
# Build wsssh-server package only
./build.sh --server-only
# Install wsssh-server package
sudo dpkg -i dist/wsssh-server*.deb
# Configure the service
sudo cp /usr/share/wsssh/wssshd.conf.example /etc/wssshd.conf
sudo editor /etc/wssshd.conf
# Enable and start the service
sudo echo "START=yes" > /etc/default/wssshd
sudo /etc/init.d/wssshd start
# Check service status
sudo /etc/init.d/wssshd status
# View the man page
man wssshd
```
**wsssh-server Package Features:**
- Standalone PyInstaller binary with bundled Python dependencies (no external Python packages required)
- Professional init script with wssshd user/group support
- Automatic user/group creation during installation
- Complete service management (start/stop/restart/status/reload)
- Integration with Debian init system and rc2.d
- /etc/default/wssshd service control configuration
- Comprehensive wssshd man page documentation
- Secure daemon operation with minimal privileges
- **Watchdog Monitoring**: Automatic daemon restart and high availability
- **Enterprise Reliability**: Professional process supervision and monitoring
- **Build System Fixes**: Robust Debian package building with binary reuse
- **Error Handling**: Comprehensive error handling for build failures
- **Minimal Dependencies**: Only requires `adduser` package for user management
#### Clean Build Artifacts
```bash
# Clean all build artifacts
./clean.sh
``` ```
### Testing ### Testing
...@@ -966,95 +656,30 @@ python3 -m pytest tests/integration/ ...@@ -966,95 +656,30 @@ python3 -m pytest tests/integration/
./test/manual_test.sh ./test/manual_test.sh
``` ```
### Code Style ## Recent Updates
- Follow PEP 8 style guidelines
- Use type hints for function parameters
- Include docstrings for all public functions
- Use descriptive variable names
### Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
### Release Process
1. Update version in all relevant files
2. Update CHANGELOG.md
3. Create git tag
4. Build release binaries
5. Create GitHub release
6. Update documentation
--- ### Version 1.6.1
- **Major Code Refactoring**: Complete modularization of wsssht.c
- **Operating Modes**: Multiple operating modes implementation
- **Bridge Mode**: JSON stdin/stdout interface
- **Script Mode**: JSON protocol for scripting
- **Daemon Mode**: Lazy tunnel initialization
## Recent Updates ### Version 1.5.0
- **Peer-to-Peer Tunneling**: Advanced tunneling system
- **Transport Selection**: Configurable transport protocols
- **PyInstaller Template Fix**: Frozen executable template loading
### Version 1.4.8 (Latest) ### Version 1.4.8
- **Critical SSL Connection Stability**: Comprehensive SSL error handling and connection resilience improvements - **SSL Connection Stability**: Comprehensive SSL error handling
- Fixed WebSocket frame sending failures that caused connection drops - **Process Exit Handling**: Fixed critical process hanging issues
- Added detailed SSL error reporting with specific error codes and descriptions - **Code Architecture**: Modular design with shared libraries
- Implemented automatic retry logic for transient SSL errors (SSL_ERROR_WANT_READ/WRITE)
- Added 5-second timeout protection for SSL read operations to prevent indefinite hangs
- Enhanced connection state validation before SSL operations
- Improved WebSocket frame transmission with retry mechanisms and partial write handling
### Version 1.4.7
- **Critical Process Exit Bug Fix**: Fixed wsssh process hanging after SSH client disconnection
- Added `broken` flag to tunnel structure to distinguish between normal closure and broken connections
- Implemented proper tunnel state tracking for EBADF, EPIPE, and ECONNRESET errors
- Enhanced error handling in `handle_tunnel_data()` for SSH client disconnections
- Fixed main loop to immediately kill SSH child process and exit when tunnel breaks
- Added proper exit code handling: 0 for normal termination, 1 for error conditions
### Version 1.4.6
- **Code Architecture Overhaul**: Major refactoring to eliminate code duplication
- Created shared libraries: `wssshlib.h/.c`, `websocket.h/.c`, `wssh_ssl.h/.c`, `tunnel.h/.c`
- Extracted ~1500+ lines of duplicate code between wsssh.c and wssshc.c
- Improved maintainability and code organization with modular architecture
- Enhanced build system with proper library dependencies
- **SSH Tunneling Enhancements**: Enhanced SSH tunnel handling and error recovery
- Added specific handling for EBADF (Bad file descriptor) errors
- Improved error handling in handle_tunnel_data for SSH client disconnections
- Removed aggressive socket validation causing SSH client disconnections
- Fixed SSH client socket invalidation issue in handle_tunnel_data
- Added missing SSH client accept() logic in wsssh socket handling
- Fixed SSH tunneling timing issue with proper data buffering
- **Port Option Behavior Correction**: Fixed critical port option behavior
- `-p`/`-P` options now correctly specify wssshd server port (not SSH/SCP server port)
- Removed misleading "passed through to ssh/scp" documentation
- Updated help text to clearly indicate port options are consumed by wsssh/wsscp
- Fixed argument parsing to properly handle wssshd server port specification
### Version 1.4.5
- **Python Implementation Removal**: Removed Python implementations of wssshc, wsssh, and wsscp
- Deleted wssshc.py, wsssh.py, and wsscp.py files
- Removed pyinstaller commands from build.sh for these tools
- Updated Debian packaging to exclude Python script installations
- Maintained C implementations in wssshtools/ directory
### Version 1.4.4
- **Advanced Logging with Logrotate**: Comprehensive logging system for all daemons
- Added `/var/log/wssshd/wssshd.log` for main daemon logging with automatic rotation
- Added `/var/log/wssshc/wssshc.log` for client daemon logging with automatic rotation
- Configured logrotate with weekly rotation, 52-week retention, and automatic compression
- Proper file permissions and ownership for security
- **Dynamic Terminal Sizing**: Web terminal now properly calculates and uses actual browser window dimensions
- **Terminal Resize Support**: Real-time terminal resizing when browser window is resized
- **Force Echo Mode**: SSH connections now force echo mode for better visibility
--- ---
## Donations ## Donations
If you find WSSH useful, please consider supporting the project development: If you find WSSSH useful, please consider supporting the project:
### PayPal ### PayPal
Donate via PayPal to: **info@nexlab.net** Donate via PayPal to: **info@nexlab.net**
...@@ -1063,16 +688,6 @@ Donate via PayPal to: **info@nexlab.net** ...@@ -1063,16 +688,6 @@ Donate via PayPal to: **info@nexlab.net**
- **Bitcoin (BTC)**: `bc1q3zlkpu95amtcltsk85y0eacyzzk29v68tgc5hx` - **Bitcoin (BTC)**: `bc1q3zlkpu95amtcltsk85y0eacyzzk29v68tgc5hx`
- **Ethereum (ETH)**: `0xdA6dAb526515b5cb556d20269207D43fcc760E51` - **Ethereum (ETH)**: `0xdA6dAb526515b5cb556d20269207D43fcc760E51`
Your support helps us continue developing and maintaining this open-source project! ❤️
## Support
For support and questions:
- **Git Issues**: Bug reports and feature requests at https://git.nexlab.net/nexlab/wsssh
- **Documentation**: This comprehensive guide
- **Community**: Join discussions and get help
## License ## License
This project is licensed under the GNU General Public License v3.0 (GPLv3). This project is licensed under the GNU General Public License v3.0 (GPLv3).
......
README.md
View file @ b7dae7b4
...@@ -2,81 +2,64 @@ ...@@ -2,81 +2,64 @@
![WSSH Logo](logos/logo-256.png) ![WSSH Logo](logos/logo-256.png)
wsssh is a swiss army's knife server assisted tunnelling system for the win initially born as a websocket ssh tunnelling system and evolved to a universal tunnelling utility **WSSSH** is a universal tunneling system that provides secure access to remote machines through various transport protocols. It consists of multiple components that work together to create a seamless tunneling experience, allowing you to access remote machines through secure relays with support for multiple transport types.
## Features ## Features
- **C Implementation**: Lightweight and efficient C versions available - **Universal Tunneling**: Support for multiple transport protocols (WebSocket, and more coming soon)
- **WebSocket-based Tunneling**: Secure SSH/SCP access through WebSocket connections - **Multi-Component Architecture**: Complete tunneling system with server, client, and wrapper tools
- **Peer-to-Peer Architecture**: Advanced tunneling with transport selection and negotiation - **Intelligent Hostname Parsing**: Automatic client ID and server endpoint detection
- **Transport Selection**: Choose specific transport types for data and control channels - **Drop-in SSH/SCP Replacement**: Use `wsssh` and `wsscp` as direct replacements for standard SSH/SCP commands
- **Client Registration**: Register client machines with the WebSocket daemon - **SSL/TLS Encryption**: All communications are fully encrypted
- **Password Authentication**: Secure client registration with configurable passwords
- **Web Management Interface**: Professional admin panel with user management and HTML5 terminal
- **Intelligent Hostname Parsing**: `<CLIENT_ID>.<WSSSHD_HOST>` format with `-p`/`-P` port options
- **Simplified CLI**: No need to specify "ssh" or "scp" commands explicitly
- **Drop-in SSH/SCP Replacement**: Use `wsssh` and `wsscp` as direct replacements for `ssh` and `scp`
- **SSL/TLS Encryption**: All WebSocket communications are encrypted
- **Multi-client Support**: Route connections to different registered clients - **Multi-client Support**: Route connections to different registered clients
- **Cross-platform**: Works on Linux, macOS, and Windows - **Professional Web Interface**: Admin panel with user management and HTML5 terminal
- **Cross-platform Compatibility**: Works on Linux, macOS, and Windows
- **Debian Packaging**: Easy installation with proper system integration - **Debian Packaging**: Easy installation with proper system integration
- **wsssh-server Package**: Standalone Debian package for wssshd daemon - **Service Management**: Complete init scripts and watchdog monitoring
- **PyInstaller Binary**: Standalone wssshd binary with no Python dependencies - **Advanced Logging**: Automatic log rotation with comprehensive monitoring
- **Professional Service Management**: Complete init scripts and service integration
- **Watchdog Monitoring**: Automatic daemon restart and high availability
- **Enterprise Reliability**: Professional process supervision and monitoring
- **Advanced Logging**: Automatic log rotation with logrotate for all daemons
- **Multiple Operating Modes**: Interactive, silent, bridge, script, and daemon modes - **Multiple Operating Modes**: Interactive, silent, bridge, script, and daemon modes
- **Bridge Mode**: JSON-based communication over stdin/stdout for programmatic use - **Enterprise Reliability**: Production-grade process supervision and high availability
- **Script Mode**: JSON protocol with status updates and command processing
- **Daemon Mode**: Lazy tunnel initialization for resource efficiency
- **Donation Support**: Community funding through PayPal and cryptocurrency
## Architecture ## Architecture
The system consists of components implemented in C for optimal performance: ### Core Components
### Server Component #### Server Component (`wssshd`)
1. **`wssshd`** - WSSH Daemon (server) - **Universal Daemon**: Central server managing connections with multiple transport protocols
- Manages WebSocket connections with SSL/TLS encryption - **Client Registration**: Handles client authentication with password-based registration
- Handles client registrations with password authentication - **Tunnel Routing**: Routes tunnel requests to appropriate registered clients
- Routes tunnel requests to appropriate clients - **Web Management Interface**: Professional admin panel with user management and HTML5 terminal
- Professional web management interface with user administration - **Session Management**: Maintains persistent connections and handles reconnection logic
- HTML5 terminal interface for SSH connections
- Donation modal integrated into the web interface
### wsssh tools (C Implementation) #### Client Tools (`wssshtools/`)
Located in the `wssshtools/` directory:
1. **`wssshc`** - WSSH Client (registration) 1. **`wssshc`** - WSSH Client Registration
- Registers client machines with the daemon - Registers client machines with the daemon
- Maintains persistent WebSocket connection - Maintains persistent connection to the server
- Automatic reconnection with configurable intervals - Automatic reconnection with configurable intervals
- Minimal dependencies (OpenSSL only) - Minimal dependencies (OpenSSL only)
- Native WebSocket implementation - Optimized for embedded systems and resource-constrained environments
- Optimized for embedded systems
2. **`wsssh`** - SSH Wrapper with Tunneling
2. **`wsssh`** - SSH wrapper with tunneling - Simplified CLI that eliminates the need to specify "ssh" commands explicitly
- Simplified CLI (no need to specify "ssh" command) - Intelligent parsing of SSH commands and hostnames
- Parses SSH commands and hostnames intelligently - Automatic establishment of tunnels
- Establishes WebSocket tunnels automatically - Launches SSH client to local tunnel port
- Launches SSH to local tunnel port - Direct system integration with no Python runtime required
- Uses shared libraries for WebSocket, SSL, and tunnel management - High performance for production environments
- Direct system integration, no Python runtime required
- High performance for production use 3. **`wsscp`** - SCP Wrapper with Tunneling
- **Multiple Operating Modes**: Interactive, silent, bridge, script, and daemon modes - Simplified CLI that eliminates the need to specify "scp" commands explicitly
- **Bridge Mode**: JSON-based communication over stdin/stdout for programmatic use - Optimized for file transfer operations through secure tunnels
- **Script Mode**: JSON protocol with status updates and command processing - Handles both upload and download operations
- **Daemon Mode**: Lazy tunnel initialization for resource efficiency - Consistent design with the SSH wrapper
- Enterprise-ready performance for large file transfers
3. **`wsscp`** - SCP wrapper with tunneling
- Simplified CLI (no need to specify "scp" command) 4. **`wsssht`** - Tunnel Setup Tool
- Similar to wsssh but optimized for SCP operations - Manual tunnel establishment without automatic command execution
- Handles file transfers through secure tunnels - Provides connection information for use with any TCP client
- Uses shared libraries for WebSocket, SSL, and tunnel management - Supports all tunneling modes and transport options
- Optimized file transfer operations - Perfect for integration with third-party tools and custom workflows
- Consistent with SSH wrapper design
- Enterprise-ready performance
## Installation ## Installation
...@@ -87,27 +70,21 @@ Located in the `wssshtools/` directory: ...@@ -87,27 +70,21 @@ Located in the `wssshtools/` directory:
git clone https://git.nexlab.net/nexlab/wsssh.git git clone https://git.nexlab.net/nexlab/wsssh.git
cd wsssh cd wsssh
# Install dependencies # Install Python dependencies for the server
pip3 install -r requirements.txt pip3 install -r requirements.txt
# Build binaries (optional) # Build all components
./build.sh ./build.sh
``` ```
### Using Pre-built Binaries
Download the latest release binaries for your platform from the releases page.
### Debian Package Installation ### Debian Package Installation
For Debian/Ubuntu systems, you can install both the server and client components via Debian packages: #### Server Package (`wsssh-server`)
#### wsssh-server Package (Daemon)
```bash ```bash
# Build the wsssh-server package # Build the server package
./build.sh --server-only ./build.sh --server-only
# Install the server package (no Python dependencies required!) # Install the server package
sudo dpkg -i dist/wsssh-server*.deb sudo dpkg -i dist/wsssh-server*.deb
# Configure the service # Configure the service
...@@ -115,39 +92,26 @@ sudo cp /usr/share/wsssh/wssshd.conf.example /etc/wssshd.conf ...@@ -115,39 +92,26 @@ sudo cp /usr/share/wsssh/wssshd.conf.example /etc/wssshd.conf
sudo editor /etc/wssshd.conf sudo editor /etc/wssshd.conf
# Enable and start the service # Enable and start the service
sudo echo "START=yes" > /etc/default/wssshd sudo systemctl enable wssshd
sudo /etc/init.d/wssshd start sudo systemctl start wssshd
# Check service status # Check service status
sudo /etc/init.d/wssshd status sudo systemctl status wssshd
# View the man page
man wssshd
```
**Note**: The wsssh-server package uses a standalone PyInstaller binary that bundles all Python dependencies, so no additional Python packages are required for installation.
**Upgrade Note**: When upgrading the wsssh-server package, if the wssshd service is running, you will be prompted for confirmation before the service is stopped for the upgrade. The service will be automatically restarted afterward if it was running, ensuring zero-downtime upgrades.
**Non-Interactive Installation**: For automated deployments or CI/CD pipelines, use:
```bash
export DEBIAN_FRONTEND=noninteractive
sudo dpkg -i dist/wsssh-server*.deb
``` ```
The service will be stopped and restarted automatically without user interaction.
#### wsssh-tools Package (C Implementation) #### Client Tools Package (`wsssh-tools`)
```bash ```bash
# Build the wsssh-tools package # Build the client tools package
./build.sh --wssshtools-only ./build.sh --wssshtools-only
# Install the client package # Install the client package
sudo dpkg -i dist/wsssh-tools*.deb sudo dpkg -i dist/wsssh-tools*.deb
# The C tools will be available system-wide # Verify installation
wssshc --help wssshc --help
wsssh --help wsssh --help
wsscp --help wsscp --help
wsssht --help
``` ```
#### Build Both Packages #### Build Both Packages
...@@ -164,136 +128,111 @@ sudo dpkg -i dist/wsssh-server*.deb dist/wsssh-tools*.deb ...@@ -164,136 +128,111 @@ sudo dpkg -i dist/wsssh-server*.deb dist/wsssh-tools*.deb
To build the C tools from source: To build the C tools from source:
```bash ```bash
# Configure and build C tools # Navigate to the tools directory
cd wssshtools cd wssshtools
# Configure and build
./configure.sh ./configure.sh
make make
# Install system-wide (optional) # Optional: Install system-wide
sudo make install sudo make install
``` ```
The C tools include comprehensive man pages: ## Quick Start Guide
### 1. Start the Daemon
```bash ```bash
man wssshc # WSSH client # Start the server with basic configuration
man wsssh # SSH wrapper ./wssshd --host 0.0.0.0 --port 9898 --domain example.com --password mysecret
man wsscp # SCP wrapper
# Or with web interface enabled
./wssshd --host 0.0.0.0 --port 9898 --domain example.com --password mysecret \
--web-host 0.0.0.0 --web-port 8080
``` ```
## Quick Start ### 2. Register a Client Machine
### 1. Start the WebSocket Daemon On each machine you want to access through WSSSH:
```bash ```bash
./wssshd --host 0.0.0.0 --port 9898 --domain example.com # Register with the server
``` ./wssshc --server-ip <server_ip> --port 9898 --id myclient --password mysecret
### 2. Register a Client # The client will maintain a persistent connection to the server
```
On the client machine you want to access through: ### 3. Connect via SSH
```bash ```bash
./wssshc --server-ip <daemon_ip> --port 9898 --id myclient --password mysecret # Using the SSH wrapper (recommended)
./wsssh user@myclient.example.com
# Using the tunnel setup tool for manual connections
./wsssht --clientid myclient --wssshd-host example.com
# With custom port
./wsssh -p 2222 user@myclient.example.com
``` ```
### 3. Connect via SSH ### 4. Transfer Files via SCP
```bash ```bash
# Simplified CLI (recommended) # Upload a file
./wsssh user@myclient.example.com -p 9898 ./wsscp localfile user@myclient.example.com:/remote/path/
# Or using C implementation # Download a file
./wssshtools/wsssh user@myclient.example.com -p 9898 ./wsscp user@myclient.example.com:/remote/file ./localfile
```
This automatically: # With custom port
- Parses `myclient.example.com` to extract client ID `myclient` ./wsscp -P 2222 localfile user@myclient.example.com:/remote/path/
- Connects to wssshd at `example.com:9898` ```
- Requests tunnel to client `myclient`
- Opens local port and launches `ssh user@localhost`
## Operating Modes ## Operating Modes
wsssht supports multiple operating modes for different use cases:
### Interactive Mode (Default) ### Interactive Mode (Default)
Standard interactive SSH/SCP sessions with full user interface. Standard interactive sessions with full user interface and progress indicators.
### Silent Mode ### Silent Mode
```bash ```bash
./wsssh --silent --clientid myclient --wssshd-host example.com ./wsssh --silent --clientid myclient --wssshd-host example.com
``` ```
Suppresses all informational output, perfect for scripts and automation. Suppresses all informational output, perfect for automation and scripting.
### Bridge Mode ### Bridge Mode
```bash ```bash
./wsssh --bridge --clientid myclient --wssshd-host example.com ./wsssht --bridge --clientid myclient --wssshd-host example.com
``` ```
JSON-based communication over stdin/stdout for programmatic use. Receives JSON commands from stdin and sends JSON responses to stdout. JSON-based communication over stdin/stdout for programmatic integration.
**Important**: In bridge mode, tunnel control channel messages are communicated through stdin/stdout (JSON protocol), while tunnel data channel messages remain handled by wsssht through normal forwarding.
### Script Mode ### Script Mode
```bash ```bash
./wsssh --script --clientid myclient --wssshd-host example.com ./wsssht --script --clientid myclient --wssshd-host example.com
``` ```
JSON protocol with status updates and command processing. Provides periodic status updates and accepts script commands. JSON protocol with status updates and command processing for scripting environments.
### Daemon Mode ### Daemon Mode
```bash ```bash
./wsssh --daemon --clientid myclient --wssshd-host example.com ./wsssht --daemon --clientid myclient --wssshd-host example.com
``` ```
Lazy tunnel initialization - waits for first connection attempt before establishing the tunnel, conserving resources. Lazy tunnel initialization that waits for the first connection before establishing the tunnel.
## Hostname Format ## Hostname Format
The system uses intelligent hostname parsing with config file support: WSSSH uses intelligent hostname parsing with the format:
``` ```
<CLIENT_ID>.<WSSSHD_HOST> <CLIENT_ID>.<WSSSHD_HOST>[:<WSSSHD_PORT>]
``` ```
**Supported Formats:**
- `user@client.domain` - Full specification with domain
- `user@client` - Uses domain from config file or defaults to localhost
Port is specified using `-p` (SSH) or `-P` (SCP) options, or from config file.
### Examples: ### Examples:
- `user@myclient.example.com` → Client: `myclient`, Server: `example.com:9898`
- `user@server.datacenter.com:2222` → Client: `server`, Server: `datacenter.com:2222`
- `user@remote` (with config domain `example.com`) → Client: `remote`, Server: `example.com:9898`
- `remote.example.com -p 9898` → Client: `remote`, Server: `example.com:9898` ## Configuration
- `server.datacenter.com -P 2222` → Client: `server`, Server: `datacenter.com:2222`
- `test.localhost -p 8080` → Client: `test`, Server: `localhost:8080`
- `myclient` (with config domain `example.com`) → Client: `myclient`, Server: `example.com:<config_port>`
## Port Detection Priority
1. **Command line option**: `-p <port>` (SSH) or `-P <port>` (SCP) - specifies wssshd server port
2. **Config file**: `port` setting in `~/.config/wsssh/wsssh.conf` - wssshd server port
3. **Default**: `9898` (wssshd default port)
## Detailed Usage
### wssshd (WSSH Daemon)
```bash
./wssshd --host 0.0.0.0 --port 9898 --domain example.com --password mysecret [--web-host 0.0.0.0 --web-port 8080] [--web-https] [--debug]
```
**Options:**
- `--host`: Bind address
- `--port`: WebSocket port
- `--domain`: Domain suffix for hostname parsing
- `--password`: Registration password
- `--web-host`: Web interface bind address (optional)
- `--web-port`: Web interface port (optional)
- `--web-https`: Enable HTTPS for web interface
- `--debug`: Enable debug output
**Configuration File:**
wssshd supports a system-wide configuration file at `/etc/wssshd.conf`:
### Server Configuration (`/etc/wssshd.conf`)
```ini ```ini
[wssshd] [wssshd]
host = 0.0.0.0 host = 0.0.0.0
...@@ -305,364 +244,151 @@ web-port = 8080 ...@@ -305,364 +244,151 @@ web-port = 8080
web-https = false web-https = false
``` ```
Command line options override configuration file values. Required parameters are only mandatory when not provided in either the config file or command line. ### Client Configuration (`~/.config/wsssh/wssshc.conf`)
**Web Interface:**
When `--web-host` and `--web-port` are specified, a web management interface is available with:
- User authentication (default: admin/admin123)
- Client connection overview
- User management (admin only)
- HTML5 terminal interface
### wssshc (WSSH Client)
```bash
./wssshc --server-ip <ip> --port 9898 --id client1 --password mysecret [--tunnel websocket] [--tunnel-control websocket] [--interval 30] [--debug]
```
**Options:**
- `--server-ip`: wssshd server IP address
- `--port`: wssshd server port (default: 9898)
- `--id`: Unique client identifier
- `--password`: Registration password
- `--tunnel`: Transport types for data channel (comma-separated or 'any', default: any)
- `--tunnel-control`: Transport types for control channel (comma-separated or 'any', default: any)
- `--interval`: Reconnection interval in seconds (default: 30)
- `--debug`: Enable debug output
**Configuration File:**
wssshc supports an optional configuration file at `~/.config/wsssh/wssshc.conf`:
```ini ```ini
[wssshc] [wssshc]
password = mysecret password = mysecret
domain = example.com
server-ip = 192.168.1.100 server-ip = 192.168.1.100
port = 9898 port = 9898
id = client1 id = client01
```
Command line options override configuration file values. Required parameters are only mandatory when not provided in either the config file or command line.
### wsssh (SSH Wrapper)
```bash
./wsssh [options] user@client.domain [ssh_options...]
``` ```
**Options:** ### Tools Configuration (`~/.config/wsssh/wsssh.conf`)
- `--local-port`: Local tunnel port (default: auto)
- `--tunnel`: Transport types for data channel (comma-separated or 'any', default: any)
- `--tunnel-control`: Transport types for control channel (comma-separated or 'any', default: any)
- `--service`: Service type (default: ssh)
- `--debug`: Enable debug output
- `--dev-tunnel`: Development mode: setup tunnel but don't launch SSH
- `--help`: Display help message and exit
**Examples:**
```bash
# Basic SSH connection with explicit port and domain
./wsssh -p 9898 user@myclient.example.com
# SSH with custom port
./wsssh -p 2222 user@myclient.example.com
# SSH using config file defaults
./wsssh user@myclient
# SSH with options
./wsssh -p 9898 -i ~/.ssh/key user@myclient.example.com ls -la
```
### wsscp (SCP Wrapper)
```bash
./wsscp [options] [scp_options...] source destination
```
**Options:**
- `--local-port`: Local tunnel port (default: auto)
- `--tunnel`: Transport types for data channel (comma-separated or 'any', default: any)
- `--tunnel-control`: Transport types for control channel (comma-separated or 'any', default: any)
- `--service`: Service type (default: ssh)
- `--debug`: Enable debug output
- `--dev-tunnel`: Development mode: setup tunnel but don't launch SCP
- `--help`: Display help message and exit
**Examples:**
```bash
# Copy file to remote with explicit port and domain
./wsscp -P 9898 localfile user@myclient.example.com:/remote/path/
# Copy file from remote
./wsscp -P 9898 user@myclient.example.com:/remote/file ./localfile
# Copy using config file defaults
./wsscp localfile user@myclient:/remote/path/
# Copy with custom port
./wsscp -P 2222 localfile user@myclient.example.com:/remote/path/
```
## Configuration
### Config File
WSSH supports an optional INI-formatted configuration file at `~/.config/wsssh/wsssh.conf`:
```ini ```ini
[default] [default]
port=8080 port = 9898
domain=example.com domain = example.com
tunnel=websocket tunnel = websocket
tunnel-control=websocket tunnel-control = websocket
service=ssh service = ssh
``` ```
**Configuration Options:** ## Advanced Usage Examples
- `port`: Default WebSocket server port (used when not specified via `-p`/`-P` options)
- `domain`: Default domain suffix (used when hostname doesn't include domain)
- `tunnel`: Default transport types for data channel (comma-separated or 'any')
- `tunnel-control`: Default transport types for control channel (comma-separated or 'any')
- `service`: Default service type (default: ssh)
**Precedence Rules:**
- **Port**: Command line `-p`/`-P` options override config file, config file overrides default (22)
- **Domain**: Command line domain (e.g., `user@client.domain`) overrides config domain, config domain overrides localhost
**Examples:** ### SSH with Custom Options
```bash ```bash
# Uses config port 8080 and domain example.com # SSH with custom port and additional options
./wsssh user@myclient ./wsssh -p 2222 user@myclient.example.com -i ~/.ssh/key -o StrictHostKeyChecking=no
# Uses command line port 2222, config domain example.com # SSH with specific transport
./wsssh -p 2222 user@myclient ./wsssh --tunnel websocket user@myclient.example.com
# Uses command line port 2222 and domain mydomain.com # Debug mode to see the actual commands
./wsssh -p 2222 user@myclient.mydomain.com ./wsssh --debug user@myclient.example.com
``` ```
### SSL Certificates ### SCP with Advanced Options
The system uses self-signed SSL certificates for WebSocket encryption. Certificates are automatically generated during the build process if they don't exist.
- `cert.pem`: SSL certificate
- `key.pem`: Private key
Certificates are created with:
- 4096-bit RSA key
- Valid for 365 days
- Subject: `/C=US/ST=State/L=City/O=Organization/CN=localhost`
### Client Registration
Each client machine must be registered with wssshd using a unique ID:
```bash ```bash
./wssshc --server-ip <daemon_ip> --port <port> --id <unique_id> --password <password> # SCP with recursive transfer
``` ./wsscp -r localdir user@myclient.example.com:/remote/path/
The client will maintain a persistent WebSocket connection to the daemon.
## Logging and Monitoring # SCP with bandwidth limit
./wsscp -l 1000 localfile user@myclient.example.com:/remote/path/
### Automatic Log Rotation # SCP with custom transport
WSSH includes comprehensive logging with automatic log rotation managed by logrotate: ./wsscp --tunnel websocket localfile user@myclient.example.com:/remote/path/
```
- **wssshd logs**: `/var/log/wssshd/wssshd.log` - Main daemon logs with weekly rotation
- **wssshc logs**: `/var/log/wssshc/wssshc.log` - Client daemon logs with weekly rotation
- **Watchdog logs**: `/var/log/wssshd/watchdog.log` and `/var/log/wssshc/watchdog.log` - Process monitoring logs
### Logrotate Configuration
All logs are automatically rotated weekly with:
- 52 weeks of retention (1 year)
- Automatic compression of rotated logs
- Proper file permissions and ownership
- HUP signal sent to daemons after rotation
### Service Integration ### Tunnel Setup for Manual Use
When installed via Debian packages, logging is automatically configured:
```bash ```bash
# View current logs # Setup tunnel and get connection info
tail -f /var/log/wssshd/wssshd.log ./wsssht --clientid myclient --wssshd-host example.com
tail -f /var/log/wssshc/wssshc.log
# Check logrotate status # Use with any TCP client
logrotate -d /etc/logrotate.d/wssshd telnet localhost 49234
logrotate -d /etc/logrotate.d/wssshc # or
nc localhost 49234
# or
ssh -p 49234 user@localhost
``` ```
## Security Considerations ## Security Considerations
- **SSL/TLS**: All WebSocket communications are encrypted - **SSL/TLS Encryption**: All communications are encrypted
- **Client Authentication**: Clients are identified by unique IDs - **Client Authentication**: Unique client IDs prevent unauthorized access
- **Network Security**: Ensure wssshd is only accessible from trusted networks - **Password Protection**: Secure client registration with configurable passwords
- **Certificate Validation**: Currently uses self-signed certificates - **Network Security**: Restrict daemon access to trusted networks
- **Certificate Management**: Use proper CA-signed certificates in production
## Troubleshooting ## Troubleshooting
### Connection Issues ### Connection Issues
```bash
# Check if wssshd is running
netstat -tlnp | grep :9898
1. **Check wssshd is running**: Verify the daemon is accessible on the specified port # Test connection
2. **Client registration**: Ensure the client is registered and connected curl -I https://localhost:9898
3. **Firewall rules**: Check that required ports are open
4. **SSL certificates**: Verify certificate files exist and are valid
### Debug Mode
Enable debug output for detailed troubleshooting: # Enable debug output
./wsssh --debug user@myclient.example.com
```
### Client Registration Problems
```bash ```bash
./wssshd --debug --host 0.0.0.0 --port 9898 --domain example.com --password mysecret # Verify client registration
./wssshc --debug --server-ip <ip> --port 9898 --id client1 --password mysecret ./wssshc --server-ip <ip> --port 9898 --id <client_id> --password <password>
./wsssh --debug -p 9898 user@client.domain
./wsssh --dev-tunnel -p 9898 user@client.domain # Setup tunnel without launching SSH # Check server logs
./wsscp --debug -P 9898 file user@client.domain:/path/ tail -f /var/log/wssshd/wssshd.log
./wsscp --dev-tunnel -P 9898 file user@client.domain:/path/ # Setup tunnel without launching SCP
``` ```
### Common Issues ### SSL Certificate Issues
```bash
# Regenerate certificates
./build.sh
- **"Client not registered"**: Register the client with wssshc first # Check certificate validity
- **"Connection refused"**: Check wssshd is running and ports are accessible openssl x509 -in cert.pem -text -noout
- **"SSL verification failed"**: The system uses self-signed certificates ```
## Development ## Development
### Building from Source ### Building from Source
```bash ```bash
# Install dependencies # Install dependencies
pip3 install -r requirements.txt pip3 install -r requirements.txt
# Run tests # Build all components
python3 -m pytest
# Build binaries
./build.sh ./build.sh
# Run tests
python3 -m pytest tests/
# Clean build artifacts # Clean build artifacts
./clean.sh ./clean.sh
``` ```
### Project Structure ### Project Structure
``` ```
wsssh/ wsssh/
├── wssshd.py # WebSocket SSH Daemon with web interface ├── wssshd.py # Universal tunneling daemon
├── build.sh # Build script (supports --debian, --server-only) ├── build.sh # Build script
├── clean.sh # Clean script ├── clean.sh # Clean script
├── requirements.txt # Python dependencies ├── requirements.txt # Python dependencies
├── cert.pem # SSL certificate (auto-generated) ├── wssshtools/ # C implementation directory
├── key.pem # SSL private key (auto-generated) │ ├── wssshc.c # Client registration tool
├── templates/ # Flask HTML templates │ ├── wsssh.c # SSH wrapper
│ ├── base.html # Base template with donation modal │ ├── wsscp.c # SCP wrapper
│ ├── index.html # Dashboard │ ├── wsssht.c # Tunnel setup tool
│ ├── login.html # Authentication │ ├── libwsssht/ # Shared libraries
│ ├── terminal.html # HTML5 terminal │ └── debian/ # Debian packaging
│ └── users.html # User management ├── wsssh-server/ # Server Debian package
├── static/ # Static web assets ├── templates/ # Web interface templates
├── wssshtools/ # C implementation directory ├── static/ # Web assets
│ ├── wssshc.c # C client for registration └── CHANGELOG.md # Version history
│ ├── wsssh.c # C SSH wrapper (main function only)
│ ├── wsscp.c # C SCP wrapper
│ ├── wssshlib.h # Shared utilities library header
│ ├── wssshlib.c # Shared utilities library implementation
│ ├── websocket.h # WebSocket functions library header
│ ├── websocket.c # WebSocket functions library implementation
│ ├── wssh_ssl.h # SSL functions library header
│ ├── wssh_ssl.c # SSL functions library implementation
│ ├── tunnel.h # Tunnel management library header
│ ├── tunnel.c # Tunnel management library implementation
│ ├── libwsssht/ # Modular wsssht components (v1.6.1)
│ │ ├── wsssht.h # Main wsssht header with declarations
│ │ ├── utils.h # Utility functions header
│ │ ├── utils.c # Utility implementations (print_usage, parse_args)
│ │ ├── modes.h # Operating mode functions header
│ │ ├── modes.c # Mode implementations (bridge, script, daemon)
│ │ ├── threads.h # Thread functions header
│ │ └── threads.c # Thread implementations and structures
│ ├── common.c # Common utilities
│ ├── configure.sh # C build configuration (updated for modular structure)
│ ├── Makefile # C build system (updated for modular structure)
│ └── debian/ # Debian packaging
│ ├── control # Package metadata
│ ├── rules # Build rules
│ ├── changelog # Package changelog
│ ├── copyright # Copyright info
│ └── compat # Debhelper compatibility
├── wsssh-server/ # wsssh-server Debian package
│ ├── debian/ # Debian packaging for wssshd daemon
│ │ ├── control # Package metadata
│ │ ├── rules # Build rules with PyInstaller
│ │ ├── changelog # Package changelog
│ │ ├── copyright # Copyright info
│ │ ├── compat # Debhelper compatibility
│ │ ├── wssshd.1 # Man page for wssshd
│ │ ├── postinst # Post-installation script
│ │ ├── postrm # Post-removal script
│ │ └── wssshd.default # Service defaults
│ └── PyInstaller/ # PyInstaller spec files
├── wssshc.conf.example # Example wssshc configuration file
├── .gitignore # Git ignore rules
├── LICENSE.md # GPLv3 license
├── README.md # This file
├── DOCUMENTATION.md # Technical documentation
└── CHANGELOG.md # Version history
## Logos and Icons
The project includes a comprehensive set of logos and icons derived from the original `image.jpg`:
### Logo Files
- `logos/logo-512.png` - High-resolution logo (512x512)
- `logos/logo-256.png` - Standard logo (256x256)
- `logos/logo-128.png` - Medium logo (128x128)
- `logos/logo-64.png` - Small logo (64x64)
- `logos/logo-high-quality.png` - Maximum quality version
- `logos/banner-800x200.png` - Banner version (800x200)
### Icon Files
- `logos/icon-256.png` - Large icon (256x256)
- `logos/icon-128.png` - Desktop icon (128x128)
- `logos/icon-64.png` - Toolbar icon (64x64)
- `logos/icon-48.png` - Application icon (48x48)
- `logos/icon-32.png` - Small icon (32x32)
- `logos/icon-16.png` - Tiny icon (16x16)
- `logos/favicon.ico` - Web favicon (32x32)
### Usage
- **Web**: Use `logos/favicon.ico` for website favicons
- **Desktop**: Use `logos/icon-128.png` or `logos/icon-64.png` for desktop shortcuts
- **Documentation**: Use `logos/logo-256.png` for README files and documentation
- **Marketing**: Use `logos/banner-800x200.png` for banners and social media
``` ```
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request
## License
This project is licensed under the GNU General Public License v3.0 (GPLv3).
Copyright (C) 2024 Stefy Lanza <stefy@nexlab.net> and SexHack.me
See [LICENSE.md](LICENSE.md) for the full license text.
## Support ## Support
- **Documentation**: Comprehensive guides in `DOCUMENTATION.md`
- **Man Pages**: Detailed help for all tools (`man wsssh`, `man wsscp`, etc.)
- **Issues**: Report bugs and request features on GitHub - **Issues**: Report bugs and request features on GitHub
- **Documentation**: See the [docs/](docs/) directory for detailed documentation - **Community**: Join discussions and get help
- **Community**: Join our community discussions
## Donations ## Donations
If you find WSSH useful, please consider supporting the project: If you find WSSSH useful, please consider supporting the project:
### PayPal ### PayPal
Donate via PayPal to: **info@nexlab.net** Donate via PayPal to: **info@nexlab.net**
...@@ -673,181 +399,10 @@ Donate via PayPal to: **info@nexlab.net** ...@@ -673,181 +399,10 @@ Donate via PayPal to: **info@nexlab.net**
Your support helps us continue developing and maintaining this open-source project! ❤️ Your support helps us continue developing and maintaining this open-source project! ❤️
## Changelog ## License
### Version 1.5.0 (Latest) This project is licensed under the GNU General Public License v3.0 (GPLv3).
**Peer-to-Peer Tunneling Architecture:** Copyright (C) 2024 Stefy Lanza <stefy@nexlab.net> and SexHack.me
- Added `--tunnel` option to wsssh and wsscp for data channel transport specification
- Added `--tunnel-control` option to wsssh, wsscp, and wssshc for control channel transport specification See [LICENSE.md](LICENSE.md) for the full license text.
- Added `--service` option to wsssh and wsscp for service type specification (default: "ssh") \ No newline at end of file
- Implemented transport definitions with `is_relay` property and weight-based selection
- Added WebSocket transport with `is_relay=true` as the primary transport implementation
- Created comprehensive transport selection logic with weight-based prioritization
- Implemented "any" transport option that expands to all available transports
- Added transport list expansion function for proper "any" option handling
- Enhanced configuration system with new tunneling options in config files
- Updated server-side architecture with new tunnel attributes and transport handling
- Modified client-side C implementations with new command-line options
- Updated all man pages with comprehensive tunneling option documentation
- Fixed critical transport list expansion for "any" option functionality
### Version 1.4.8
**Critical SSL Connection Stability:**
- Fixed WebSocket frame sending failures that caused connection drops
- Added detailed SSL error reporting with specific error codes and descriptions
- Implemented automatic retry logic for transient SSL errors (SSL_ERROR_WANT_READ/WRITE)
- Added 5-second timeout protection for SSL read operations to prevent indefinite hangs
- Enhanced connection state validation before SSL operations
- Improved WebSocket frame transmission with retry mechanisms and partial write handling
### Version 1.4.7
**Critical Bug Fix:**
- **Process Exit Issue Resolution**: Fixed wsssh process hanging after SSH client disconnection
- Added `broken` flag to tunnel structure to distinguish between normal closure and broken connections
- Implemented proper tunnel state tracking for EBADF, EPIPE, and ECONNRESET errors
- Enhanced error handling in `handle_tunnel_data()` for SSH client disconnections
- Fixed main loop to immediately kill SSH child process and exit when tunnel breaks
- Added proper exit code handling: 0 for normal termination, 1 for error conditions
- Prevented indefinite hanging of wsssh process after tunnel failures
**Technical Improvements:**
- **Tunnel State Management**: Added `int broken` field to `tunnel_t` structure for connection state tracking
- **Error Detection**: Enhanced detection of broken SSH connections with proper error classification
- **Process Management**: Improved SSH child process termination logic with immediate cleanup
- **Exit Code Standards**: Implemented standard exit codes (0=success, 1=error) for better automation support
- **Memory Management**: Maintained proper cleanup of tunnel resources in all exit paths
### Version 1.4.6
**Major Refactoring:**
- **Code Architecture Overhaul**: Major refactoring to eliminate code duplication
- Created shared libraries: `wssshlib.h/.c`, `websocket.h/.c`, `wssh_ssl.h/.c`, `tunnel.h/.c`
- Extracted ~1500+ lines of duplicate code between wsssh.c and wssshc.c
- Improved maintainability and code organization with modular architecture
- Enhanced build system with proper library dependencies
**SSH Tunneling Enhancements:**
- **Enhanced Tunnel Stability**: Improved SSH tunnel handling and error recovery
- Added specific handling for EBADF (Bad file descriptor) errors
- Improved error handling in handle_tunnel_data for SSH client disconnections
- Removed aggressive socket validation causing SSH client disconnections
- Fixed SSH client socket invalidation issue in handle_tunnel_data
- Added missing SSH client accept() logic in wsssh socket handling
- Fixed SSH tunneling timing issue with proper data buffering
- Implemented correct SSH tunneling architecture for wssshc
- Fixed critical architectural issue in wssshc tunnel handling
- Enhanced error handling for broken SSH connections
**Critical Bug Fixes:**
- **Port Option Behavior Correction**: Fixed critical port option behavior
- `-p`/`-P` options now correctly specify wssshd server port (not SSH/SCP server port)
- Removed misleading "passed through to ssh/scp" documentation
- Updated help text to clearly indicate port options are consumed by wsssh/wsscp
- Fixed argument parsing to properly handle wssshd server port specification
**User Experience Improvements:**
- **Help Documentation Cleanup**: Fixed duplicate "Options:" sections in help output
- Removed duplicate "Options:" sections from both wsssh and wsscp help
- Consolidated all options into single, clean "Options:" section
- Improved user experience with clearer documentation
**Technical Improvements:**
- **Library Dependencies**: New build system properly links wsssh and wsscp against shared libraries
- **Code Deduplication**: Eliminated redundant implementations of WebSocket, SSL, and tunnel functions
- **SSH Tunnel Reliability**: Enhanced tunnel stability with improved error handling and connection management
- **Port Handling**: Fixed hostname parsing and port precedence logic
- **Build System**: Updated configure.sh and Makefile to handle new library structure
- **Backward Compatibility**: All existing functionality preserved, new features are additive
### Version 1.4.5
**Removed:**
- **Python Implementations**: Removed Python implementations of wssshc, wsssh, and wsscp
- Deleted wssshc.py, wsssh.py, and wsscp.py files
- Removed pyinstaller commands from build.sh for these tools
- Updated Debian packaging to exclude Python script installations
- Cleaned up documentation and project structure references
- Maintained C implementations in wssshtools/ directory
**Changed:**
- **Build System**: Updated build.sh to only build C tools and wssshd daemon
- **Documentation**: Updated README.md, DOCUMENTATION.md, and project structure to reflect C-only implementations
- **Debian Packaging**: Modified wssshtools/debian/rules to only install wssshd.py and C tools
### Version 1.4.4
**New Features:**
- **Dynamic Terminal Sizing**: Web terminal automatically adjusts to browser window dimensions
- **Real-time Resize**: Terminal resizes dynamically when browser window changes
- **Force Echo Mode**: SSH connections now force echo mode for better visibility
- **Enhanced Logging**: Complete logrotate integration for daemon processes
- **Full-Screen Applications**: Applications like `top`, `htop`, `vim` now use full terminal area
**Technical Improvements:**
- Proper terminal dimension calculation and transmission
- SIGWINCH signal handling for SSH process updates
- Log file management with rotation policies
- Backend resize API for dynamic terminal updates
### Version 1.4.3
- **Debian Package Build System Fixes**: Comprehensive fixes for wsssh-server package building
- Fixed Makefile syntax error in debian/rules by replacing here document with echo commands
- Resolved "missing separator" error caused by tab characters in PyInstaller spec generation
- Removed redundant debian/compat file causing debhelper compatibility conflicts
- Added automatic directory creation in install target to prevent "No such file or directory" errors
- Implemented binary reuse logic to avoid unnecessary rebuilds of wssshd binary
- Enhanced build efficiency by copying existing binaries from dist/ directory when available
- Fixed --server-only option to properly build wsssh-server Debian package
- **Build System Improvements**: Enhanced build script functionality and error handling
- More robust error handling and directory creation for Debian package builds
- Intelligent reuse of existing build artifacts to reduce build times
- Improved output messages showing package build status
- Better dependency checking and error reporting for Debian builds
### Version 1.4.1
- **Watchdog Scripts for High Availability**: Professional daemon monitoring and automatic restart
- `wssshd-watchdog`: Comprehensive watchdog script for wssshd daemon with automatic restart on failure
- `wssshc-watchdog`: Watchdog script for wssshc client daemon with configurable restart limits
- Enhanced init scripts that launch daemons through watchdog for process supervision
- Configurable monitoring intervals (default: 30 seconds) and restart policies
- Prevents restart loops with 5-restart limit per 5-minute window
- Detailed logging to /var/log/wssshd/watchdog.log and /var/log/wssshc/watchdog.log
- Integration with syslog for system monitoring and troubleshooting
- Proper signal handling and resource cleanup on shutdown
- **Enterprise Reliability Features**: Production-grade process supervision and monitoring
- Automatic daemon restart on unexpected termination or crashes
- Non-blocking watchdog operation that doesn't interfere with normal service operation
- Enhanced service status reporting showing both daemon and watchdog process information
- Robust error handling for various failure scenarios and edge cases
- Professional standards compliance for enterprise deployment
### Version 1.4.0
- **wsssh-server Debian Package**: Complete standalone Debian package for wssshd daemon
- **PyInstaller Binary Packaging**: wssshd packaged as standalone executable with no Python dependencies
- **Professional Service Management**: Complete init scripts with wssshd user/group support and rc2.d integration
- **Comprehensive wssshd Man Page**: Full documentation for wssshd daemon with usage examples and configuration
- **Enhanced Build System**: Updated build.sh with --server-only option for selective package building
- **Multi-Package Architecture**: Separate wsssh-server (daemon) and wsssh-tools (clients) packages
- **Security Hardening**: Dedicated wssshd user/group with minimal privileges and proper file ownership
- **System Integration**: Complete Debian packaging with postinst/postrm scripts and service management
- **Configuration Management**: /etc/default/wssshd service control and /etc/wssshd.conf configuration
- **Enterprise Ready**: Production-grade deployment with professional standards compliance
### Version 1.3.4
- **Enhanced WebSocket Connection Management**: Robust ping/pong frame handling and automatic reconnection for wsssh.c and wsscp.c
- **Fixed Ping Frame Parsing**: Corrected WebSocket ping frame processing in C implementations with proper pong responses
- **Automatic Reconnection Logic**: Added smart reconnection with 1-second intervals for WebSocket recovery and configurable --interval for initial setup
- **Improved Connection Resilience**: Better handling of network interruptions with seamless tunnel recovery
- **Enhanced Debug Output**: Clear logging for connection state changes and reconnection attempts
### Previous Updates
- Enhanced logo assets with higher quality versions for better visual presentation
- Improved C implementation files for better performance and reliability
- Added dedicated clean script for easier project maintenance
See [CHANGELOG.md](CHANGELOG.md) for complete version history and changes.
\ No newline at end of file
TODO.md
View file @ b7dae7b4
# WSSSH:: Warp-Powered Stefy's Spatial Secure Hyperdrive - Future Enhancements Roadmap # WSSSH: Warp-Powered Stefy's Spatial Secure Hyperdrive - Future Enhancements Roadmap
## Recently Completed (v1.6.1) ## Recently Completed (v1.6.1)
- [x] **Major Code Refactoring**: Complete modularization of `wsssht.c` for improved maintainability - [x] **Major Code Refactoring**: Complete modularization of `wsssht.c` for improved maintainability
...@@ -24,8 +24,6 @@ ...@@ -24,8 +24,6 @@
- Real-time JSON status updates during tunnel establishment - Real-time JSON status updates during tunnel establishment
- Command processing from stdin with JSON responses - Command processing from stdin with JSON responses
- Structured error reporting and connection status - Structured error reporting and connection status
- **Tunnel control channel messages are communicated through stdin/stdout** (JSON protocol)
- **Tunnel data channel messages remain handled by wsssht** (normal forwarding)
- Perfect for programmatic integration and automation - Perfect for programmatic integration and automation
- [x] **Script Mode Implementation**: JSON protocol for scripting - [x] **Script Mode Implementation**: JSON protocol for scripting
- Periodic status updates (every 30 seconds) - Periodic status updates (every 30 seconds)
...@@ -38,7 +36,7 @@ ...@@ -38,7 +36,7 @@
- Seamless transition to normal operation after first connection - Seamless transition to normal operation after first connection
- Reduced resource usage for intermittent connections - Reduced resource usage for intermittent connections
- [x] **Configuration Support**: Extended config file support for new modes - [x] **Configuration Support**: Extended config file support for new modes
- `mode` and `daemon` options in `[wssht]` section - `mode` and `daemon` options in `[wsssht]` section
- Command-line options override config file values - Command-line options override config file values
- Backward compatibility with existing configurations - Backward compatibility with existing configurations
- [x] **Command-Line Interface**: Extended CLI with new operating mode options - [x] **Command-Line Interface**: Extended CLI with new operating mode options
...@@ -53,7 +51,7 @@ ...@@ -53,7 +51,7 @@
- Updated configuration examples - Updated configuration examples
## Recently Completed (v1.5.0) ## Recently Completed (v1.5.0)
- [x] **Peer-to-Peer Tunneling Architecture**: Complete implementation of advanced tunneling system - [x] **Universal Tunneling Architecture**: Complete implementation of advanced tunneling system
- Added `--tunnel` option to wsssh and wsscp for data channel transport specification - Added `--tunnel` option to wsssh and wsscp for data channel transport specification
- Added `--tunnel-control` option to wsssh, wsscp, and wssshc for control channel transport specification - Added `--tunnel-control` option to wsssh, wsscp, and wssshc for control channel transport specification
- Added `--service` option to wsssh and wsscp for service type specification (default: "ssh") - Added `--service` option to wsssh and wsscp for service type specification (default: "ssh")
...@@ -153,11 +151,6 @@ ...@@ -153,11 +151,6 @@
- Cleaned up documentation and project structure references - Cleaned up documentation and project structure references
- Maintained C implementations in wssshtools/ directory - Maintained C implementations in wssshtools/ directory
### Changed
- [x] **Build System**: Updated build.sh to only build C tools and wssshd daemon
- [x] **Documentation**: Updated README.md, DOCUMENTATION.md, and project structure to reflect C-only implementations
- [x] **Debian Packaging**: Modified wssshtools/debian/rules to only install wssshd.py and C tools
## Recently Completed (v1.4.4) ## Recently Completed (v1.4.4)
- [x] **Dynamic Terminal Sizing**: Implemented proper terminal dimension calculation and transmission - [x] **Dynamic Terminal Sizing**: Implemented proper terminal dimension calculation and transmission
- [x] **Terminal Resize Support**: Added real-time terminal resizing when browser window changes - [x] **Terminal Resize Support**: Added real-time terminal resizing when browser window changes
...@@ -179,9 +172,6 @@ ...@@ -179,9 +172,6 @@
- [x] **Documentation Updates**: Updated CHANGELOG.md, README.md, and DOCUMENTATION.md for version 1.4.3 - [x] **Documentation Updates**: Updated CHANGELOG.md, README.md, and DOCUMENTATION.md for version 1.4.3
## Web Interface Improvements ## Web Interface Improvements
- [x] **Terminal Resizing and Dimensions**: Fixed terminal sizing to use actual browser window dimensions
- [x] **Dynamic Terminal Resize**: Implemented real-time terminal resizing on browser window changes
- [x] **Echo Mode Handling**: Resolved password echo issues by forcing echo mode appropriately
- [ ] **Better web terminal interface and functionality** - [ ] **Better web terminal interface and functionality**
- Improve xterm.js integration and responsiveness - Improve xterm.js integration and responsiveness
- Add support for terminal themes and customization - Add support for terminal themes and customization
...@@ -189,15 +179,15 @@ ...@@ -189,15 +179,15 @@
- Implement better error handling for terminal sessions - Implement better error handling for terminal sessions
## Advanced Tunneling Features ## Advanced Tunneling Features
- [ ] **Additional tunnels/ports for VNC, HTTP/HTTPS** - [ ] **Additional transport protocols**
- Implement VNC tunneling support for remote desktop access - Implement additional transport protocols beyond WebSocket
- Add HTTP/HTTPS proxy tunneling capabilities - Add transport negotiation and fallback mechanisms
- Support for custom port forwarding rules - Support for custom transport plugins
- Integration with popular remote access protocols - Integration with popular tunneling protocols
- Secure tunnel multiplexing for multiple services - Secure transport multiplexing for multiple services
## Multi-User and Group Management ## Multi-User and Group Management
- [ ] **Multi-groups with different password and web interface users association** - [ ] **Multi-user support with different password and web interface access**
- Implement user groups with different access levels - Implement user groups with different access levels
- Group-based password policies and authentication - Group-based password policies and authentication
- Web interface user association with specific groups - Web interface user association with specific groups
...@@ -205,7 +195,7 @@ ...@@ -205,7 +195,7 @@
- Group-specific configuration profiles - Group-specific configuration profiles
## Resource Management and Limits ## Resource Management and Limits
- [ ] **Active IDs limits per user/group** - [ ] **Active client limits per user/group**
- Implement connection limits per user - Implement connection limits per user
- Group-based resource allocation - Group-based resource allocation
- Active session monitoring and management - Active session monitoring and management
...@@ -232,15 +222,6 @@ ...@@ -232,15 +222,6 @@
- Resource usage monitoring and limits - Resource usage monitoring and limits
- Performance profiling and bottleneck identification - Performance profiling and bottleneck identification
## Peer-to-Peer Architecture
- [ ] **Peer-to-peer with NAT traversal/evasion for better performance**
- Implement P2P connection establishment
- NAT traversal techniques (STUN, TURN, ICE)
- Direct peer connections for reduced latency
- NAT evasion strategies for restricted networks
- Hybrid P2P/centralized architecture options
- Bandwidth optimization for P2P connections
## Monitoring and Logging ## Monitoring and Logging
- [ ] **Comprehensive monitoring system** - [ ] **Comprehensive monitoring system**
- Real-time metrics and dashboards - Real-time metrics and dashboards
...@@ -288,11 +269,6 @@ ...@@ -288,11 +269,6 @@
- .pkg installer package - .pkg installer package
- Integration with macOS Keychain - Integration with macOS Keychain
- Native UI elements support - Native UI elements support
- [ ] **Android wssshc implementation (future)**
- Android NDK native client
- Java/Kotlin wrapper application
- Google Play Store distribution
- Android-specific security features
## Platform Support ## Platform Support
- [ ] **Extended platform compatibility** - [ ] **Extended platform compatibility**
...@@ -306,15 +282,14 @@ ...@@ -306,15 +282,14 @@
### High Priority (Next Release) ### High Priority (Next Release)
- Better web terminal interface and functionality fixes - Better web terminal interface and functionality fixes
- Active IDs limits per user/group - Active client limits per user/group
- Enhanced error handling and user feedback - Enhanced error handling and user feedback
- Stability and performance improvements - Stability and performance improvements
### Medium Priority (Future Releases) ### Medium Priority (Future Releases)
- Additional tunnels/ports for VNC, HTTP/HTTPS - Additional transport protocols
- Multi-groups with different password policies - Multi-user support with different password policies
- Performance optimizations and monitoring - Performance optimizations and monitoring
- Peer-to-peer with NAT traversal/evasion
- Windows and macOS wssshc implementations - Windows and macOS wssshc implementations
### Low Priority (Long-term) ### Low Priority (Long-term)
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment