317 lines
No EOL
13 KiB
Markdown
317 lines
No EOL
13 KiB
Markdown
# WebSSH2 - Web SSH Client
|
|
|
|
|
|
|
|
WebSSH2 is an HTML5 web-based terminal emulator and SSH client. It uses SSH2 as a client on a host to proxy a Websocket / Socket.io connection to an SSH2 server.
|
|
|
|
|
|
|
|
|
|
|
|
## Table of Contents
|
|
|
|
- [Requirements](#requirements)
|
|
- [Installation](#installation)
|
|
- [Docker Setup](#docker-setup)
|
|
- [Usage](#usage)
|
|
- [Configuration](#configuration)
|
|
- [Features](#features)
|
|
- [Routes](#routes)
|
|
- [Deprecation Notice](#deprecation-notice)
|
|
- [Tips](#tips)
|
|
- [Support](#support)
|
|
|
|
## Requirements
|
|
|
|
- Node.js 6.9.1
|
|
|
|
## Installation
|
|
|
|
1. Clone the repository:
|
|
```
|
|
git clone https://github.com/billchurch/webssh2.git
|
|
cd webssh2
|
|
```
|
|
|
|
2. Install dependencies:
|
|
```
|
|
npm install --production
|
|
```
|
|
For development purposes, use `npm install` instead.
|
|
|
|
3. Configure the application by editing `config.json` if needed.
|
|
|
|
4. Start the server:
|
|
```
|
|
npm start
|
|
```
|
|
|
|
## Docker Setup
|
|
|
|
1. Build and run the Docker container (with debug messages):
|
|
```bash
|
|
docker build -t webssh2 .
|
|
docker run --name webssh2 --rm -it -p 2222:2222 -e "DEBUG=webssh*,-webssh2:ssh2" webssh2
|
|
```
|
|
|
|
## Usage
|
|
|
|
Access the web client by navigating to:
|
|
|
|
```
|
|
http://localhost:2222/ssh
|
|
```
|
|
|
|
You'll be prompted for host details and SSH credentials.
|
|
|
|
Alternatively you may use the `/ssh/host/<host>` route:
|
|
|
|
```
|
|
http://localhost:2222/ssh/host/127.0.0.1
|
|
```
|
|
|
|
You'll be prompted for SSH credentials via HTTP Basic Authentication.
|
|
P
|
|
## Configuration
|
|
|
|
### GET Parameters
|
|
|
|
- `port=` - _integer_ - SSH server port (default: `22`)
|
|
- `header=` - _string_ - Optional header text
|
|
- `headerBackground=` - _string_ - Optional background color (default: `"green"`)
|
|
- `sshterm=` - _string_ - Terminal type for pty (default: xterm-color)
|
|
|
|
### Config File Options
|
|
|
|
Edit `config.json` to customize the following options:
|
|
|
|
- `listen.ip` - _string_ - IP address to listen on (default: `"127.0.0.1"`)
|
|
- `listen.port` - _integer_ - Port to listen on (default: `2222`)
|
|
- `http.origins` - _array_ - CORS origins for socket.io (default: `["*:*"]`)
|
|
- `user.name` - _string_ - Default SSH username (default: `null`)
|
|
- `user.password` - _string_ - Default SSH password (default: `null`)
|
|
- `ssh.host` - _string_ - Default SSH host (default: `null`)
|
|
- `user.privatekey` - _string_ - Default SSH private key (default: `null`)
|
|
- `ssh.port` - _integer_ - Default SSH port (default: `22`)
|
|
- `ssh.term` - _string_ - Terminal emulation (default: `"xterm-color"`)
|
|
- `ssh.readyTimeout` - _integer_ - SSH handshake timeout in ms (default: `20000`)
|
|
- `ssh.keepaliveInterval` - _integer_ - SSH keepalive interval in ms (default: `120000`)
|
|
- `ssh.keepaliveCountMax` - _integer_ - Max SSH keepalive packets (default: `10`)
|
|
- `ssh.disableInteractiveAuth` - _boolean_ - When set to `true`, prevents interactive authentication through the web interface. Users must use Basic Authentication via the `/ssh/host/<host>` route. (default: `false`)
|
|
- `ssh.algorithms.cipher` - _array_ - Supported cipher algorithms (default: `["aes128-ctr", "aes192-ctr", "aes256-ctr", "aes128-gcm", "aes128-gcm@openssh.com", "aes256-gcm", "aes256-gcm@openssh.com", "aes256-cbc"]`)
|
|
- `ssh.algorithms.compress` - _array_ - Supported compression methods (default: `["none", "zlib@openssh.com", "zlib"]`)
|
|
- `ssh.algorithms.hmac` - _array_ - Supported HMAC algorithms (default: `["hmac-sha2-256", "hmac-sha2-512", "hmac-sha1"]`)
|
|
- `ssh.algorithms.kex` - _array_ - Supported key exchange methods (default: `["ecdh-sha2-nistp256", "ecdh-sha2-nistp384", "ecdh-sha2-nistp521", "diffie-hellman-group-exchange-sha256", "diffie-hellman-group14-sha1"]`)
|
|
- `ssh.algorithms.serverHostKey` - _array_ - Supported host key types (default: `["ecdsa-sha2-nistp256", "ecdsa-sha2-nistp384", "ecdsa-sha2-nistp521", "ssh-rsa"]`)
|
|
- `header.text` - _string_ - Header text (default: `null`)
|
|
- `header.background` - _string_ - Header background color (default: `"green"`)
|
|
- `session.name` - _string_ - Session cookie name (default: `"webssh2.sid"`)
|
|
- `session.secret` - _string_ - Session secret key (default: `crypto.randomBytes(32).toString("hex")`)
|
|
- `options.challengeButton` - _boolean_ - Enable challenge button (default: `true`)
|
|
- `options.autoLog` - _boolean_ - Enable auto-logging (default: `false`)
|
|
- `options.allowReauth` - _boolean_ - Allow reauthentication (default: `true`)
|
|
- `options.allowReconnect` - _boolean_ - Allow reconnection (default: `true`)
|
|
- `options.allowReplay` - _boolean_ - Allow credential replay (default: `true`)
|
|
|
|
For detailed SSH algorithm configurations, refer to the full config file.
|
|
|
|
## Features
|
|
|
|
### Keyboard Interactive Authentication
|
|
|
|
Keyboard Interactive authentication provides a flexible way to handle various authentication scenarios, including multi-factor authentication.
|
|
|
|
#### How it works
|
|
|
|
1. When the SSH server requests Keyboard Interactive authentication, WebSSH2 can handle it in two ways:
|
|
a) Automatically (default behavior)
|
|
b) By prompting the user through the web interface
|
|
|
|
2. In automatic mode:
|
|
- If all prompts contain the word "password" (case-insensitive), WebSSH2 will automatically respond using the password provided during the initial connection attempt.
|
|
- If any prompt doesn't contain "password", all prompts will be forwarded to the web client for user input.
|
|
|
|
3. When prompts are sent to the web client:
|
|
- A dialog box appears in the user's browser, displaying all prompts from the SSH server.
|
|
- The user can input responses for each prompt.
|
|
- Responses are sent back to the SSH server to complete the authentication process.
|
|
|
|
#### Configuration Options
|
|
|
|
You can customize the Keyboard Interactive authentication behavior using the following option in your `config.json`:
|
|
|
|
```json
|
|
{
|
|
"ssh": {
|
|
"alwaysSendKeyboardInteractivePrompts": false
|
|
}
|
|
}
|
|
```
|
|
|
|
- `alwaysSendKeyboardInteractivePrompts` (boolean, default: false):
|
|
- When set to `true`, all Keyboard Interactive prompts will always be sent to the web client, regardless of their content.
|
|
- When set to `false` (default), WebSSH2 will attempt to automatically handle password prompts and only send non-password prompts to the web client.
|
|
|
|
#### Use Cases
|
|
|
|
1. **Simple Password Authentication**:
|
|
With default settings, if the SSH server uses Keyboard Interactive for password authentication, WebSSH2 will automatically handle it without additional user interaction.
|
|
|
|
2. **Multi-Factor Authentication**:
|
|
For SSH servers requiring additional factors (e.g., OTP), WebSSH2 will present prompts to the user through the web interface.
|
|
|
|
3. **Always Prompt User**:
|
|
By setting `alwaysSendKeyboardInteractivePrompts` to `true`, you can ensure that users always see and respond to all authentication prompts, which can be useful for security-sensitive environments or for debugging purposes.
|
|
|
|
#### Security Considerations
|
|
|
|
- The automatic password handling feature is designed for convenience but may not be suitable for high-security environments. Consider setting `alwaysSendKeyboardInteractivePrompts` to `true` if you want users to explicitly enter their credentials for each session.
|
|
- Ensure that your WebSSH2 installation uses HTTPS to protect the communication between the web browser and the WebSSH2 server.
|
|
|
|
For more information on SSH keyboard-interactive authentication, refer to [RFC 4256](https://tools.ietf.org/html/rfc4256).
|
|
|
|
### SSH Private Key Authentication
|
|
|
|
WebSSH2 supports SSH private key authentication when using the `/ssh/host/` endpoint with a private key configured in the server settings.
|
|
|
|
#### Configuration
|
|
|
|
Private key authentication can only be configured through the `config.json` file:
|
|
|
|
```json
|
|
{
|
|
"user": {
|
|
"name": "myuser",
|
|
"privatekey": "-----BEGIN RSA PRIVATE KEY-----\nYour-Private-Key-Here\n-----END RSA PRIVATE KEY-----",
|
|
"password": "optional-fallback-password"
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Key Requirements
|
|
|
|
- Only `ssh-rsa` type keys are supported
|
|
- The private key must be in PEM format
|
|
- The key in `config.json` must be on a single line with `\n` as line separators
|
|
- Must include the appropriate header and footer:
|
|
```
|
|
-----BEGIN RSA PRIVATE KEY-----\n[... key content ...]\n-----END RSA PRIVATE KEY-----
|
|
```
|
|
|
|
#### Generating a Private Key
|
|
To generate a new SSH private key, you can use the following command:
|
|
|
|
```bash
|
|
ssh-keygen -m PEM -t rsa -b 4096 -f ~/.ssh/id_rsa
|
|
```
|
|
|
|
#### Converting Your Private Key
|
|
|
|
To convert your existing SSH private key into the correct format for `config.json`, you can use this bash command:
|
|
|
|
```bash
|
|
echo '"'$(cat ~/.ssh/id_rsa | tr '\n' '~' | sed 's/~/\\n/g')'"'
|
|
```
|
|
|
|
This command:
|
|
1. Reads your private key file
|
|
2. Converts newlines to temporary characters
|
|
3. Replaces those characters with `\n`
|
|
4. Wraps the result in quotes
|
|
5. Outputs the key in a format ready to paste into your `config.json`
|
|
|
|
#### Authentication Process
|
|
|
|
1. When connecting through the `/ssh/host/` endpoint, WebSSH2 will first attempt to authenticate using the private key specified in `config.json`
|
|
2. If key authentication fails and `user.password` is configured, the system will automatically attempt password authentication
|
|
3. If both authentication methods fail, you'll receive an authentication error
|
|
|
|
#### Endpoint Support
|
|
|
|
- `/ssh/host/:host` - Supports private key authentication configured via `config.json`
|
|
- `/ssh` - Does NOT support private key authentication
|
|
|
|
#### Security Considerations
|
|
|
|
- Store private keys securely in your server configuration
|
|
- Use appropriate file permissions for your `config.json` file
|
|
- Consider using encrypted private keys for additional security
|
|
- Always use HTTPS when accessing the WebSSH2 service
|
|
|
|
#### Example Usage
|
|
|
|
1. Convert and configure your private key:
|
|
```bash
|
|
# First, convert your key
|
|
echo '"'$(cat ~/.ssh/id_rsa | tr '\n' '~' | sed 's/~/\\n/g')'"'
|
|
|
|
# Copy the output and paste it into config.json
|
|
```
|
|
|
|
2. Configure `config.json`:
|
|
```json
|
|
{
|
|
"user": {
|
|
"name": "myuser",
|
|
"privatekey": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpA...[rest of key]...Yh5Q==\n-----END RSA PRIVATE KEY-----",
|
|
"password": "fallback-password"
|
|
}
|
|
}
|
|
```
|
|
|
|
3. Access the service via the `/ssh/host/` endpoint:
|
|
```
|
|
https://your-server:2222/ssh/host/target-server
|
|
```
|
|
|
|
#### Troubleshooting
|
|
|
|
If key authentication fails, check:
|
|
- Key type is `ssh-rsa`
|
|
- Key format in `config.json` is properly escaped with `\n` line separators
|
|
- Key permissions on the target SSH server
|
|
- Server's `authorized_keys` file configuration
|
|
- SSH server logs for specific authentication failure reasons
|
|
|
|
For additional support or troubleshooting, please open an issue on the GitHub repository.
|
|
|
|
## Routes
|
|
|
|
WebSSH2 provides two main routes:
|
|
|
|
### 1. `/ssh`
|
|
|
|
- **URL:** `http(s)://your-webssh2-server/ssh`
|
|
- **Features:**
|
|
- Interactive login form
|
|
|
|
<img width="341" alt="image" src="https://github.com/user-attachments/assets/829d1776-3bc5-4315-b0c6-9e96a648ce06">
|
|
- Terminal configuration options
|
|
|
|
<img width="341" alt="image" src="https://github.com/user-attachments/assets/bf60f5ba-7221-4177-8d64-946907aed5ff">
|
|
|
|
### 2. `/ssh/host/:host`
|
|
|
|
- **URL:** `http(s)://your-webssh2-server/ssh/host/:host`
|
|
- **Authentication:** HTTP Basic Auth
|
|
- **Features:**
|
|
- Quick connections to specific hosts
|
|
- Optional `port` parameter (e.g., `?port=2222`)
|
|
|
|
## Deprecation Notice
|
|
|
|
Several configuration options and GET parameters have been deprecated. For a list of removed options and required actions, please refer to [DEPRECATED.md](./DEPRECATED.md).
|
|
|
|
## Tips
|
|
|
|
- To add custom JavaScript, modify `./src/client.htm`, `./src/index.js`, or add your file to `webpack.*.js`.
|
|
- For security, use HTTPS when transmitting credentials via HTTP Basic Auth.
|
|
- Terminal settings for `/ssh/host/:host` can be customized after login via `Menu | Settings` and persist across sessions.
|
|
- You can enable debug from the console by passing the `DEBUG` environment variable to your start script: `DEBUG=webssh*,-webssh2:ssh2 npm run start`. The `webssh2:ssh2` namespace is very chatty and shows all of the SSH protocol information, the `-webssh2:ssh2` excludes that namespace from the line above, otherwise `DEBUG=webssh*` will capture all of the WebSSH2 specific bits. You may also debug Socket.IO and Express related events with `engine`, `socket` and `express` namespaces, or go for broke and debug everything with `DEBUG=*`.
|
|
|
|
For more detailed information on configuration and usage, please refer to the full documentation or open an issue on GitHub.
|
|
|
|
## Support
|
|
If you like what I do, and want to support me you can [buy me a coffee](https://www.buymeacoffee.com/billchurch)!
|
|
|
|
[](https://www.buymeacoffee.com/billchurch) |