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
• Installation
• Docker Setup
• Usage
• Configuration
• Routes
• Deprecation Notice
• Tips
• 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):

   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.

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)
• 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 (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.

Routes

WebSSH2 provides two main routes:

1. /ssh

• URL: http(s)://your-webssh2-server/ssh
• Features:

  • Interactive login form

    

  • Terminal configuration options

    

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.

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!