diff --git a/README.md b/README.md index 767eb5e..b4bf0c2 100644 --- a/README.md +++ b/README.md @@ -14,11 +14,11 @@ > Terminal access in browser over http/https -![WeTTy](./docs/terminal.png?raw=true) +![WeTTY](./docs/terminal.png?raw=true) -Terminal over HTTP and https. WeTTy is an alternative to ajaxterm and anyterm -but much better than them because WeTTy uses xterm.js which is a full fledged -implementation of terminal emulation written entirely in JavaScript. WeTTy uses +Terminal over HTTP and https. WeTTY is an alternative to ajaxterm and anyterm +but much better than them because WeTTY uses xterm.js which is a full fledged +implementation of terminal emulation written entirely in JavaScript. WeTTY uses websockets rather then Ajax and hence better response time. ## Prerequisites @@ -82,7 +82,7 @@ list of flags ### Docker container -To use wetty as a docker container, a docker image is available on +To use WeTTY as a docker container, a docker image is available on [docker hub](https://hub.docker.com/r/wettyoss/wetty). To run this image, use ```sh @@ -92,7 +92,7 @@ docker run --rm -p 3000:3000 wettyoss/wetty --ssh-host= and you will be able to open a ssh session to the host given by `YOUR-IP` under the URL [http://localhost:3000/wetty](http://localhost:3000/wetty). -It is recommended to drive wetty behind a reverse proxy to have HTTPS security +It is recommended to drive WeTTY behind a reverse proxy to have HTTPS security and possibly Let’s Encrypt support. Popular containers to achieve this are [nginx-proxy](https://github.com/nginx-proxy/nginx-proxy) and [traefik](https://traefik.io/traefik/). For traefik there is an example @@ -111,7 +111,7 @@ Check out the [docs](https://github.com/butlerx/wetty/tree/main/docs) ### What browsers are supported? -WeTTy supports all browsers that +WeTTY supports all browsers that [xterm.js supports](https://github.com/xtermjs/xterm.js#browser-support). ## Author @@ -137,56 +137,56 @@ Thanks goes to these wonderful people - - - - - - - + + + + + + + - - - - - - - + + + + + + + - - - - - - - + + + + + + + - - - - - - - + + + + + + + - - - - - - - + + + + + + + - - - - - + + + + +

Cian Butler
πŸ’» πŸ“–
Krishna Srinivas
πŸ’»
acalatrava
πŸ’»
Strubbl
πŸ’»
Oleg Kurapov
πŸ’»
Boyan Rabchev
πŸ’»
Jimmy
πŸ’»
Cian Butler
πŸ’» πŸ“–
Krishna Srinivas
πŸ’»
acalatrava
πŸ’»
Strubbl
πŸ’»
Oleg Kurapov
πŸ’»
Boyan Rabchev
πŸ’»
Jimmy
πŸ’»

Luca Milanesio
πŸ’»
Anthony Jund
πŸ’»
mirtouf
πŸ’»
Bertrand Roussel
πŸ’»
Ben Letchford
πŸ’»
SouraDutta
πŸ’»
Koushik M.L.N
πŸ’»
Luca Milanesio
πŸ’»
Anthony Jund
πŸ’»
mirtouf
πŸ’»
Bertrand Roussel
πŸ’»
Ben Letchford
πŸ’»
SouraDutta
πŸ’»
Koushik M.L.N
πŸ’»

Imuli
πŸ’»
perpen
πŸ’»
Nathan LeClaire
πŸ’»
Mihir Kumar
πŸ’»
Chris Suszynski
πŸ’»
Felix Bartels
πŸ’»
Jarrett Gilliam
πŸ’»
Imuli
πŸ’»
perpen
πŸ’»
Nathan LeClaire
πŸ’»
Mihir Kumar
πŸ’»
Chris Suszynski
πŸ’»
Felix Bartels
πŸ’»
Jarrett Gilliam
πŸ’»

Harry Lee
πŸ’»
Andreas KlΓΆckner
πŸ’»
DenisKramer
πŸ’»
Vamshi K Ponnapalli
πŸ’»
Tri Nguyen
πŸ“–
Felix Pojtinger
πŸ“–
Neale Pickett
πŸ’»
Harry Lee
πŸ’»
Andreas KlΓΆckner
πŸ’»
DenisKramer
πŸ’»
Vamshi K Ponnapalli
πŸ’»
Tri Nguyen
πŸ“–
Felix Pojtinger
πŸ“–
Neale Pickett
πŸ’»

