WebSSH2 Client is an HTML5 web-based terminal emulator and SSH client. It uses WebSockets to communicate with a WebSSH2 server, which in turn uses SSH2 to connect to SSH servers.
The current status is experimental, and this first version is a refactor of webssh2 v0.2.x to be compatible with a refactor of the same version of webssh2 as a stand-alone server-side component running Node.js v6.9.1.
The intention is to harmonize the latest release of webssh2 by splitting out the client and server as separate repos (webssh2-client and webssh2-server) but joining them both together as modules in a parent webssh2 in an attempt to provide backward compatibility.
The main idea behind bifurcating the client/server is to make it easier to customize the client to work in other frameworks and use cases.
- Requirements
- Installation
- Usage
- Configuration
- Features
- Routes
- Development
- Advanced Configuration
- Support
- License
- Acknowledgments
- Modern web browser with JavaScript enabled
- WebSSH2 server (see server README for setup instructions)
-
Clone the repository:
git clone https://github.com/billchurch/webssh2_client.git cd webssh2_client
-
Install dependencies:
npm install
-
Build the client:
npm run build
-
The built client files will be in the
client/public
directory.
-
Set up and start the WebSSH2 server (see server README for instructions).
-
Access the web client by navigating to the server's URL, typically:
http://localhost:2222/ssh
-
You'll be prompted for host details and SSH credentials.
The client can be configured using URL parameters or through the config file on the server. Some configurable options include:
port
- SSH server port (default: 22)header
- Optional header textheaderBackground
- Optional header background colorsshterm
- Terminal type for pty (default: xterm-color)
For a full list of configuration options, refer to the server README.
- Web-based SSH client with xterm.js terminal emulation
- Supports various SSH authentication methods (password and keyboard-interactive)
- Customizable terminal settings (font size, font family, colors, etc.)
- Session logging with download option
- Support for reauthentication and credential replay
- Responsive design for various screen sizes
- Keyboard shortcuts support
- Terminal Mouse support
- Copy and paste functionality
- Multi-factor authentication support
- CORS support for flexible server setups
The WebSSH2 Server (not provided by this package) provides two main routes:
- Interactive login form
- Terminal configuration options
- Quick connections to specific hosts
- Optional
port
parameter (e.g.,?port=2222
) - HTTP Basic Authentication for credentials
- To add custom JavaScript, modify
./src/client.htm
,./src/index.js
, or add your file towebpack.*.js
. - For security, use HTTPS when transmitting credentials via HTTP Basic Auth.
- Terminal settings can be customized after login via
Menu | Settings
and persist across sessions. - Debug mode can be enabled by setting the
DEBUG
environment variable.
In the client HTML file, you'll find this script tag:
<script>
window.webssh2Config = null;
</script>
The WebSSH2 server replaces this null value with a configuration object. However, you can also set this manually to override server-provided settings or to configure the client when using it standalone.
Here's a comprehensive list of parameters that can be injected using window.webssh2Config
:
window.webssh2Config = {
socket: {
url: null, // WebSocket URL. If null, it will be automatically determined
path: '/ssh/socket.io', // Socket.IO path
},
ssh: {
host: null, // SSH server hostname (required for autoConnect)
port: 22, // SSH server port
username: null, // SSH username (required for autoConnect)
password: null, // SSH password (required for autoConnect)
sshterm: 'xterm-color', // Terminal type
readyTimeout: 20000, // SSH connection timeout (ms)
},
header: {
text: null, // Custom header text
background: 'green', // Header background color
},
autoConnect: false // Whether to connect automatically
};
The autoConnect
option is used to create pre-configured connections:
- When set to
true
, the client will attempt to connect immediately using the provided SSH configuration, bypassing the login form. - For
autoConnect
to work, you must provide at least thehost
in the SSH configuration. autoConnect
requires a username and password. If these are not provided, the server may use other methods (like basic auth or session data) to authenticate the connection.- If the host is missing when
autoConnect
istrue,
the login form will be shown instead.
Example usage:
window.webssh2Config = {
ssh: {
host: 'example.com',
port: 22,
username: 'user', // Optional
password: 'password' // Optional
},
autoConnect: true
};
This configuration will attempt to connect to example.com
as soon as the page loads, using any provided credentials or relying on server-side authentication methods.
The autoConnect
feature only requires the host to be specified. The server handles authentication, which may use various methods, including basic auth or session data.
- If you do include a username and password in the client-side configuration, be cautious, as this may pose security risks, especially in production environments.
- For production use, consider using secure server-side authentication methods rather than including credentials in the client-side configuration.
When
autoConnect
is not used, ensure your server is configured to prompt for or securely handle credentials as needed.
-
Setting a custom header:
window.webssh2Config = { header: { text: 'My Custom SSH Client', background: '#007acc' } };
-
Configuring for a specific SSH server with auto-connect:
window.webssh2Config = { ssh: { host: 'myserver.example.com', port: 2222 }, autoConnect: true };
By leveraging these configuration options, you can customize the WebSSH2 client to suit your needs or integrate it seamlessly into your existing systems. Remember that the server handles authentication, providing flexibility in managing and securing credentials.
If you find this project helpful, you can support the developer:
This project is licensed under the MIT License - see the LICENSE.md file for details.