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