287 lines
8.5 KiB
Markdown
287 lines
8.5 KiB
Markdown
# Sshwifty Web SSH & Telnet Client
|
|
|
|
**Sshwifty is a SSH and Telnet connector made for Web.** It can be deployed on
|
|
your computer or server to provide SSH and Telnet access interface to any
|
|
compatible (standard) web browser.
|
|
|
|
|
|
|
|
[](https://travis-ci.org/niruix/sshwifty)
|
|
|
|
## Install
|
|
|
|
### Binary
|
|
|
|
Compiled binaries can be found at the [release] section of the page.
|
|
|
|
Please be advised that those binaries is generated by an automatic proccess,
|
|
the author of this project will NOT verify them. You have to try it at your owk
|
|
risk.
|
|
|
|
[release]: https://github.com/niruix/sshwifty/releases
|
|
|
|
### Docker Image
|
|
|
|
If [Docker] is installed on your machine, you may use our prebuild Docker Image
|
|
by executing following command:
|
|
|
|
```
|
|
$ docker run --detach \
|
|
--restart=always \
|
|
--publish 8182:8182 \
|
|
--name sshwifty \
|
|
niruix/sshwifty:latest
|
|
```
|
|
|
|
When TLS is desired and you don't want to setup Docker Volumes, you can use
|
|
`SSHWIFTY_DOCKER_TLSCERT` and `SSHWIFTY_DOCKER_TLSCERTKEY` environment variables
|
|
to import credential files to the container and automatically apply them:
|
|
|
|
```
|
|
$ openssl req \
|
|
-newkey rsa:4096 -nodes -keyout domain.key -x509 -days 90 -out domain.crt
|
|
$ docker run --detach \
|
|
--restart=always \
|
|
--publish 8182:8182 \
|
|
--env SSHWIFTY_DOCKER_TLSCERT="$(cat domain.crt)" \
|
|
--env SSHWIFTY_DOCKER_TLSCERTKEY="$(cat domain.key)" \
|
|
--name sshwifty \
|
|
niruix/sshwifty:latest
|
|
```
|
|
|
|
The `domain.crt` and `domain.key` must be valid TLS certificate and key file
|
|
located on the machine which the `docker run` command will be executed.
|
|
|
|
[Docker]: https://www.docker.com
|
|
|
|
### Compile from source code (Recommanded if you're a developer)
|
|
|
|
Following tools is required in order to build the software from source code:
|
|
|
|
- `git` to download the source code
|
|
- `node` and `npm` to build front-end application
|
|
- `go` to build back-end application
|
|
|
|
To start the build process, execute:
|
|
|
|
```
|
|
$ git clone https://github.com/niruix/sshwifty
|
|
$ cd sshwifty
|
|
$ npm install
|
|
$ npm run build
|
|
```
|
|
|
|
When done, you can found the newly generated `sshwifty` binary inside current
|
|
working directory.
|
|
|
|
Notice: `Dockerfile` contains the entire build procedure of this software.
|
|
Please refer to it when you encountered any compile/build related problem.
|
|
|
|
### Deploy on the cloud
|
|
|
|
To deploy this project onto the cloud, Google App Engine or Heroku for example,
|
|
you need to first download the source code, then generate it locally before
|
|
deploying it.
|
|
|
|
`npm run generate` command will generate all static files and automatically
|
|
call `go generate ./...` to bind those static files directly into program source
|
|
code. And you need those generated source code to get the software to function.
|
|
|
|
Trying to deploy ungenerated code directly to cloud will lead to failure, as
|
|
required source code is missing.
|
|
|
|
Also keep in mind, if the cloud deployment process is `git` based, you may have
|
|
to modify `.gitignore` file in order to allow all required files to be uploaded.
|
|
|
|
## Configure
|
|
|
|
Sshwifty can be configured through either file or environment variables. By
|
|
default, the configuration loader will try to load file from default paths
|
|
first, when failed, environment variables will be used.
|
|
|
|
You can also specify your own configuration file by setting `SSHWIFTY_CONFIG`
|
|
environment variable. For example:
|
|
|
|
```
|
|
$ SSHWIFTY_CONFIG=./sshwifty.conf.json ./sshwifty
|
|
```
|
|
|
|
This way, Sshwifty will try to load the configuration from file
|
|
`./sshwifty.conf.json`, and never reach for other environment variables.
|
|
|
|
### Configuration file
|
|
|
|
Here is all the options of a configuration file:
|
|
|
|
```
|
|
{
|
|
// HTTP Host. Keep it empty to accept request from all hosts, otherwise, only
|
|
// specified host is allowed to access
|
|
"HostName": "localhost",
|
|
|
|
// Web interface access password. Set to empty to allow public access
|
|
"SharedKey": "WEB_ACCESS_PASSWORD",
|
|
|
|
// Remote dial timeout. This limits how long of time the backend can spend
|
|
// to connect to a remote host. The max timeout will be determined by
|
|
// server configuration (ReadTimeout).
|
|
// (In Seconds)
|
|
"DialTimeout": 10,
|
|
|
|
// Socks5 proxy. When set, Sshwifty backend will try to connect remote through
|
|
// the given proxy
|
|
"Socks5": "localhost:1080",
|
|
|
|
// Username of the Socks5 server. Please set when needed
|
|
"Socks5User": "",
|
|
|
|
// Password of the Socks5 server. Please set when needed
|
|
"Socks5Password": "",
|
|
|
|
// Sshwifty HTTP server, you can set multiple ones to serve on different
|
|
// ports
|
|
"Servers": [
|
|
{
|
|
// Which local network interface this server will be listening
|
|
"ListenInterface": "0.0.0.0",
|
|
|
|
// Which local network port this server will be listening
|
|
"ListenPort": 8182,
|
|
|
|
// Timeout of initial request. HTTP handshake must be finished within
|
|
// this time
|
|
// (In Seconds)
|
|
"InitialTimeout": 3,
|
|
|
|
// How long do the connection can stay in idle before the backend server
|
|
// disconnects the client
|
|
// (In Seconds)
|
|
"ReadTimeout": 60,
|
|
|
|
// How long the server will wait until the client connection is ready to
|
|
// recieve new data. If this timeout is exceed, the connection will be
|
|
// closed.
|
|
// (In Seconds)
|
|
"WriteTimeout": 60,
|
|
|
|
// The interval between internal echo requests
|
|
// (In Seconds)
|
|
"HeartbeatTimeout": 20,
|
|
|
|
// Forced delay between each request
|
|
// (In Milliseconds)
|
|
"ReadDelay": 10,
|
|
|
|
// Forced delay between each write
|
|
// (In Milliseconds)
|
|
"WriteDelay": 10,
|
|
|
|
// Path to TLS certificate file. Set empty to use HTTP
|
|
"TLSCertificateFile": "",
|
|
|
|
// Path to TLS certificate key file. Set empty to use HTTP
|
|
"TLSCertificateKeyFile": ""
|
|
},
|
|
{
|
|
"ListenInterface": "0.0.0.0",
|
|
"ListenPort": 8182,
|
|
"InitialTimeout": 3,
|
|
.....
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
`sshwifty.conf.example.json` is an example of a valid configuration file.
|
|
|
|
### Environment variables
|
|
|
|
Valid environment variables are:
|
|
|
|
```
|
|
SSHWIFTY_HOSTNAME
|
|
SSHWIFTY_SHAREDKEY
|
|
SSHWIFTY_DIALTIMEOUT
|
|
SSHWIFTY_SOCKS5
|
|
SSHWIFTY_SOCKS5_USER
|
|
SSHWIFTY_SOCKS5_PASSWORD
|
|
SSHWIFTY_LISTENPORT
|
|
SSHWIFTY_INITIALTIMEOUT
|
|
SSHWIFTY_READTIMEOUT
|
|
SSHWIFTY_WRITETIMEOUT
|
|
SSHWIFTY_HEARTBEATTIMEOUT
|
|
SSHWIFTY_READDELAY
|
|
SSHWIFTY_WRITEELAY
|
|
SSHWIFTY_LISTENINTERFACE
|
|
SSHWIFTY_TLSCERTIFICATEFILE
|
|
SSHWIFTY_TLSCERTIFICATEKEYFILE
|
|
```
|
|
|
|
The option they represented is corresponded to their counterparts in the
|
|
configuration file.
|
|
|
|
Notice: When you're using environment variables to configure Sshwifty, only one
|
|
Sshwifty HTTP server is then allowed. There is no way to setup mulitple servers
|
|
under this method of configuration. If you need to serve on multiple ports, use
|
|
configuration file instead.
|
|
|
|
Be aware: An invalid value inside following environment variables will cause
|
|
the value to be sliently reset to default during configuration parsing phase
|
|
without warning:
|
|
|
|
```
|
|
SSHWIFTY_DIALTIMEOUT
|
|
SSHWIFTY_INITIALTIMEOUT
|
|
SSHWIFTY_READTIMEOUT
|
|
SSHWIFTY_WRITETIMEOUT
|
|
SSHWIFTY_HEARTBEATTIMEOUT
|
|
SSHWIFTY_READDELAY
|
|
SSHWIFTY_WRITEELAY
|
|
```
|
|
|
|
## FAQ
|
|
|
|
### Why the software says "The time difference is beyond operational limit"?
|
|
|
|
This software requires both the client and the server is running at the same
|
|
date time.
|
|
|
|
Please reload the page. If the error message won't go away, consider resync the
|
|
time on both the client and the server with a trusted time server.
|
|
|
|
### Why I got error "TypeError: Cannot read property 'importKey' of undefined"
|
|
|
|
It's usually because your web browser does not support WebCrypt API, or the
|
|
support has been disabled.
|
|
|
|
If you're using Google Chrome, please use HTTPS when connect to Sshwifty. Chrome
|
|
will disable WebCrypt and many other APIs when the connection is not safe.
|
|
|
|
## License
|
|
|
|
Code of this project is licensed under AGPL, see [LICENSE.md] for detail.
|
|
|
|
Third-party components used by this project are licensed under their respective
|
|
license. See [DEPENDENCIES.md] for dependencies used by this project.
|
|
|
|
[LICENSE.md]: LICENSE.md
|
|
[DEPENDENCIES.md]: DEPENDENCIES.md
|
|
|
|
## Contribute
|
|
|
|
This is a hobbyist project, meaning I don't have too many time to put into it.
|
|
Sorry.
|
|
|
|
Upon release (Which is then you're able to read this file), this project will
|
|
enter _maintaining_ state, which includes doing bug fix and security updates.
|
|
Adding new features however, is not a part of the state.
|
|
|
|
Please do not send pull request. If you need new feature, fork it, and maintain
|
|
it like one of your own project.
|
|
|
|
(Notice: Typo, grammar error or invalid use of language in the source code and
|
|
document is categorized as bug, please report them if you found any. Thank you!)
|
|
|
|
Appreciate your help!
|
|
|
|
Enjoy! |