webssh2/README.md

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

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. Modify config.json:

   {
     "listen": {
       "ip": "0.0.0.0",
       "port": 2222
     }
   }
   

2. Build and run the Docker container:

   docker build -t webssh2 .
   docker run --name webssh2 -d -p 2222:2222 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.

For more detailed information on configuration and usage, please refer to the full documentation or open an issue on GitHub.