Matthew Piercey
πŸ“–
Kasper Holbek Jensen
πŸ“–
Farhan Khan
πŸ’»
Jurre Vriesen
πŸ’»
James Turnbull
πŸ’»
Dean Shub
πŸ’»
lozbrown
πŸ’» πŸ’‘
Matthew Piercey
πŸ“–
Kasper Holbek Jensen
πŸ“–
Farhan Khan
πŸ’»
Jurre Vriesen
πŸ’»
James Turnbull
πŸ’»
Dean Shub
πŸ’»
lozbrown
πŸ’» πŸ’‘

sergeir82
πŸ’»
Kyle Lucy
πŸ’»
userdocs
πŸ“–
Janos Kasza
πŸ’»
Grant Handy
πŸ“–
sergeir82
πŸ’»
Kyle Lucy
πŸ’»
userdocs
πŸ“–
Janos Kasza
πŸ’»
Grant Handy
πŸ“–
diff --git a/conf/config.json5 b/conf/config.json5 index b955580..92f4d6e 100644 --- a/conf/config.json5 +++ b/conf/config.json5 @@ -13,7 +13,7 @@ base: '/wetty/', // URL base to serve resources from port: 3000, // Port to listen on host: '0.0.0.0', // address to listen on - title: 'WeTTy - The Web Terminal Emulator', // Page title + title: 'WeTTY - The Web Terminal Emulator', // Page title bypassHelmet: false, // Disable Helmet security checks }, diff --git a/docs/API.md b/docs/API.md index f305464..c40ff30 100644 --- a/docs/API.md +++ b/docs/API.md @@ -1,4 +1,4 @@ -## WeTTy +## WeTTY Create WeTTY server @@ -12,7 +12,7 @@ Create WeTTY server ### WeTTy.start β‡’ `Promise` -Starts WeTTy Server +Starts WeTTY Server **Kind**: inner property of [`WeTTy`](#module_WeTTy) **Returns**: `Promise` - Promise resolves once server is running @@ -31,7 +31,7 @@ Starts WeTTy Server | [serverConf.base] | `Object` | `'/wetty/'` | Server settings | | [serverConf.port] | `number` | `3000` | Port to run server on | | [serverConf.host] | `string` | `'0.0.0.0'` | Host address for server | -| [serverConf.title] | `string` | `'WeTTy'` | Title of the server | +| [serverConf.title] | `string` | `'WeTTY'` | Title of the server | | [serverConf.bypasshelmet] | `boolean` | `false` | if helmet should be disabled on the sever | | [command] | `string` | `"''"` | The command to execute. If running as root and no host specified this will be login if a host is specified will be ssh | | [forcessh] | `boolean` | `false` | Connecting through ssh even if running as root | diff --git a/docs/README.md b/docs/README.md index 938ddb8..f59996c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,6 +1,6 @@ # Docs -![WeTTy](./terminal.png?raw=true) +![WeTTY](./terminal.png?raw=true) - [AtoZ](./atoz.md) - [Running as daemon](./service.md) @@ -13,11 +13,11 @@ ## API -For WeTTy options and event details please refer to the [api docs](./API.md) +For WeTTY options and event details please refer to the [api docs](./API.md) ### Getting started -WeTTy is event driven. To Spawn a new server call `wetty.start()` with no +WeTTY is event driven. To Spawn a new server call `wetty.start()` with no arguments. ```javascript diff --git a/docs/apache.md b/docs/apache.md index 72a7290..e3ab7aa 100644 --- a/docs/apache.md +++ b/docs/apache.md @@ -1,15 +1,15 @@ -## Run wetty behind nginx or apache +## Run WeTTY behind nginx or apache -As said earlier you can use a proxy to add https to WeTTy. +As said earlier you can use a proxy to add https to WeTTY. -**Note** that if your proxy is configured for https you should run WeTTy without +**Note** that if your proxy is configured for https you should run WeTTY without SSL If your proxy uses a base path other than `/wetty`, specify the path with the `--base` flag, or the `BASE` environment variable. -The following confs assume you want to serve wetty on the url -`example.com/wetty` and are running wetty with the default base and serving it +The following confs assume you want to serve WeTTY on the url +`example.com/wetty` and are running WeTTY with the default base and serving it on the same server Put the following configuration in apache's conf: @@ -34,10 +34,10 @@ the community version, only pro). Main idea is to propagate the SAML2 validated user identity into the `remote-user` HTTP header. You need to have the user id returned within the -SAML2 NameID matching the username defined on the platform wetty is running. +SAML2 NameID matching the username defined on the platform WeTTY is running. E.g: You can ask the Idp to return a sAMAccountName within the SAML2Response -NameID, and provision beforehand those allowed users on the OS wetty is running +NameID, and provision beforehand those allowed users on the OS WeTTY is running on. ### SAML2 Metadata generation @@ -84,7 +84,7 @@ here `idp.xml` and exchange you foo.xml with it. MellonSPCertFile /etc/apache2/saml2/foo.cert MellonIdPMetadataFile /etc/apache2/saml2/idp.xml - # the identity propagated to wetty (as HTTP header 'remote-user: xxxxx') + # the identity propagated to WeTTY (as HTTP header 'remote-user: xxxxx') # is retrieved from SAMLResponse NameID attribute RequestHeader set remote-user %{MELLON_NAMEID}e @@ -106,15 +106,15 @@ here `idp.xml` and exchange you foo.xml with it. ### Auto login If you want to have a seamless login by trusting your IdP for authentication, -you can create password-less users on the wetty platform and have them trust an -SSH key used by the NodeJS, owned by the dedicated wetty OS user. +you can create password-less users on the WeTTY platform and have them trust an +SSH key used by the NodeJS, owned by the dedicated WeTTY OS user. -Wetty instanciation with proper parameters, especially the SSH private key is +WeTTY instanciation with proper parameters, especially the SSH private key is done via the following systemd service `/etc/systemd/system/wetty.service`: ``` [Unit] -Description=Wetty Web Terminal +Description=WeTTY Web Terminal After=network.target [Service] @@ -140,12 +140,12 @@ You probably don't want local users to impersonate each other, for that you need to make sure that: 1. NodeJS is listenning only to localhost: provided by `wetty.service` -2. **Only** the apache2 process can join the wetty port. Else local users will +2. **Only** the apache2 process can join the WeTTY port. Else local users will be able to connect and forge a `remote-user` header: provided by `iptables -A OUTPUT -o lo -p tcp --dport 3000 -m owner \! --uid-owner www-data -j DROP` -3. Validate your wetty version does not allow access to `/wetty/ssh/` else again +3. Validate your WeTTY version does not allow access to `/wetty/ssh/` else again you will be able to impersonnate anyone: provided by either: - 1. wetty version 2.0.3 and beyond implements this by disabling this feature + 1. WeTTY version 2.0.3 and beyond implements this by disabling this feature in case of `remote-user` presence 2. apache2 conf as provided in previous section (containing the ``) diff --git a/docs/atoz.md b/docs/atoz.md index c0ab391..f7348a1 100644 --- a/docs/atoz.md +++ b/docs/atoz.md @@ -353,7 +353,7 @@ Here is the template `config.json` you need to use. **Note:** To be [validated json](https://codebeautify.org/jsonvalidator) the below json example should have the `// ...` comments removed. With all comments removed the example is valid json. They are in the example to help explain the -options and won't stop wetty from loading if you leave them in place. Lines you +options and won't stop WeTTY from loading if you leave them in place. Lines you do not need can be commented out but should be removed if you want the json to pass validation. @@ -371,7 +371,7 @@ pass validation. "base": "/wetty/", // URL base to serve resources from "port": 3000, // Port to listen on "host": "0.0.0.0", // listen on all interfaces or can be 127.0.0.1 with nginx - "title": "WeTTy - The Web Terminal Emulator", // Page title + "title": "WeTTY - The Web Terminal Emulator", // Page title "bypassHelmet": false // Disable Helmet security checks }, "forceSSH": false, // Force sshing to local machine over login if running as root @@ -446,7 +446,7 @@ remove or modify the `ExecStart` command based on your needs. ```bash [Unit] -Description=wetty +Description=WeTTY After=network-online.target [Service] @@ -484,7 +484,7 @@ this file. ```bash [Unit] -Description=wetty +Description=WeTTY After=network-online.target [Service] @@ -628,7 +628,7 @@ behind either: --ssh-host ssh server host [string] [default: "localhost"] --ssh-port ssh server port [number] [default: 22] --ssh-user ssh user [string] [default: ""] - --title window title [string] [default: "WeTTy - The Web Terminal Emulator"] + --title window title [string] [default: "WeTTY - The Web Terminal Emulator"] --ssh-auth defaults to "password", you can use "publickey,password" instead [string] [default: "password"] --ssh-pass ssh password [string] @@ -646,7 +646,7 @@ behind either: same origin [boolean] [default: false] ``` -## Updating Wetty +## Updating WeTTY With `yarn`: diff --git a/docs/auto-login.md b/docs/auto-login.md index 54aae24..977b68e 100644 --- a/docs/auto-login.md +++ b/docs/auto-login.md @@ -16,7 +16,7 @@ For auto-login feature you'll need sshpass installed ## Usage You can also pass the ssh password as an optional query parameter to auto-login -the user like this (Only while running WeTTy as a non root account or when +the user like this (Only while running WeTTY as a non root account or when specifying the ssh host): `http://yourserver:3000/wetty/ssh/?pass=` diff --git a/docs/development.md b/docs/development.md index 7df2d07..d126ea8 100644 --- a/docs/development.md +++ b/docs/development.md @@ -1,6 +1,6 @@ # Installation from Source -WeTTy can be installed from source or from npm. +WeTTY can be installed from source or from npm. To install from source run: @@ -13,8 +13,8 @@ $ yarn build ## Development Env -To run WeTTy in dev mode you can run `yarn dev` this will build latest version -of WeTTy and start the server pointing at `localhost` on port `22`. The Dev -server will rebuild WeTTy when ever a file is edited and restart the server with -the new build. Any current ssh session in WeTTy will be killed and the user +To run WeTTY in dev mode you can run `yarn dev` this will build latest version +of WeTTY and start the server pointing at `localhost` on port `22`. The Dev +server will rebuild WeTTY when ever a file is edited and restart the server with +the new build. Any current ssh session in WeTTY will be killed and the user logged out. diff --git a/docs/docker.md b/docs/docker.md index 50c7871..a46143d 100644 --- a/docs/docker.md +++ b/docs/docker.md @@ -1,6 +1,6 @@ # Dockerized Version -WeTTy can be run from a container to ssh to a remote host or the host system. +WeTTY can be run from a container to ssh to a remote host or the host system. This is handy for quick deployments. Just modify `docker-compose.yml` for your host and run: @@ -8,7 +8,7 @@ host and run: $ docker-compose up -d ``` -This will start 2 containers, one will be WeTTy container running ssh client the +This will start 2 containers, one will be WeTTY container running ssh client the other will be a container running ssh server. Visit the appropriate URL in your browser @@ -22,6 +22,6 @@ In the docker version all flags can be accessed as environment variables such as If you dont want to build the image yourself just remove the line `build; .` -If you wish to use the WeTTy container in prod just modify the WeTTy container +If you wish to use the WeTTY container in prod just modify the WeTTY container to have `SSHHOST` point to the server you want to ssh to and remove the ssh server container. diff --git a/docs/downloading-files.md b/docs/downloading-files.md index 6261984..1fc0a5e 100644 --- a/docs/downloading-files.md +++ b/docs/downloading-files.md @@ -1,6 +1,6 @@ # File Downloading -WeTTy supports file downloads by printing terminal escape sequences between a +WeTTY supports file downloads by printing terminal escape sequences between a base64 encoded file. The terminal escape sequences used are `^[[5i` and `^[[4i` (VT100 for "enter @@ -15,11 +15,11 @@ function wetty-download() { } ``` -You are then able to download files via WeTTy! +You are then able to download files via WeTTY! ```bash $ cat my-pdf-file.pdf | ./wetty-download.sh ``` -WeTTy will then issue a popup like the following that links to a local file +WeTTY will then issue a popup like the following that links to a local file blob: `Download ready: file-20191015233654.pdf` diff --git a/docs/flags.md b/docs/flags.md index b867f49..6aad58d 100644 --- a/docs/flags.md +++ b/docs/flags.md @@ -1,15 +1,15 @@ # Flags -WeTTy can be run with the `--help` flag to get a full list of flags. +WeTTY can be run with the `--help` flag to get a full list of flags. ## Server Port -WeTTy runs on port `3000` by default. You can change the default port by +WeTTY runs on port `3000` by default. You can change the default port by starting with the `--port` or `-p` flag. ## SSH Host -If WeTTy is run as root while the host is set as the local machine it will use +If WeTTY is run as root while the host is set as the local machine it will use the `login` binary rather than ssh. If no host is specified it will use `localhost` as the ssh host. @@ -26,10 +26,10 @@ be prompted to enter their username when they connect. ## SSH Port -By default WeTTy will try to ssh to port `22`, if your host uses an alternative +By default WeTTY will try to ssh to port `22`, if your host uses an alternative ssh port this can be specified with the flag `--ssh-port`. -## WeTTy URL +## WeTTY URL If you'd prefer an HTTP base prefix other than `/wetty`, you can specify that with `--base`. diff --git a/docs/https.md b/docs/https.md index 8632e3e..45b5f39 100644 --- a/docs/https.md +++ b/docs/https.md @@ -1,12 +1,12 @@ # HTTPS Always use HTTPS especially with a terminal to your server. You can add HTTPS by -either using WeTTy behind a proxy or directly. +either using WeTTY behind a proxy or directly. See docs for [NGinX](./nginx.md) and [Apache](./apache.md) for running behind a proxy. -To run WeTTy directly with SSL use both the `--ssl-key` and `--ssl-cert` flags +To run WeTTY directly with SSL use both the `--ssl-key` and `--ssl-cert` flags and pass them the path too your cert and key as follows: ```bash diff --git a/docs/nginx.md b/docs/nginx.md index d08dc37..c8c6ab9 100644 --- a/docs/nginx.md +++ b/docs/nginx.md @@ -1,15 +1,15 @@ -## Run WeTTy behind nginx +## Run WeTTY behind nginx -As said earlier you can use Nginx to add https to WeTTy. +As said earlier you can use Nginx to add https to WeTTY. -**Note** that if your proxy is configured for https you should run WeTTy without +**Note** that if your proxy is configured for https you should run WeTTY without SSL -If you configure nginx to use a base path other than `/WeTTy`, then specify that +If you configure nginx to use a base path other than `/wetty`, then specify that path with the `--base` flag, or the `BASE` environment variable. -The following confs assume you want to serve WeTTy on the url -`example.com/wetty` and are running WeTTy with the default base and serving it +The following confs assume you want to serve WeTTY on the url +`example.com/wetty` and are running WeTTY with the default base and serving it on the same server For a more detailed look see the diff --git a/docs/service.md b/docs/service.md index 2ad7aed..d5bb094 100644 --- a/docs/service.md +++ b/docs/service.md @@ -1,6 +1,6 @@ -## Run WeTTy as a service daemon +## Run WeTTY as a service daemon -WeTTy can be run as a daemon on your service init confs and systemd services are +WeTTY can be run as a daemon on your service init confs and systemd services are bundled with the npm package to make this easier. ### init.d @@ -20,7 +20,7 @@ $ systemctl --user enable wetty $ systemctl --user start wetty ``` -This will start WeTTy on port 3000. If you want to change the port or redirect +This will start WeTTY on port 3000. If you want to change the port or redirect stdout/stderr you should change the last line in `wetty.conf` file, something like this: diff --git a/src/main.ts b/src/main.ts index 5b01331..0e23aaf 100644 --- a/src/main.ts +++ b/src/main.ts @@ -89,7 +89,7 @@ const opts = yargs }) .option('allow-iframe', { description: - 'Allow wetty to be embedded in an iframe, defaults to allowing same origin', + 'Allow WeTTY to be embedded in an iframe, defaults to allowing same origin', type: 'boolean', }) .option('help', { diff --git a/src/shared/defaults.ts b/src/shared/defaults.ts index 46aca04..e72a300 100644 --- a/src/shared/defaults.ts +++ b/src/shared/defaults.ts @@ -15,7 +15,7 @@ export const serverDefault: Server = { base: process.env.BASE || '/wetty/', port: parseInt(process.env.PORT || '3000', 10), host: '0.0.0.0', - title: process.env.TITLE || 'WeTTy - The Web Terminal Emulator', + title: process.env.TITLE || 'WeTTY - The Web Terminal Emulator', allowIframe: false, };