Initial commit
This commit is contained in:
NI
215
README.md
Normal file
215
README.md
Normal file
@@ -0,0 +1,215 @@
|
||||
# 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 a 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
|
||||
```
|
||||
|
||||
[Docker]: https://www.docker.com
|
||||
|
||||
### Compile from source code
|
||||
|
||||
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 build` will build 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 specifc your own configuration file by setting `SSHWIFTY_CONFIG`
|
||||
environment variables. For example:
|
||||
|
||||
```
|
||||
$ SSHWIFTY_CONFIG=./sshwifty.conf.json ./sshwifty
|
||||
```
|
||||
|
||||
Then, Sshwifty will load the configuration from file `./sshwifty.conf.json`, and
|
||||
will never try for environment variable.
|
||||
|
||||
### 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",
|
||||
|
||||
// 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
|
||||
"InitialTimeout": 3,
|
||||
|
||||
// How long the connection can be idle before the server disconnects the
|
||||
// client
|
||||
"ReadTimeout": 60,
|
||||
|
||||
// How long the server will wait until the client connect is ready to
|
||||
// recieve new data
|
||||
"WriteTimeout": 60,
|
||||
|
||||
// The interval between internal echo requests
|
||||
"HeartbeatTimeout": 20,
|
||||
|
||||
// Forced delay between each request
|
||||
"ReadDelay": 10,
|
||||
|
||||
// Forced delay between each write
|
||||
"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 counterpart in the
|
||||
configuration file.
|
||||
|
||||
Notice: When you use environment variables to configure Sshwifty, then only one
|
||||
Sshwifty HTTP server is then allowed. There is no way to setup mulitple servers
|
||||
here. If you need to serve on multiple ports, use configuratio file instead.
|
||||
|
||||
Be adviced: 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 [DEPENDENCES.md] for dependences used by this project.
|
||||
|
||||
[LICENSE.md]: LICENSE.md
|
||||
[DEPENDENCES.md]: DEPENDENCES.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 don't send pull request. If you need new function, fork it, and maintain
|
||||
it like one of your own. Appreciated!
|
||||
Reference in New Issue
Block a user