jimmyw/ssh_cli_server

readme

| Supported Targets | ESP32 | ESP32-C2 | ESP32-C3 | ESP32-C5 | ESP32-C6 | ESP32-C61 | ESP32-H2 | ESP32-H21 | ESP32-H4 | ESP32-P4 | ESP32-S2 | ESP32-S3 |
| ----------------- | ----- | -------- | -------- | -------- | -------- | --------- | -------- | --------- | -------- | -------- | -------- | -------- |

# SSH CLI Server Component

This ESP-IDF component provides a complete SSH server implementation with an integrated command-line interface. It allows remote access to your ESP32 device over SSH, providing the same console commands that are available over UART/USB.

## Why This Component?

While there are many SSH server implementations available, **this component is specifically designed to provide a true CLI experience** that forwards stdin/stdout just like your local ESP32 console. Unlike basic SSH servers that might only provide file transfer or simple command execution, this implementation:

- **Seamlessly integrates with ESP-IDF Console**: Access the exact same commands available on your local UART/USB console
- **True bidirectional I/O**: Real-time stdin/stdout forwarding with proper terminal emulation
- **Interactive shell experience**: Command history, tab completion, and line editing work exactly as expected
- **Session persistence**: Maintains state and context throughout the SSH session
- **Multiple concurrent sessions**: Each SSH connection gets its own isolated console environment

This bridges the gap between remote access and local development, giving you the same powerful console experience whether you're connected via USB cable or SSH over WiFi.

## Features

- **Full SSH Server**: Built on libssh library with support for key exchange, authentication, and encrypted communication
- **True Console Integration**: Complete stdin/stdout forwarding that works exactly like your local ESP32 console
- **Multiple Authentication Methods**:
  - Password authentication
  - Public key authentication
- **Interactive Shell**: Complete command-line interface with history, tab completion, and line editing
- **Session Tracking**: Real-time client information including IP, authentication method, and connection details
- **VFS Integration**: Thread-safe communication between SSH sessions and ESP console
- **Multi-channel Support**: Handle multiple concurrent SSH connections with isolated environments
- **Console Commands**: Access to all standard ESP-IDF console commands (WiFi, NVS, system info, etc.)
- **Built-in Session Commands**:
  - `session` - View current connection details
  - `exit`/`quit` - Graceful session termination


## Enhanced Shell Features

For an even more powerful shell experience with advanced features like pipes, grep, and other UNIX-style utilities, consider applying this ESP-IDF enhancement:

