diff --git a/README.md b/README.md index 847002e..3ea9569 100644 --- a/README.md +++ b/README.md @@ -60,7 +60,6 @@ Options: --host wetty listen host [string] --command, -c command to run in shell [string] --bypass-helmet disable helmet from placing security restrictions [boolean] - ``` Open your browser on `http://yourserver:3000/wetty` and you will prompted to diff --git a/conf/wetty.service b/conf/wetty.service index af4a7d4..c503121 100644 --- a/conf/wetty.service +++ b/conf/wetty.service @@ -9,9 +9,13 @@ Description=Wetty Web Terminal After=network.target [Service] - +Type=simple WorkingDirectory=$HOME/.config/yarn/global/node_modules/wetty/ ExecStart=/usr/bin/node . -p 3000 --host 127.0.0.1 +TimeoutStopSec=20 +KillMode=mixed +Restart=always +RestartSec=2 [Install] WantedBy=multi-user.target diff --git a/docs/README.md b/docs/README.md index c2b785f..938ddb8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,6 +2,7 @@ ![WeTTy](./terminal.png?raw=true) +- [AtoZ](./atoz.md) - [Running as daemon](./service.md) - [HTTPS Support](./https.md) - [Using NGINX](./nginx.md) diff --git a/docs/atoz.md b/docs/atoz.md index 8d03cec..ffe5306 100644 --- a/docs/atoz.md +++ b/docs/atoz.md @@ -1,10 +1,16 @@ ### Introduction -This is an A to Z guide that will help you get `wetty` up and running on Debian Stable. It covers the key configuration areas by using copy and paste commands to help you install this application and get it securely up and running. It should also provide enough information to allow you to understand and extend that configuration for your personal requirements. +This is an A to Z guide that will help you get `wetty` up and running on Debian +Stable. It covers the key configuration areas by using copy and paste commands +to help you install this application and get it securely up and running. It +should also provide enough information to allow you to understand and extend +that configuration for your personal requirements. ### Required dependencies -You will need the package `build-essential` to be installed. We need this specifically for `node-gyp` to build packages when using `npm` or `yarn` to install packages. +You will need the package `build-essential` to be installed. We need this +specifically for `node-gyp` to build packages when using `npm` or `yarn` to +install packages. As the `root` user run these commands: @@ -13,7 +19,8 @@ apt update apt install -y build-essential ``` -If you do not have root access and just want to check the dependency is installed you can use this command: +If you do not have root access and just want to check the dependency is +installed you can use this command: ```bash dpkg -s build-essential | grep Status: @@ -27,30 +34,39 @@ Status: install ok installed ### Create a local user account -For this guide, unless specifically stated, you should not use a `root` account to install and run `wetty`. Please use an existing local account or create one now. +For this guide, unless specifically stated, you should not use a `root` account +to install and run `wetty`. Please use an existing local account or create one +now. -**Note:** Whichever user runs `wetty` should be the same user you wish to authenticate with via `ssh` to keep this simple. +**Note:** Whichever user runs `wetty` should be the same user you wish to +authenticate with via `ssh` to keep this simple. -If you need to create a local user account you can run this command: +If you need to create a local user account you can run this command: -**Important note:** replace `username` with a user name of your choosing and create a password when prompted +**Important note:** replace `username` with a user name of your choosing and +create a password when prompted ```bash adduser --gecos "" username ``` -Switch to your local user now and open an `ssh` session to continue with this guide. +Switch to your local user now and open an `ssh` session to continue with this +guide. ### Install node locally -To install and manage `node` as a local user we are going to use [Node Version Manager](https://github.com/nvm-sh/nvm) as an established solution to installing and managing multiple versions of node without needing `root` access. We are going to install the `lts` or long term support release of `node` to use with this application. +To install and manage `node` as a local user we are going to use +[Node Version Manager](https://github.com/nvm-sh/nvm) as an established solution +to installing and managing multiple versions of node without needing `root` +access. We are going to install the `lts` or long term support release of `node` +to use with this application. ```bash bash <(curl -s https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh) && source ~/.profile nvm install --lts ``` -You can now call `node` to check it works using this command. +You can now call `node` to check it works using this command. ```bash node -v @@ -62,19 +78,26 @@ Your result should look something like this. v12.16.2 ``` -**Note:** There is consideration with this method. `node` is only in the local user's path through sourcing of the `~/.nvm/nvm.sh` via the users `.bashrc` file. Unless this is done `node` will not be usable unless directly linked to and `nvm` commands will be unavailable. +**Note:** There is consideration with this method. `node` is only in the local +user's path through sourcing of the `~/.nvm/nvm.sh` via the users `.bashrc` +file. Unless this is done `node` will not be usable unless directly linked to +and `nvm` commands will be unavailable. -The way we over come this issue for the needs of this guide is by using this command where applicable: +The way we over come this issue for the needs of this guide is by using this +command where applicable: ```bash -source ~/.nvm/nvm.sh && nvm which 12 +source ~/.nvm/nvm.sh && nvm which 14 ``` -**Why?** This command will always provide us with the path to the most current version of `node 12` installed via `nvm` regardless of other versions of `node` installed. +**Why?** This command will always provide us with the path to the most current +version of `node 12` installed via `nvm` regardless of other versions of `node` +installed. ### Generate openssl certificates. -**Why?** So that later we can configure `wetty` to work with `https` and make sure we interact with `wetty` over a secure connection at all times. +**Why?** So that later we can configure `wetty` to work with `https` and make +sure we interact with `wetty` over a secure connection at all times. Make the required directory using this command: @@ -82,7 +105,8 @@ Make the required directory using this command: mkdir -p ~/.ssl ``` -Generate the self signed `openssl` certificates we will use to encrypt our web traffic when using `wetty` using this command: +Generate the self signed `openssl` certificates we will use to encrypt our web +traffic when using `wetty` using this command: **Note:** we are using`ecdsa` using the `secp521r1` curve. @@ -94,7 +118,7 @@ Now give these file and folders the correct permissions using these commands: ```bash chmod 700 ~/.ssl -chmod 644 ~/.ssl/wetty.crt +chmod 644 ~/.ssl/wetty.crt chmod 600 ~/.ssl/wetty.key ``` @@ -102,7 +126,8 @@ This is all we need to do for now in regards to https. ### Generate the ssh key file -**Why?** So that later we can set up automatic login via `ssh`. Our instance will authorise using this key file stored locally. +**Why?** So that later we can set up automatic login via `ssh`. Our instance +will authorise using this key file stored locally. Make the required directory, if it does not exist, using this command: @@ -110,13 +135,16 @@ Make the required directory, if it does not exist, using this command: mkdir -p ~/.ssh ``` -Create the `ssh` private key using `ed25519` that we need to authorise our local connection, using this command: +Create the `ssh` private key using `ed25519` that we need to authorise our local +connection, using this command: ```bash ssh-keygen -q -C "wetty-keyfile" -t ed25519 -N '' -f ~/.ssh/wetty 2>/dev/null <<< y >/dev/null ``` -**Important Note:** You must add the public key to your `authorized_keys` file in order to be able to log in using your `ssh` key file when accessing `wetty` via a web browser. +**Important Note:** You must add the public key to your `authorized_keys` file +in order to be able to log in using your `ssh` key file when accessing `wetty` +via a web browser. Copy the key to our `~/.ssh/authorized_keys` file, using this command: @@ -132,7 +160,9 @@ chmod 644 ~/.ssh/authorized_keys chmod 600 ~/.ssh/wetty ``` -**Optional:** A housekeeping command. If you need to remove all entries of the `wetty` public key with the comment `wetty-keyfile` from the `~/.ssh/authorized_keys` file use this command. Otherwise ignore this. +**Optional:** A housekeeping command. If you need to remove all entries of the +`wetty` public key with the comment `wetty-keyfile` from the +`~/.ssh/authorized_keys` file use this command. Otherwise ignore this. ```bash sed -r '/^ssh-ed25519(.*)wetty-keyfile$/d' -i ~/.ssh/authorized_keys @@ -140,17 +170,23 @@ sed -r '/^ssh-ed25519(.*)wetty-keyfile$/d' -i ~/.ssh/authorized_keys ### Install wetty -**Note:** we are using `-g` for `npm` or `global` for `yarn` along with `--prefix ~/` so that the application symbolic link is installed to our `~/bin` directory and available in our local user's `PATH`. +**Note:** we are using `-g` for `npm` or `global` for `yarn` along with +`--prefix ~/` so that the application symbolic link is installed to our `~/bin` +directory and available in our local user's `PATH`. -As your local user run these commands to install `wetty` and `forever`. We will need `forever` later to run wetty in the background. +As your local user run these commands to install `wetty` and `forever`. We will +need `forever` later to run wetty in the background. -First, we need to make sure the local user's `~/bin` folder exists and is in the `PATH` for the following commands to work. +First, we need to make sure the local user's `~/bin` folder exists and is in the +`PATH` for the following commands to work. ```bash mkdir -p ~/bin && source ~/.profile ``` -Please use either the `npm` or `yarn` method and not both. The `yarn` method is recommended but I provide both as you may have a personal preference. The outcome is effectively the same. +Please use either the `npm` or `yarn` method and not both. The `yarn` method is +recommended but I provide both as you may have a personal preference. The +outcome is effectively the same. `npm ` - optional - use `npm` to install wetty @@ -158,14 +194,15 @@ Please use either the `npm` or `yarn` method and not both. The `yarn` method is npm install -g wetty forever --prefix ~/ ``` -`yarn` - recommended - use `yarn` to install wetty +`yarn` - recommended - use `yarn` to install wetty ```bash npm install -g yarn --prefix ~/ yarn global add wetty forever --prefix ~/ ``` -Once successfully installed the application should be available in your local user's `PATH`. To test the installation was successful please use this command: +Once successfully installed the application should be available in your local +user's `PATH`. To test the installation was successful please use this command: ```bash wetty -h @@ -173,23 +210,29 @@ wetty -h ### Accessing the web interface. -This needs to be done here because it is not easy to do in the next steps if `wetty` is running in the terminal. +This needs to be done here because it is not easy to do in the next steps if +`wetty` is running in the terminal. -This command will generate the correct URL you need to visit after using the start up commands in the following section. +This command will generate the correct URL you need to visit after using the +start up commands in the following section. ```bash echo https://$(curl -s4 icanhazip.com):3000 ``` -*Please make make a note of this URL now.* +_Please make make a note of this URL now._ ### Running wetty -Now we have all the ground work done we can focus on our `wetty` server configuration settings. +Now we have all the ground work done we can focus on our `wetty` server +configuration settings. -For example, the below command would provide a `https` instance with automatic `ssh` authorisation using our `wetty` private key on port `3000` accessible at `https://IP:3000` . Refer to the previous URL generation command. +For example, the below command would provide a `https` instance with automatic +`ssh` authorisation using our `wetty` private key on port `3000` accessible at +`https://IP:3000` . Refer to the previous URL generation command. -**Important note:** This command will run in your current terminal session and not in the background. +**Important note:** This command will run in your current terminal session and +not in the background. ```bash wetty --host 0.0.0.0 -p 3000 --title wetty --base / --sshkey ~/.ssh/wetty --sshhost localhost --sshuser $(whoami) --sshport 22 --sshauth publickey --sslkey ~/.ssl/wetty.key --sslcert ~/.ssl/wetty.crt @@ -197,7 +240,8 @@ wetty --host 0.0.0.0 -p 3000 --title wetty --base / --sshkey ~/.ssh/wetty --sshh #### forever to manage wetty -Now you can use `forever` we installed to run `wetty` in the background instead of directly in your terminal +Now you can use `forever` we installed to run `wetty` in the background instead +of directly in your terminal ```bash forever start ~/bin/wetty --host 0.0.0.0 -p 3000 --title wetty --base / --sshkey ~/.ssh/wetty --sshhost localhost --sshuser $(whoami) --sshport 22 --sshauth publickey --sslkey ~/.ssl/wetty.key --sslcert ~/.ssl/wetty.crt @@ -211,40 +255,39 @@ forever stop ~/bin/wetty #### Optional - config file. -**Important Note:** This is an optional and unsupported method to load settings from a physical configuration file. It's a hack and you need to accept it has some limitations but I've made it as easy as I can to use. - -Since `wetty` does not have configurations files and all commands are passed as command line arguments we can fake this behaviour by using a method to read from a text file and expand variables then pass this to `wetty`. All arguments must be on a single line - Create a directory to store our configuration data using this command: ```bash mkdir -p ~/.config/wetty ``` -Now populate our `config` file with some settings. This examples is the same command as above. +Now populate our `config` file with some settings. This examples is the same +command as above. ```bash -echo -n '--host 0.0.0.0 -p 3000 --title wetty --base / --sshkey ~/.ssh/wetty --sshhost localhost --sshuser $(whoami) --sshport 22 --sshauth publickey --sslkey ~/.ssl/wetty.key --sslcert ~/.ssl/wetty.crt' > ~/.config/wetty/config +echo -n '{ "server": { "host": "0.0.0.0", "port": 3000, "title": "WeTTy", "base": "/" }, "ssh": {"key": "~/.ssh/wetty", "host": "localhost", "user": "$(whoami)", "port": 22, "auth": "publickey"}, "ssl": { "key": "~/.ssl/wetty.key", "cert": "~/.ssl/wetty.crt"}}' > ~/.config/wetty/config.json ``` This configuration file is now available here for you to manage your settings. ```bash -~/.config/wetty/config +~/.config/wetty/config.json ``` -Now we can load this file as part of the command we pass to `wetty` with shell expansion and command substitution. +Now we can load this file as part of the command we pass to `wetty` with shell +expansion and command substitution. ```bash -wetty $(eval echo $(cat ~/.config/wetty/config)) +wetty --conf ~/.config/wetty/config.json ``` #### forever using a config file -Now you can use `forever` to run it in the background instead of directly in your terminal +Now you can use `forever` to run it in the background instead of directly in +your terminal ```bash -forever start ~/bin/wetty $(eval echo $(cat ~/.config/wetty/config)) +forever start ~/bin/wetty --conf ~/.config/wetty/config.json ``` To stop `wetty` from running you can use this command: @@ -261,43 +304,63 @@ Let's break it down so that we can understand what's being done and why. --host 0.0.0.0 -p 3000 --title wetty --base / ``` -`--host 0.0.0.0` - defines the interface we want to bind to. Using `0.0.0.0` means that we bind to all available interfaces so using this setting just works. When we use nginx we can change this to `--host 127.0.0.1` in order to prevent generic port access to the application and force traffic through our nginx reverse proxy URL. +`--host 0.0.0.0` - defines the interface we want to bind to. Using `0.0.0.0` +means that we bind to all available interfaces so using this setting just works. +When we use nginx we can change this to `--host 127.0.0.1` in order to prevent +generic port access to the application and force traffic through our nginx +reverse proxy URL. -`-p 3000` - defines the local listening port. You will use this port to connect via the remotely accessible web server or when configuring a reverse proxy through nginx. +`-p 3000` - defines the local listening port. You will use this port to connect +via the remotely accessible web server or when configuring a reverse proxy +through nginx. -`--title wetty` - an optional setting to set the window title for this `wetty` session. +`--title wetty` - an optional setting to set the window title for this `wetty` +session. -`--base /` - changes the default base URL setting from `/wetty/` to define the remote URL. We use `--base /` to make `wetty` accessible on the URL format `https://IP:3000` instead of `https://IP:3000/wetty` but we would change this back if we use nginx to reverse proxy the application. +`--base /` - changes the default base URL setting from `/wetty/` to define the +remote URL. We use `--base /` to make `wetty` accessible on the URL format +`https://IP:3000` instead of `https://IP:3000/wetty` but we would change this +back if we use nginx to reverse proxy the application. #### SSH settings explained -These settings are all specific to `ssh` and will enable you to automatically log into you ssh session for the selected user. +These settings are all specific to `ssh` and will enable you to automatically +log into you ssh session for the selected user. ```bash --sshkey ~/.ssh/wetty --sshhost localhost --sshuser $(whoami) --sshport 22 --sshauth publickey ``` -`--sshkey ~/.ssh/wetty` - we are telling `wetty` to load our `ssh` key file that we generated earlier. +`--ssh-key ~/.ssh/wetty` - we are telling `wetty` to load our `ssh` key file +that we generated earlier. -`--sshhost localhost` - optional setting telling `wetty` to connect the host `localhost` +`--ssh-host localhost` - optional setting telling `wetty` to connect the host +`localhost` -`--sshuser $(whomai)` - defines our `ssh` username. In this case via the command substitution of `whoami` which will not require your input of a username. +`--ssh-user $(whomai)` - defines our `ssh` username. In this case via the +command substitution of `whoami` which will not require your input of a +username. -`--sshport 22` - optional setting to set the `ssh` port we need to connect to. +`--ssh-port 22` - optional setting to set the `ssh` port we need to connect to. -`--sshauth publickey` defines the accepted authentication types. You do not have to use the key file and you can instead require a password but setting this to `--sshauth password`. You can specify both `--sshauth publickey,password` +`--ssh-auth publickey` defines the accepted authentication types. You do not +have to use the key file and you can instead require a password but setting this +to `--ssh-auth password`. You can specify both `--ssh-auth publickey,password` #### SSL settings explained -These settings are specific to `openssl` to make `wetty` load https webserver so that all data is transmitted over a secure connection. +These settings are specific to `openssl` to make `wetty` load https webserver so +that all data is transmitted over a secure connection. ```bash ---sslkey ~/.ssl/wetty.key --sslcert ~/.ssl/wetty.crt +--ssl-key ~/.ssl/wetty.key --ssl-cert ~/.ssl/wetty.crt ``` -`--sslkey ~/.ssl/wetty.key` - tells `wetty` to load our `openssl` generated key file. +`--ssl-key ~/.ssl/wetty.key` - tells `wetty` to load our `openssl` generated key +file. -`--sslcert ~/.ssl/wetty.crt` - tells `wetty` to load our `openssl` generates certificate file. +`--ssl-cert ~/.ssl/wetty.crt` - tells `wetty` to load our `openssl` generates +certificate file. ### Systemd service settings @@ -311,7 +374,9 @@ mkdir -p ~/.config/systemd/user #### Systemd service. -Here is a normal service file template with hardcoded values you can insert into the `wetty.service` file. +Here is the example using our pseudo configuration file. All modifications to +the start up of `wetty` will be done by editing the `~/.config/Wetty/config` +file and then reloading the ` wetty.service`. Use `nano` to open the file for editing. @@ -329,7 +394,7 @@ After=network.target [Service] Type=simple WorkingDirectory=%h -ExecStart=/bin/bash -c "$$(source /home/$$(whoami)/.nvm/nvm.sh && nvm which 12) /home/$$(whoami)/bin/wetty --host 0.0.0.0 -p 3000 --title wetty --base / --sshkey /home/$$(whoami)/.ssh/wetty --sshhost localhost --sshuser $$(whoami) --sshport 22 --sshauth publickey --sslkey /home/$$(whoami)/.ssl/wetty.key --sslcert /home/$$(whoami)/.ssl/wetty.crt" +ExecStart=/bin/bash -c "$$(source /home/$$(whoami)/.nvm/nvm.sh && nvm which 12) /home/$$(whoami)/bin/wetty --conf /home/$$(whoami)/.config/wetty/config.json" TimeoutStopSec=20 KillMode=mixed Restart=always @@ -339,39 +404,8 @@ RestartSec=2 WantedBy=multi-user.target ``` -Press `ctrl` + `x` and then press `y` to save then press `enter` to confirm and exit `nano`. - -#### Optional - Systemd service with config file - -Here is the example using our pseudo configuration file. All modifications to the start up of `wetty` will be done by editing the `~/.config/Wetty/config` file and then reloading the ` wetty.service`. - -Use `nano` to open the file for editing. - -```bash -nano ~/.config/systemd/user/wetty.service -``` - -The copy and paste this code. - -```bash -[Unit] -Description=wetty -After=network.target - -[Service] -Type=simple -WorkingDirectory=%h -ExecStart=/bin/bash -c "$$(source /home/$$(whoami)/.nvm/nvm.sh && nvm which 12) /home/$$(whoami)/bin/wetty $$(eval echo $(cat /home/$$(whoami)/.config/wetty/config))" -TimeoutStopSec=20 -KillMode=mixed -Restart=always -RestartSec=2 - -[Install] -WantedBy=multi-user.target -``` - -Press `ctrl` + `x` and then press `y` to save then press `enter` to confirm and exit `nano`. +Press `ctrl` + `x` and then press `y` to save then press `enter` to confirm and +exit `nano`. #### Activating your service @@ -397,17 +431,20 @@ systemctl --user enable --now wetty ### Nginx reverse proxy -If you want to use nginx as a revers proxy here is the configuration file you can use. +If you want to use nginx as a revers proxy here is the configuration file you +can use. Please modify these specific environment settings: -**Why?** This will disable generic port access to the application and force traffic via the nginx reverse proxy. +**Why?** This will disable generic port access to the application and force +traffic via the nginx reverse proxy. ```bash --host 127.0.0.1 ``` -**Why?** This change is so that our application does not attempt to load as the web root of `/` for nginx. +**Why?** This change is so that our application does not attempt to load as the +web root of `/` for nginx. ```bash --base /wetty/ @@ -415,38 +452,38 @@ Please modify these specific environment settings: Now you can use this nginx configuration file. -**Note:** we are using `https` here `https://127.0.0.1:3000/wetty;` because we configured `wetty` to run via `https` +**Note:** we are using `https` here `https://127.0.0.1:3000/wetty;` because we +configured `wetty` to run via `https` -The copy and paste this into the `https` server block of your enable server configuration file. +The copy and paste this into the `https` server block of your enable server +configuration file. ```nginx location /wetty { proxy_pass https://127.0.0.1:3000/wetty; - # proxy_pass_request_headers on; - # - proxy_set_header Host $host; - # + proxy_http_version 1.1; - # + + proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-Protocol $scheme; proxy_set_header X-Forwarded-Host $http_host; proxy_set_header X-NginX-Proxy true; - # proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $http_connection; - proxy_read_timeout 43200000; proxy_set_header X-Forwarded-Ssl on; - # + + proxy_read_timeout 43200000; proxy_redirect off; proxy_buffering off; } ``` -Press `ctrl` + `x` and then press `y` to save then press `enter` to confirm and exit `nano` +Press `ctrl` + `x` and then press `y` to save then press `enter` to confirm and +exit `nano` Now you would need to reload nginx service using this command: @@ -456,13 +493,14 @@ systemctl restart nginx #### Accessing the web interface via nginx -Visit the URL format `https://YourIP/wetty` and you can access `wetty`. This command will generate the correct URL you need to visit. +Visit the URL format `https://YourIP/wetty` and you can access `wetty`. This +command will generate the correct URL you need to visit. ```bash echo https://$(curl -s4 icanhazip.com)/wetty ``` -### Configuration reference +### Configuration reference `wetty -h` configuration options for reference.