251 lines
7.1 KiB
Markdown
251 lines
7.1 KiB
Markdown
# Sshwifty Web SSH Client
|
|
|
|
|
|
|
|
Sshwifty is a SSH client that provides a web interface. You can deploy it on
|
|
your computer or server, so you can access SSH servers via any device that have
|
|
a compatible (standard) web browser.
|
|
|
|
|
|
|
|
## Install
|
|
|
|
### Binary
|
|
|
|
You can download compiled binaries at [Release] section of the page.
|
|
|
|
Please noted that those binaries was generated by an automatic proccess, and 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 you have [Docker] installed on your machine, you can directly use the Docker
|
|
image by executing following command:
|
|
|
|
```
|
|
$ docker run --detach \
|
|
--restart=always \
|
|
--publish 8182:8182 \
|
|
--name sshwifty \
|
|
niruix/sshwifty:latest
|
|
```
|
|
|
|
If you want to use TLS (HTTPS) with the Docker image and don't want to setup
|
|
volumes, you can use `SSHWIFTY_DOCKER_TLSCERT` and `SSHWIFTY_DOCKER_TLSCERTKEY`
|
|
environment variables when starting the container:
|
|
|
|
```
|
|
$ docker run --detach \
|
|
--restart=always \
|
|
--publish 8182:8182 \
|
|
--env SSHWIFTY_DOCKER_TLSCERT="$(cat /path/to/domain.crt)"
|
|
--env SSHWIFTY_DOCKER_TLSCERTKEY="$(cat /path/to/domain.key)"
|
|
--name sshwifty \
|
|
niruix/sshwifty:latest
|
|
```
|
|
|
|
`/path/to/domain.crt` and `/path/to/domain.key` must be valid TLS certificate
|
|
and key file located on the machine which the `docker run` command is executed.
|
|
|
|
[Docker]: https://www.docker.com
|
|
|
|
### Compile from source code (Recommanded if you're a developer)
|
|
|
|
In order to use the source code, you need to install following tools:
|
|
|
|
- `git` to download the source code
|
|
- `npm` to compile front-end application
|
|
- `go` to compile back-end application
|
|
|
|
After you have installed those tools, run following command to download the code
|
|
to your computer, and start the build proccess:
|
|
|
|
```
|
|
$ git clone https://github.com/niruix/sshwifty
|
|
$ cd sshwifty
|
|
$ npm install
|
|
$ npm run build
|
|
```
|
|
|
|
If the command succeed, you will found the newly generated `sshwifty` binary
|
|
under current working directory.
|
|
|
|
### 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, build it locally, then try to deploy
|
|
it.
|
|
|
|
The `npm run generate` will generate all static files, then automatically call
|
|
`go generate ./...` to bind those static files directly into program source
|
|
code. You need those generated source code to get application to function. Also
|
|
because of this, directly call `go build .` on the newly downloaded souce code
|
|
will result a failure.
|
|
|
|
## Configure
|
|
|
|
Sshwifty can be configured though either file or environment variables. By
|
|
default, the configuration loader will try to load file from default paths
|
|
first, then try environment variables.
|
|
|
|
You can also specify your own configuration file by setting `SSHWIFTY_CONFIG`
|
|
environment variables. For example:
|
|
|
|
```
|
|
$ SSHWIFTY_CONFIG=./sshwifty.conf.json ./sshwifty
|
|
```
|
|
|
|
After that, Sshwifty will try to load the configuration from file
|
|
`./sshwifty.conf.json`, and never reach for configuration inside environment
|
|
variables.
|
|
|
|
### Configuration file
|
|
|
|
Here is the options that can be used in a configuration file and what it for:
|
|
|
|
```
|
|
{
|
|
// HTTP Host. Keep it empty to accept request from all hosts
|
|
"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, we will try to connect remote through the given
|
|
// proxy
|
|
"Socks5": "localhost:1080",
|
|
|
|
// Username of the Socks5 server. Set when the Socks5 server requires login
|
|
"Socks5User": "",
|
|
|
|
// Password of the Socks5 server. Set when the Socks5 server requires login
|
|
"Socks5Password": "",
|
|
|
|
// Sshwifty HTTP server, you can set multiple ones to serve on different
|
|
// ports
|
|
"Servers": [
|
|
{
|
|
// Which local interface this server will be listening
|
|
"ListenInterface": "0.0.0.0",
|
|
|
|
// Which local 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 the connection can be idle before the server disconnects the
|
|
// client
|
|
// (In Seconds)
|
|
"ReadTimeout": 60,
|
|
|
|
// How long the server will wait until the client connect is ready to
|
|
// recieve new data
|
|
// (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_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 use environment variables to configure Sshwifty, only one
|
|
Sshwifty HTTP server is then allowed. There is no way to setup mulitple servers
|
|
by using this method. 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 reset to default during configuration parsing without warning:
|
|
|
|
```
|
|
SSHWIFTY_INITIALTIMEOUT
|
|
SSHWIFTY_READTIMEOUT
|
|
SSHWIFTY_WRITETIMEOUT
|
|
SSHWIFTY_HEARTBEATTIMEOUT
|
|
SSHWIFTY_READDELAY
|
|
SSHWIFTY_WRITEELAY
|
|
```
|
|
|
|
## 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.
|
|
|
|
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. Appreciated!
|
|
|
|
Enjoy! |