From cfe9b5cb3df02afdc52012e75bee2f184bd8856a Mon Sep 17 00:00:00 2001 From: Bill Church Date: Mon, 19 Aug 2024 12:26:48 +0000 Subject: [PATCH] docs: update README.md docs: add DEPRECATED.md --- DEPRECATED.md | 75 ++++++++++++ README.md | 310 ++++++++++++++++++-------------------------------- 2 files changed, 183 insertions(+), 202 deletions(-) create mode 100644 DEPRECATED.md diff --git a/DEPRECATED.md b/DEPRECATED.md new file mode 100644 index 0000000..1fdc0dd --- /dev/null +++ b/DEPRECATED.md @@ -0,0 +1,75 @@ +# Deprecated Features in WebSSH2 + +This document outlines features, configuration options, and parameters that have been deprecated in the this version of WebSSH2. Please review this information to ensure your setup remains compatible and to make necessary adjustments. + +## Removed `config.json` Options + +The following configuration options have been **removed** from `config.json`: + +### Terminal Configuration + +The following options have been replaced with client-side terminal configuration handling in the browser: + +- `terminal.cursorBlink` (boolean): Whether the cursor blinks. +- `terminal.scrollback` (integer): Scrollback limit. +- `terminal.tabStopWidth` (integer): Tab stop width. +- `terminal.bellStyle` (string): Bell style. + +### Logging Configuration + +- `serverlog.client` (boolean): Enabled or disabled client logging. +- `serverlog.server` (boolean): Enabled or disabled server logging. +- `accesslog` (boolean): Controlled whether access logging was enabled. + +### Other + +- `verify` (boolean): This option was never implemented and has been removed. + +## Removed GET Parameters + +The following GET parameters have been **removed** from the application: + +### Terminal Configuration Parameters + +These have been replaced with client-side terminal configuration handling in the browser: + +- `headerBackground=` +- `readyTimeout=` +- `cursorBlink=` +- `scrollback=` +- `tabStopWidth=` +- `bellStyle=` + +### Header Parameters + +- `allowReplay=` (boolean): Controlled the use of the password replay feature. This is now exclusively controlled from server-side `config.json`. +- `mrhsession=` (string): Used to pass an APM session for event correlation. This unused option has been removed. + +## Required Actions + +1. **Review and Update Configuration Files:** + - Remove references to deprecated options in your `config.json` file. + - If you relied on any of the removed terminal configuration options, implement client-side configurations instead. + +2. **Update Integrations:** + - If your integrations or workflows use any of the removed GET parameters, update them to remove these references. + +3. **Logging and Verification Adjustments:** + - If you relied on `serverlog`, `accesslog`, or `verify` options, you may need to implement custom solutions for logging and verification. + +4. **Client-Side Terminal Configuration:** + - Implement client-side terminal configurations to replace the removed server-side options. + +5. **Review Header Configurations:** + - Update any configurations or integrations that relied on `allowReplay` or `mrhsession` GET parameters. + +6. **Test Your Setup:** + - After making these changes, thoroughly test your WebSSH2 setup to ensure everything works as expected with the new configuration. + +## Additional Notes + +- The removal of these options is part of our effort to simplify the codebase and improve performance. +- If you encounter any issues after updating, please refer to the latest documentation or open an issue on our GitHub repository. +- For the most up-to-date information on configuration options, always refer to the current README.md and configuration files in the repository. + +I appreciate your understanding and cooperation as we continue to improve WebSSH2. If you have any questions or need assistance with these changes, please don't hesitate to reach out to the project maintainers. \ No newline at end of file diff --git a/README.md b/README.md index 68e577a..058e812 100644 --- a/README.md +++ b/README.md @@ -1,239 +1,145 @@ -# WebSSH2 - BIG-IP SERVER ONLY EDITION - -# This branch `bigip-server` is a work in progress and you shouldn't use it - -[![GitHub version](https://badge.fury.io/gh/billchurch%2Fwebssh2.svg)](https://badge.fury.io/gh/billchurch%2Fwebssh2) +# WebSSH2 - Web SSH Client [![Buy Me A Coffee](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/billchurch) -Web SSH Client using ssh2, socket.io, xterm.js, and express +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. -A bare bones example of an HTML5 web-based terminal emulator and SSH client. We use SSH2 as a client on a host to proxy a Websocket / Socket.io connection to a SSH2 server. +![WebSSH2 v0.2.0 demo](https://github.com/billchurch/WebSSH2/raw/master/screenshots/demo-800.gif) -WebSSH2 v0.2.0 demo +## Table of Contents -# Requirements +- [Requirements](#requirements) +- [Installation](#installation) +- [Docker Setup](#docker-setup) +- [Usage](#usage) +- [Configuration](#configuration) +- [Routes](#routes) +- [Deprecation Notice](#deprecation-notice) +- [Tips](#tips) -Node v6.x or above. If using ` route: + +``` http://localhost:2222/ssh/host/127.0.0.1 - -You will be prompted for credentials to use on the SSH server via HTTP Basic authentcaiton. This is to permit usage with some SSO systems that can replay credentials over HTTP basic. - -# Docker Instructions - -Modify config.json - -```json -{ - "listen": { - "ip": "0.0.0.0", - "port": 2222 - } -} ``` -Build and run +You'll be prompted for SSH credentials via HTTP Basic Authentication. -```bash -docker build -t webssh2 . -docker run --name webssh2 -d -p 2222:2222 webssh2 -``` +## Configuration -# Options +### GET Parameters -## GET request vars +- `port=` - _integer_ - SSH server port (default: 22) +- `header=` - _string_ - Optional header text +- `sshTerm=` - _string_ - Terminal type for pty (default: xterm-color) -- **port=** - _integer_ - port of SSH server (defaults to 22) +### Config File Options -- **header=** - _string_ - optional header to display on page +Edit `config.json` to customize the following options: -- **headerBackground=** - _string_ - optional background color of header to display on page +- `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 +- `user.name` - _string_ - Default SSH username (default: null) +- `user.password` - _string_ - Default SSH password (default: null) +- `ssh.host` - _string_ - Default SSH host (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) +- `header.text` - _string_ - Header text (default: null) +- `header.background` - _string_ - Header background color (default: "green") +- `session.name` - _string_ - Session cookie name +- `session.secret` - _string_ - Session secret key +- `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) -- **readyTimeout=** - _integer_ - How long (in milliseconds) to wait for the SSH handshake to complete. **Default:** 20000. **Enforced Values:** Min: 1, Max: 300000 +For detailed SSH algorithm configurations, refer to the full config file. -- **cursorBlink** - _boolean_ - Cursor blinks (true), does not (false) **Default:** true. +## Routes -- **scrollback** - _integer_ - Lines in the scrollback buffer. **Default:** 10000. **Enforced Values:** Min: 1, Max: 200000 +WebSSH2 provides two main routes: -- **tabStopWidth** - _integer_ - Tab stops at _n_ characters **Default:** 8. **Enforced Values:** Min: 1, Max: 100 +### 1. `/ssh` -- **bellStyle** - _string_ - Style of terminal bell: ("sound"|"none"). **Default:** "sound". **Enforced Values:** "sound", "none" +- **URL:** `http(s)://your-webssh2-server/ssh` +- **Features:** + - Interactive login form + - Terminal configuration options -## Headers +### 2. `/ssh/host/:host` -- **allowReplay** - _boolean_ - Allow use of password replay feature, example `allowReplay: true` +- **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`) -- **mrhsession** - _string_ - Can be used to pass APM session for event correlation `mrhsession: abc123` +## Deprecation Notice -## Config File Options +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). -`config.json` contains several options which may be specified to customize to your needs, vs editing the javascript directly. This is JSON format so mind your spacing, brackets, etc... +## Tips -- **listen.ip** - _string_ - IP address node should listen on for client connections, defaults to `127.0.0.1` +- 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. -- **listen.port** - _integer_ - Port node should listen on for client connections, defaults to `2222` - -- **http.origins** - _array_ - COORS origins to allow connections from to socket.io server, defaults to `localhost:2222`. Changed in 0.3.1, to enable previous, less secure, default behavior of everything use `*:*` (not recommended). Check [#240](../../issues/240) - -- **user.name** - _string_ - Specify user name to authenticate with. In normal cases this should be left to the default `null` setting. - -- **user.password** - _string_ - Specify password to authenticate with. In normal cases this should be left to the default `null` setting. - -- **ssh.host** - _string_ - Specify host to connect to. May be either hostname or IP address. Defaults to `null`. - -- **ssh.port** - _integer_ - Specify SSH port to connect to, defaults to `22` - -- **ssh.term** - _string_ - Specify terminal emulation to use, defaults to `xterm-color` - -- **ssh.readyTimeout** - _integer_ - How long (in milliseconds) to wait for the SSH handshake to complete. **Default:** 20000. - -- **ssh.keepaliveInterval** - _integer_ - How often (in milliseconds) to send SSH-level keepalive packets to the server (in a similar way as OpenSSH's ServerAliveInterval config option). Set to 0 to disable. **Default:** 120000. - -- **ssh.keepaliveCountMax** - _integer_ - How many consecutive, unanswered SSH-level keepalive packets that can be sent to the server before disconnection (similar to OpenSSH's ServerAliveCountMax config option). **Default:** 10. - -- **terminal.cursorBlink** - _boolean_ - Cursor blinks (true), does not (false) **Default:** true. - -- **terminal.scrollback** - _integer_ - Lines in the scrollback buffer. **Default:** 10000. - -- **terminal.tabStopWidth** - _integer_ - Tab stops at _n_ characters **Default:** 8. - -- **terminal.bellStyle** - _string_ - Style of terminal bell: (sound|none). **Default:** "sound". - -- **header.text** - _string_ - Specify header text, defaults to `My Header` but may also be set to `null`. When set to `null` no header bar will be displayed on the client. - -- **header.background** - _string_ - Header background, defaults to `green`. - -- **session.name** - _string_ - Name of session ID cookie. it's not a horrible idea to make this something unique. - -- **session.secret** - _string_ - Secret key for cookie encryption. You should change this in production. - -- **options.challengeButton** - _boolean_ - Challenge button. This option, which is still under development, allows the user to resend the password to the server (in cases of step-up authentication for things like `sudo` or a router `enable` command. - -- **options.allowReauth** - _boolean_ - Reauth button. This option creates an option to provide a button to create a new session with new credentials. See [issue 51](../../issues/51) and [pull 85](../../pull/85) for more detail. - -- **algorithms** - _object_ - This option allows you to explicitly override the default transport layer algorithms used for the connection. Each value must be an array of valid algorithms for that category. The order of the algorithms in the arrays are important, with the most favorable being first. Valid keys: - - - **kex** - _array_ - Key exchange algorithms. - - - Default values: - - 1. ecdh-sha2-nistp256 - 2. ecdh-sha2-nistp384 - 3. ecdh-sha2-nistp521 - 4. diffie-hellman-group-exchange-sha256 - 5. diffie-hellman-group14-sha1 - - - Supported values: - - - ecdh-sha2-nistp256 - - ecdh-sha2-nistp384 - - ecdh-sha2-nistp521 - - diffie-hellman-group-exchange-sha256 - - diffie-hellman-group14-sha1 - - diffie-hellman-group-exchange-sha1 - - diffie-hellman-group1-sha1 - - - **cipher** - _array_ - Ciphers. - - - Default values: - - 1. aes128-ctr - 2. aes192-ctr - 3. aes256-ctr - 4. aes128-gcm - 5. aes128-gcm@openssh.com - 6. aes256-gcm - 7. aes256-gcm@openssh.com - 8. aes256-cbc **legacy cipher for backward compatibility, should removed :+1:** - - - Supported values: - - - aes128-ctr - - aes192-ctr - - aes256-ctr - - aes128-gcm - - aes128-gcm@openssh.com - - aes256-gcm - - aes256-gcm@openssh.com - - aes256-cbc - - aes192-cbc - - aes128-cbc - - blowfish-cbc - - 3des-cbc - - arcfour256 - - arcfour128 - - cast128-cbc - - arcfour - - - **hmac** - _array_ - (H)MAC algorithms. - - - Default values: - - 1. hmac-sha2-256 - 2. hmac-sha2-512 - 3. hmac-sha1 **legacy hmac for backward compatibility, should removed :+1:** - - - Supported values: - - - hmac-sha2-256 - - hmac-sha2-512 - - hmac-sha1 - - hmac-md5 - - hmac-sha2-256-96 - - hmac-sha2-512-96 - - hmac-ripemd160 - - hmac-sha1-96 - - hmac-md5-96 - - - **compress** - _array_ - Compression algorithms. - - - Default values: - - 1. none - 2. zlib@openssh.com - 3. zlib - - - Supported values: - - - none - - zlib@openssh.com - - zlib - -- **serverlog.client** - _boolean_ - Enables client command logging on server log (console.log). Very simple at this point, buffers data from client until it receives a line-feed then dumps buffer to console.log with session information for tracking. Will capture anything send from client, including passwords, so use for testing only... Default: false. Example: - - - _serverlog.client: GcZDThwA4UahDiKO2gkMYd7YPIfVAEFW/mnf0NUugLMFRHhsWAAAA host: 192.168.99.80 command: ls -lat_ - -- **serverlog.server** - _boolean_ - not implemented, default: false. - -- **accesslog** - _boolean_ - http style access logging to console.log, default: false - -# Experimental client-side logging - -Clicking `Start logging` on the status bar will log all data to the client. A `Download log` option will appear after starting the logging. You may download at any time to the client. You may stop logging at any time my pressing the `Logging - STOP LOG`. Note that clicking the `Start logging` option again will cause the current log to be overwritten, so be sure to download first. - -# Example: - -http://localhost:2222/ssh/host/192.168.1.1?port=2244&header=My%20Header&headerBackground=red - -# Tips - -- If you want to add custom JavaScript to the browser client you can either modify `./src/client.html` and add a **