search

billchurch / webssh2

Web SSH Client using ssh2, socket.io, xterm.js, and express. webssh webssh2
MIT License
2.26k stars 527 forks source link
ssh ssh-client web-ssh

readme

WebSSH2

Build Status GitHub version docker build images

Buy Me A Coffee

Web SSH Client using ssh2, socket.io, xterm.js, and express

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

Requirements

Node v14.x or above. If using <v14.x you should be able to run by replacing the "read-config" package to @1 like this (after a clone):

npm install --save read-config@1

Just keep in mind that there is no intention to ensure compatability with Node < v14

Instructions

The instructions previously showed cloning directly from main, while normally safe may include "work in progress". It's recommended that after you clone, you switch to a particular tag.

To install:

  1. Clone to a location somewhere

  2. Checkout to the current tag using git checkout current or choose a particular release tag

  3. cd app and npm install --production. If you want to develop and rebuild javascript and other files utilize npm install instead.

  4. If desired, edit app/config.json to change the listener to your liking. There are also some default options which may be definied for a few of the variables.

  5. Run npm start

  6. Fire up a browser, navigate to IP/port of your choice and specify a host (https isn't used here because it's assumed it will be off-loaded to some sort of proxy):

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.

Alternatively in main for testing, you can send credentials via POST with the variables "username" and "userpassword".

Customizing client files

See BUILDING.md for more details.

Docker

NOTICE

Docker versions differ from what is in main and are release dependant.

Meaning billchurch/webssh2:latest is the latest official release. This does NOT sync with what is in main on this repo. main is development and will change until it gets a release tag.

On occasion, examples or instructions on main will drift from what is released. You should refer to the tag of the version you're using to ensure you are following the proper guidance.

That being said the most current release version is 0.4.6, see that tag for details.

Instructions

Some configuration options are available as Environment Variables. If there is a configuration option you require which does not have an environment variable please open an issue requesting.

webssh2 images are available in docker hub.

the latest tag will pull the most recent stable release, otherwise you can pull individual tags/releases/versions of this repo by using a particular version in the tag.

For instance:

docker pull billchurch/webssh2:0.4.6

or

docker pull billchurch/webssh2:0.4.7-alpha.2

or

docker pull billchurch/webssh2

for the most recent

If you want to play around localy:

Copy app/config.json.template to app/config.json and modify the latter:

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

Rebuild and run

docker build -t webssh2 .
docker run --name webssh2 -d -p 2222:2222 webssh2

Alternatively if you don't want to rebuild, mount the config at runtime:

docker run --name webssh2 -d -p 2222:2222 -v `pwd`/app/config.json:/usr/src/config.json webssh2

Alternatively if you don't want to build either and mount the config at runtime relying on the community image :

docker run --name webssh2 -d -p 2222:2222 -v `pwd`/app/config.json:/usr/src/config.json billchurch/webssh2

Options

Environment Variables

Environment variables introduced in 0.4.7 will override anything specified in config.json. This is useful for settings that may be per-node, or in a container environment. These are optional and will default to whatever their peer config.json settings are

POST request vars (in main branch for testing)

GET request vars

Headers

Config File Options

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...

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

CONTRIBUTING

As of 0.4.0, we're trying our best to conform to the Airbnb Javascript Style Guide. I'm hoping this will make contributions easier and keep the code readable. I love shortcuts more than anyone but I've found when making changes to code I've not looked at in a while, it can take me a few momements to deconstruct what was being done due to readbility issues. While I don't agree with every decision in the style guide (semi-colons, yuk), it is a good base to keep the code consistent.

If you've not used it before, I recommend installing the vscode extensions for that and Prettier and getting familiar. The autocorrections are great (especially if you hate dealing with semi-colons...)

All contributions are welcome, all may not make it into a release... To increase the chances of your contribution making it into a release, try your best to conform to the style guides and targets of the project.

Tips