**ESP Shell Component Enhancement**: [ESP-IDF Pull Request #17793](https://github.com/espressif/esp-idf/pull/17793)

This patch extends the ESP-IDF console component to provide:
- **Pipe support**: Chain commands together (e.g., `help | grep wifi`)
- **Text filtering**: Use `grep` to filter command output
- **Enhanced command composition**: Build complex command pipelines
- **Improved shell scripting**: More sophisticated command interactions

When combined with this SSH server, you get a truly powerful remote shell environment that rivals traditional UNIX shells.

## Dependencies

This component requires:
- `david-cermak/libssh` - SSH library implementation for ESP32
- ESP-IDF v4.4 or later
- WiFi connectivity

## How to use this component

### 1. Add to your project

Add this component to your ESP-IDF project by including it in your `idf_component.yml`:

```yaml
dependencies:
  jimmyw/ssh_cli_server: "*"
```

Or clone this repository into your project's `components` directory.

### 2. Include in your application

```c
#include "ssh_server.h"

// Configure and start SSH server
ssh_server_config_t server_config = {
    .bindaddr = "0.0.0.0",
    .port = "22",
    .debug_level = "1",
    .username = "esp32",
    .host_key = host_key_pem_string,
    .password = "espressif",  // For password auth
    .shell_func = your_shell_function,
    .shell_func_ctx = shell_context,
    .shell_task_size = 8192,
    .shell_task_kill_on_disconnect = true,
};

esp_err_t err = ssh_server_start(&server_config);
```

### 3. Generate SSH Host Key

You need to provide an SSH host key in PEM format. Generate one using:

```bash
ssh-keygen -t ed25519 -f ssh_host_key -N ""
```

Then embed it in your firmware using `embed_files` in CMakeLists.txt or include it as a string.

### 4. Configure Authentication

The component supports multiple authentication methods via Kconfig options:

- `CONFIG_EXAMPLE_ALLOW_PASSWORD_AUTH` - Enable username/password authentication
- `CONFIG_EXAMPLE_ALLOW_PUBLICKEY_AUTH` - Enable public key authentication

## API Reference

### ssh_server_start()

Starts the SSH server with the provided configuration.

```c
esp_err_t ssh_server_start(ssh_server_config_t *config);
```

**Parameters:**
- `config`: Pointer to SSH server configuration structure

**Configuration Structure:**

```c
typedef struct {
    const char *bindaddr;              // IP address to bind (e.g., "0.0.0.0")
    const char *port;                  // Port to listen on (e.g., "22")
    const char *debug_level;           // SSH debug level ("0"-"3")
    const char *username;              // Username for authentication
    const char *host_key;              // SSH host private key (PEM format)
    const char *password;              // Password for password auth
    const char *allowed_pubkeys;       // Authorized public keys
    ssh_shell_func_t shell_func;       // Shell function to execute
    void *shell_func_ctx;              // Context for shell function
    uint32_t shell_task_size;          // Stack size for shell task
    bool shell_task_kill_on_disconnect; // Kill shell task on disconnect
} ssh_server_config_t;
```

## How to use the example

### 1. Configure WiFi

Set your WiFi credentials in menuconfig:
```
idf.py menuconfig
```

Navigate to `Example Configuration` and set:
- WiFi SSID
- WiFi Password

### 2. Build and Flash

```bash
cd examples/example_ssh_server
idf.py build flash monitor
```

### 3. Connect via SSH

Once the device is connected to WiFi, you can SSH to it:

```bash
ssh esp32@<device_ip_address>
# Password: espressif (default)
```

## Example Output

Device console output:
```
I (2000) example: Starting network connection...
I (5000) example: WiFi connected, IP: 192.168.1.100
I (5100) example: Starting SSH server...
I (5200) ssh_server: SSH Server listening on 0.0.0.0:22
I (5300) ssh_server: Default credentials: esp32/espressif
```

SSH client session:
```
$ ssh esp32@192.168.1.100
esp32@192.168.1.100's password:

=== SSH Session Information ===
Client: 192.168.1.50:54321
User: esp32
Auth method: password
Client version: SSH-2.0-OpenSSH_8.9
Session ID: 1
Connected at: 12345 seconds since boot
===============================

Welcome to ESP32 SSH Console
esp32> help
help     Print the list of registered commands
session  Show current SSH session information
exit     Exit the SSH session
quit     Exit the SSH session (alias for exit)
free     Get current free heap memory
esp32> free
Current Free Memory: 234560 bytes
esp32> wifi_info
WiFi Mode: STA
SSID: MyWiFi
IP Address: 192.168.1.100
esp32> session
Session ID: 1
Client: 192.168.1.50:54321
User: esp32
Auth method: password
Client version: SSH-2.0-OpenSSH_8.9
Connected: 12345 seconds since boot
esp32> exit
Connection to 192.168.1.100 closed.
```

## Built-in Commands

The SSH server includes several built-in commands in addition to all standard ESP-IDF console commands:

### Session Management Commands

- **`exit`** or **`quit`**: Gracefully closes the SSH session and returns to the client
- **`session`**: Displays detailed information about the current SSH session including:
  - Client IP address and port
  - Authenticated username
  - Authentication method used (password, publickey)
  - SSH client version string
  - Unique session ID
  - Connection timestamp

### Session Information Display

When you first connect via SSH, the server automatically displays session information showing who connected from where and how they authenticated. This provides immediate visibility into the connection details for security and debugging purposes.

## Troubleshooting

### SSH Connection Refused
- Verify WiFi is connected and device has IP address
- Check firewall settings on both device and client
- Ensure SSH server started successfully (check logs)

### Authentication Failed
- Verify username/password are correct (default: esp32/espressif)
- For public key auth, ensure the public key is properly formatted in authorized_keys format
- Check SSH debug logs by setting debug_level to "3"

### Performance Issues
- Increase shell_task_size if experiencing stack overflow
- Adjust message buffer sizes in ssh_server.c if needed
- Monitor free heap memory during operation

### Memory Issues
- SSH server uses approximately 20KB+ RAM per active connection
- Ensure sufficient free heap before starting SSH server
- Consider limiting concurrent connections for memory-constrained applications

### Build Issues
- Ensure ESP-IDF version is v4.4 or later
- Verify libssh component is properly installed
- Check that all required Kconfig options are enabled