README.md (5129B)
1 ## WebSSH 2 3 [](https://travis-ci.org/huashengdun/webssh) 4 [](https://codecov.io/gh/huashengdun/webssh) 5  6  7 8 9 ### Introduction 10 11 A simple web application to be used as an ssh client to connect to your ssh servers. It is written in Python, base on tornado, paramiko and xterm.js. 12 13 ### Features 14 15 * SSH password authentication supported, including empty password. 16 * SSH public-key authentication supported, including DSA RSA ECDSA Ed25519 keys. 17 * Encrypted keys supported. 18 * Two-Factor Authentication (time-based one-time password) supported. 19 * Fullscreen terminal supported. 20 * Terminal window resizable. 21 * Auto detect the ssh server's default encoding. 22 * Modern browsers including Chrome, Firefox, Safari, Edge, Opera supported. 23 24 25 ### Preview 26 27  28  29 30 31 ### How it works 32 ``` 33 +---------+ http +--------+ ssh +-----------+ 34 | browser | <==========> | webssh | <=======> | ssh server| 35 +---------+ websocket +--------+ ssh +-----------+ 36 ``` 37 38 ### Requirements 39 40 * Python 2.7/3.4+ 41 42 43 ### Quickstart 44 45 1. Install this app, run command `pip install webssh` 46 2. Start a webserver, run command `wssh` 47 3. Open your browser, navigate to `127.0.0.1:8888` 48 4. Input your data, submit the form. 49 50 51 ### Server options 52 53 ```bash 54 # start a http server with specified listen address and listen port 55 wssh --address='2.2.2.2' --port=8000 56 57 # start a https server, certfile and keyfile must be passed 58 wssh --certfile='/path/to/cert.crt' --keyfile='/path/to/cert.key' 59 60 # missing host key policy 61 wssh --policy=reject 62 63 # logging level 64 wssh --logging=debug 65 66 # log to file 67 wssh --log-file-prefix=main.log 68 69 # more options 70 wssh --help 71 ``` 72 73 ### Browser console 74 75 ```javascript 76 // connect to your ssh server 77 wssh.connect(hostname, port, username, password, privatekey, passphrase, totp); 78 79 // pass an object to wssh.connect 80 var opts = { 81 hostname: 'hostname', 82 port: 'port', 83 username: 'username', 84 password: 'password', 85 privatekey: 'the private key text', 86 passphrase: 'passphrase', 87 totp: 'totp' 88 }; 89 wssh.connect(opts); 90 91 // without an argument, wssh will use the form data to connect 92 wssh.connect(); 93 94 // set a new encoding for client to use 95 wssh.set_encoding(encoding); 96 97 // reset encoding to use the default one 98 wssh.reset_encoding(); 99 100 // send a command to the server 101 wssh.send('ls -l'); 102 ``` 103 104 ### Custom Font 105 106 To use custom font, put your font file in the directory `webssh/static/css/fonts/` and restart the server. 107 108 ### URL Arguments 109 110 Support passing arguments by url (query or fragment) like following examples: 111 112 Passing form data (password must be encoded in base64, privatekey not supported) 113 ```bash 114 http://localhost:8888/?hostname=xx&username=yy&password=str_base64_encoded 115 ``` 116 117 Passing a terminal background color 118 ```bash 119 http://localhost:8888/#bgcolor=green 120 ``` 121 122 Passing a terminal font color 123 ```bash 124 http://localhost:8888/#fontcolor=red 125 ``` 126 127 Passing a user defined title 128 ```bash 129 http://localhost:8888/?title=my-ssh-server 130 ``` 131 132 Passing an encoding 133 ```bash 134 http://localhost:8888/#encoding=gbk 135 ``` 136 137 Passing a font size 138 ```bash 139 http://localhost:8888/#fontsize=24 140 ``` 141 142 Passing a command executed right after login 143 ```bash 144 http://localhost:8888/?command=pwd 145 ``` 146 147 Passing a terminal type 148 ```bash 149 http://localhost:8888/?term=xterm-256color 150 ``` 151 152 ### Use Docker 153 154 Start up the app 155 ``` 156 docker-compose up 157 ``` 158 159 Tear down the app 160 ``` 161 docker-compose down 162 ``` 163 164 ### Tests 165 166 Requirements 167 ``` 168 pip install pytest pytest-cov codecov flake8 mock 169 ``` 170 171 Use unittest to run all tests 172 ``` 173 python -m unittest discover tests 174 ``` 175 176 Use pytest to run all tests 177 ``` 178 python -m pytest tests 179 ``` 180 181 ### Deployment 182 183 Running behind an Nginx server 184 185 ```bash 186 wssh --address='127.0.0.1' --port=8888 --policy=reject 187 ``` 188 ```nginx 189 # Nginx config example 190 location / { 191 proxy_pass http://127.0.0.1:8888; 192 proxy_http_version 1.1; 193 proxy_read_timeout 300; 194 proxy_set_header Upgrade $http_upgrade; 195 proxy_set_header Connection "upgrade"; 196 proxy_set_header Host $http_host; 197 proxy_set_header X-Real-IP $remote_addr; 198 proxy_set_header X-Real-PORT $remote_port; 199 } 200 ``` 201 202 Running as a standalone server 203 ```bash 204 wssh --port=8080 --sslport=4433 --certfile='cert.crt' --keyfile='cert.key' --xheaders=False --policy=reject 205 ``` 206 207 208 ### Tips 209 210 * For whatever deployment choice you choose, don't forget to enable SSL. 211 * By default plain http requests from a public network will be either redirected or blocked and being redirected takes precedence over being blocked. 212 * Try to use reject policy as the missing host key policy along with your verified known_hosts, this will prevent man-in-the-middle attacks. The idea is that it checks the system host keys file("~/.ssh/known_hosts") and the application host keys file("./known_hosts") in order, if the ssh server's hostname is not found or the key is not matched, the connection will be aborted.