userdocs 5 years ago
parent
commit
e5c6e2ce8a
  1. 184
      docs/atoz.md

184
docs/atoz.md

@ -8,22 +8,22 @@ You will need the package `build-essential` to be installed. We need this specif
As the `root` user run these commands: As the `root` user run these commands:
~~~bash ```bash
apt update apt update
apt install -y build-essential 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 ```bash
dpkg -s build-essential | grep Status: dpkg -s build-essential | grep Status:
~~~ ```
If the program is installed you will see this result: If the program is installed you will see this result:
~~~bash ```bash
Status: install ok installed Status: install ok installed
~~~ ```
### Create a local user account ### Create a local user account
@ -35,9 +35,9 @@ 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 ```bash
adduser --gecos "" username 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.
@ -45,30 +45,30 @@ Switch to your local user now and open an `ssh` session to continue with this gu
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
bash <(curl -s https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh) && source ~/.profile bash <(curl -s https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh) && source ~/.profile
nvm install --lts 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 ```bash
node -v node -v
~~~ ```
Your result should look something like this. Your result should look something like this.
~~~bash ```bash
v12.16.2 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 ```bash
source ~/.nvm/nvm.sh && nvm which 12 source ~/.nvm/nvm.sh && nvm which 12
~~~ ```
**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.
@ -78,25 +78,25 @@ source ~/.nvm/nvm.sh && nvm which 12
Make the required directory using this command: Make the required directory using this command:
~~~bash ```bash
mkdir -p ~/.ssl 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. **Note:** we are using`ecdsa` using the `secp521r1` curve.
~~~bash ```bash
openssl req -x509 -nodes -days 1095 -newkey ec:<(openssl ecparam -name secp521r1) -subj "/C=GB/ST=None/L=None/O=None/OU=None/CN=None" -out ~/.ssl/wetty.crt -keyout ~/.ssl/wetty.key openssl req -x509 -nodes -days 1095 -newkey ec:<(openssl ecparam -name secp521r1) -subj "/C=GB/ST=None/L=None/O=None/OU=None/CN=None" -out ~/.ssl/wetty.crt -keyout ~/.ssl/wetty.key
~~~ ```
Now give these file and folders the correct permissions using these commands: Now give these file and folders the correct permissions using these commands:
~~~bash ```bash
chmod 700 ~/.ssl chmod 700 ~/.ssl
chmod 644 ~/.ssl/wetty.crt chmod 644 ~/.ssl/wetty.crt
chmod 600 ~/.ssl/wetty.key chmod 600 ~/.ssl/wetty.key
~~~ ```
This is all we need to do for now in regards to https. This is all we need to do for now in regards to https.
@ -106,37 +106,37 @@ This is all we need to do for now in regards to https.
Make the required directory, if it does not exist, using this command: Make the required directory, if it does not exist, using this command:
~~~bash ```bash
mkdir -p ~/.ssh 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 ```bash
ssh-keygen -q -C "wetty-keyfile" -t ed25519 -N '' -f ~/.ssh/wetty 2>/dev/null <<< y >/dev/null 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: Copy the key to our `~/.ssh/authorized_keys` file, using this command:
~~~bash ```bash
cat ~/.ssh/wetty.pub >> ~/.ssh/authorized_keys cat ~/.ssh/wetty.pub >> ~/.ssh/authorized_keys
~~~ ```
Now give these file and folders the correct permissions, using these commands: Now give these file and folders the correct permissions, using these commands:
~~~bash ```bash
chmod 700 ~/.ssh chmod 700 ~/.ssh
chmod 644 ~/.ssh/authorized_keys chmod 644 ~/.ssh/authorized_keys
chmod 600 ~/.ssh/wetty 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 ```bash
sed -r '/^ssh-ed25519(.*)wetty-keyfile$/d' -i ~/.ssh/authorized_keys sed -r '/^ssh-ed25519(.*)wetty-keyfile$/d' -i ~/.ssh/authorized_keys
~~~ ```
### Install wetty ### Install wetty
@ -146,30 +146,30 @@ As your local user run these commands to install `wetty` and `forever`. We will
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 ```bash
mkdir -p ~/bin && source ~/.profile 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 `npm ` - optional - use `npm` to install wetty
~~~bash ```bash
npm install -g wetty forever --prefix ~/ npm install -g wetty forever --prefix ~/
~~~ ```
`yarn` - recommended - use `yarn` to install wetty `yarn` - recommended - use `yarn` to install wetty
~~~bash ```bash
npm install -g yarn --prefix ~/ npm install -g yarn --prefix ~/
yarn global add wetty forever --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 ```bash
wetty -h wetty -h
~~~ ```
### Accessing the web interface. ### Accessing the web interface.
@ -177,9 +177,9 @@ This needs to be done here because it is not easy to do in the next steps if `we
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 ```bash
echo https://$(curl -s4 icanhazip.com):3000 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.*
@ -191,23 +191,23 @@ For example, the below command would provide a `https` instance with automatic `
**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 ```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 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
~~~ ```
#### forever to manage wetty #### 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 ```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 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
~~~ ```
To stop `wetty` from running you can use this command To stop `wetty` from running you can use this command
~~~bash ```bash
forever stop ~/bin/wetty forever stop ~/bin/wetty
~~~ ```
#### Optional - config file. #### Optional - config file.
@ -217,49 +217,49 @@ Since `wetty` does not have configurations files and all commands are passed as
Create a directory to store our configuration data using this command: Create a directory to store our configuration data using this command:
~~~bash ```bash
mkdir -p ~/.config/wetty 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 ```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 '--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
~~~ ```
This configuration file is now available here for you to manage your settings. This configuration file is now available here for you to manage your settings.
~~~bash ```bash
~/.config/wetty/config ~/.config/wetty/config
~~~ ```
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 ```bash
wetty $(eval echo $(cat ~/.config/wetty/config)) wetty $(eval echo $(cat ~/.config/wetty/config))
~~~ ```
#### forever using a config file #### 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 ```bash
forever start ~/bin/wetty $(eval echo $(cat ~/.config/wetty/config)) forever start ~/bin/wetty $(eval echo $(cat ~/.config/wetty/config))
~~~ ```
To stop `wetty` from running you can use this command: To stop `wetty` from running you can use this command:
~~~bash ```bash
forever stop ~/bin/wetty forever stop ~/bin/wetty
~~~ ```
#### Environment settings explained #### Environment settings explained
Let's break it down so that we can understand what's being done and why. Let's break it down so that we can understand what's being done and why.
~~~bash ```bash
--host 0.0.0.0 -p 3000 --title wetty --base / --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.
@ -273,9 +273,9 @@ Let's break it down so that we can understand what's being done and why.
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 ```bash
--sshkey ~/.ssh/wetty --sshhost localhost --sshuser $(whoami) --sshport 22 --sshauth publickey --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. `--sshkey ~/.ssh/wetty` - we are telling `wetty` to load our `ssh` key file that we generated earlier.
@ -291,9 +291,9 @@ These settings are all specific to `ssh` and will enable you to automatically lo
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 ```bash
--sslkey ~/.ssl/wetty.key --sslcert ~/.ssl/wetty.crt --sslkey ~/.ssl/wetty.key --sslcert ~/.ssl/wetty.crt
~~~ ```
`--sslkey ~/.ssl/wetty.key` - tells `wetty` to load our `openssl` generated key file. `--sslkey ~/.ssl/wetty.key` - tells `wetty` to load our `openssl` generated key file.
@ -305,9 +305,9 @@ We will use a local user `systemd` service file to manage the `wetty` service.
First, create the required directory, if it does not exist. First, create the required directory, if it does not exist.
~~~bash ```bash
mkdir -p ~/.config/systemd/user mkdir -p ~/.config/systemd/user
~~~ ```
#### Systemd service. #### Systemd service.
@ -315,13 +315,13 @@ Here is a normal service file template with hardcoded values you can insert into
Use `nano` to open the file for editing. Use `nano` to open the file for editing.
~~~ ```
nano ~/.config/systemd/user/wetty.service nano ~/.config/systemd/user/wetty.service
~~~ ```
The copy and paste this code. The copy and paste this code.
~~~bash ```bash
[Unit] [Unit]
Description=wetty Description=wetty
After=network.target After=network.target
@ -337,7 +337,7 @@ RestartSec=2
[Install] [Install]
WantedBy=multi-user.target 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`.
@ -347,13 +347,13 @@ Here is the example using our pseudo configuration file. All modifications to th
Use `nano` to open the file for editing. Use `nano` to open the file for editing.
~~~bash ```bash
nano ~/.config/systemd/user/wetty.service nano ~/.config/systemd/user/wetty.service
~~~ ```
The copy and paste this code. The copy and paste this code.
~~~bash ```bash
[Unit] [Unit]
Description=wetty Description=wetty
After=network.target After=network.target
@ -369,7 +369,7 @@ RestartSec=2
[Install] [Install]
WantedBy=multi-user.target 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`.
@ -377,15 +377,15 @@ Press `ctrl` + `x` and then press `y` to save then press `enter` to confirm and
The you can enable and start your service. The you can enable and start your service.
~~~bash ```bash
systemctl --user enable --now wetty systemctl --user enable --now wetty
~~~ ```
#### Managing your services #### Managing your services
These commands will help you manage your service. These commands will help you manage your service.
~~~bash ```bash
systemctl --user daemon-reload systemctl --user daemon-reload
systemctl --user status wetty systemctl --user status wetty
systemctl --user start wetty systemctl --user start wetty
@ -393,7 +393,7 @@ systemctl --user stop wetty
systemctl --user restart wetty systemctl --user restart wetty
systemctl --user disable --now wetty systemctl --user disable --now wetty
systemctl --user enable --now wetty systemctl --user enable --now wetty
~~~ ```
### Nginx reverse proxy ### Nginx reverse proxy
@ -403,15 +403,15 @@ 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 ```bash
--host 127.0.0.1 --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 ```bash
--base /wetty/ --base /wetty/
~~~ ```
Now you can use this nginx configuration file. Now you can use this nginx configuration file.
@ -419,7 +419,7 @@ Now you can use this nginx configuration file.
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 ```nginx
location /wetty { location /wetty {
proxy_pass https://127.0.0.1:3000/wetty; proxy_pass https://127.0.0.1:3000/wetty;
# #
@ -444,29 +444,29 @@ location /wetty {
proxy_redirect off; proxy_redirect off;
proxy_buffering 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: Now you would need to reload nginx service using this command:
~~~bash ```bash
systemctl restart nginx systemctl restart nginx
~~~ ```
#### Accessing the web interface via 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 ```bash
echo https://$(curl -s4 icanhazip.com)/wetty echo https://$(curl -s4 icanhazip.com)/wetty
~~~ ```
### Configuration reference ### Configuration reference
`wetty -h` configuration options for reference. `wetty -h` configuration options for reference.
~~~bash ```bash
--help, -h Print help message [boolean] --help, -h Print help message [boolean]
--version Show version number [boolean] --version Show version number [boolean]
--sslkey path to SSL key [string] --sslkey path to SSL key [string]
@ -484,4 +484,4 @@ echo https://$(curl -s4 icanhazip.com)/wetty
--host wetty listen host [string] [default: "0.0.0.0"] --host wetty listen host [string] [default: "0.0.0.0"]
--command, -c command to run in shell [string] [default: "login"] --command, -c command to run in shell [string] [default: "login"]
--bypasshelmet disable helmet from placing security restrictions [boolean] [default: false] --bypasshelmet disable helmet from placing security restrictions [boolean] [default: false]
~~~ ```

Loading…
Cancel
Save