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 a Debian based system. It covers the key configuration areas by using copy and paste commands. This will help you install this application and get it securely up and running with minimal system interference and reversible changes. It should also provide enough information to allow you to understand and extend that configuration for your personal requirements.
### Required dependencies
**Note:** Some of these configurations are optional, such as self signed SSL and public key authentication. The purpose of the guide is to show you how to correctly understand, configure, install and use these options should you wish to use them but they are not required to use WeTTY in general.
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.
## Required dependencies
`Node` - WeTTY requires node v14 or greater. We will install this locally for a non root user later in the guide.
`python` - This should be installed by default but we will include it in our `apt-get` command to be safe.
`build-essential` - 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:
```bash
apt update
apt install -y build-essential
apt install -y build-essential python
```
If you do not have root access and just want to check the dependency is
installed you can use this command:
If you have no root access and just want to check the dependencies are installed you can use these commands:
```bash
dpkg -s python | grep Status:
dpkg -s build-essential | grep Status:
```
If the program is installed you will see this result:
If the package is installed you will see this result:
```bash
Status: install ok installed
```
### Create a local user account
## 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 guide simple.
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
## 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). This is an established solution for installing and managing multiple versions of node without needing `root` access. This will allow you to install and use multiple versions of `node` at the same time.
This command will download and install `nvm` and reload our shell.
This command will install the latest version of the v14 branch, which is the minimum required version for WeTTY.
```bash
nvm install 14
```
You can now call `node` to check it works using this command.
@ -75,29 +73,20 @@ node -v
Your result should look something like this.
```bash
v12.16.2
v14.14.0
```
**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 overcome this issue for the needs of this guide is by using this
command where applicable:
**Note:** There is an important consideration with the `nvm` method. `node` is only in the local user's path through sourcing of the `~/.nvm/nvm.sh` which is done when the user logs in and the shell sources the user's `.bashrc` file. So for some applications who are not aware of this local shell environment `node` will not be usable unless we provide a full path and `nvm` commands will also be unavailable. The way we over come this issue for the needs of this guide is by using this command substitution to provide the full path, where applicable:
```bash
source ~/.nvm/nvm.sh && nvm which 14
$(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 14` installed via `nvm` regardless of other versions of `node` installed with `nvm`.
### Generate openssl certificates.
## 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:
@ -105,13 +94,12 @@ 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.
**Note:** we are using`ecdsa` using the `secp384r1` curve. Tested to be compatible with Chrome and Firefox browsers.
**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:
**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
```
### Install wetty
## 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's 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:
First, we need to make sure the local user's `~/bin` folder exists and is in the
`PATH` for the following commands to work.
To make sure the local user's `~/bin` directory exists and is in the `PATH` please run the following command.
```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.
`npm ` - optional - use `npm` to install wetty
Now use `npm` to install the `yarn` packet manager.
```bash
npm install -g wetty forever --prefix ~/
npm install -g yarn --prefix ~/
```
`yarn` - recommended - use `yarn` to install wetty
Then use `yarn` to install `wetty`.
```bash
npm install -g yarn --prefix ~/
yarn global add wetty forever --prefix ~/
yarn global add wetty --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
```
### Accessing the web interface.
## Accessing the web interface via our external IP
This needs to be done here because it is not easy to do in the next steps if
`wetty` is running in the terminal.
If you are using your external IP and not a domain to access WeTTY this step 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
## 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` .
**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. The key combination of `CTRL` + `c` will exit the application.
To stop `wetty` from running you can use this command
Let's break it down so that we can understand what's being done and why.
```bash
forever stop ~/bin/wetty
--host 0.0.0.0 -p 3000 --title wetty --base /
```
#### Optional - config file.
`--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.
Create a directory to store our configuration data using this command:
`-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.
```bash
mkdir -p ~/.config/wetty
```
`--title wetty` - an optional setting to set the window title for this `wetty` session.
Now populate our `config` file with some settings. This example is the same
command as above.
`--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.
Now we can load this file as part of the command we pass to `wetty` with shell
expansion and command substitution.
`--ssh-key ~/.ssh/wetty` - we are telling WeTTY to load our `ssh` key file that we generated earlier.
```bash
wetty --conf ~/.config/wetty/config.json
```
`--ssh-host localhost` - optional setting telling WeTTY to connect the host `localhost`
#### forever using a config file
`--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.
Now you can use `forever` to run it in the background instead of directly in
your terminal
`--ssh-port 22` - optional setting to set the `ssh` port we need to connect to.
`--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 `--sshauth password`. You can specify both `--sshauth publickey,password`
To stop `wetty` from running you can use this command:
`--ssh-config configfile` - (not used for this guide) alternative ssh configuration file. From ssh(1):
```bash
forever stop ~/bin/wetty
```
> If a configuration file is given on the command line, the system-wide
> configuration file (/etc/ssh/ssh_config) will be ignored. The default for the
> per-user configuration file is ~/.ssh/config.
#### Environment settings explained
### SSL settings explained
Let's break it down so that we can understand what's being done and why.
These settings are specific to `openssl` to make WeTTY load https webserver so that all data is transmitted over a secure connection.
`--ssh-key ~/.ssh/wetty` - we are telling `wetty` to load our `ssh` key file
that we generated earlier.
Here is the template `config.json` you need to use.
`--ssh-host localhost` - optional setting telling `wetty` to connect the host
`localhost`
**Note:** All option that you do not want to use can be commented out using `//`. For example `// title: 'Terminal', // Page title` will comment out this line and it will be ignored.
`--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.
```json
{
ssh: {
user: 'username', // default user to use when ssh-ing
host: 'localhost', // Server to ssh to
auth: 'publickey,password', // shh authentication, method. Defaults to "password", you can use "publickey,password" instead'
pass: "password", // Password to use when sshing
key: "/home/username/.ssh/wetty", // path to an optional client private key, connection will be password-less and insecure!
port: 22, // Port to ssh to
knownHosts: '/dev/null', // ssh knownHosts file to use
},
server: {
base: '/terminal/', // URL base to serve resources from
`--ssl-cert ~/.ssl/wetty.crt` - tells `wetty` to load our `openssl` generates
certificate file.
There are currently no environment settings for variables not listed above.
### Systemd service settings
## Systemd service settings
We will use a local user `systemd` service file to manage the `wetty` service.
@ -378,42 +349,74 @@ First, create the required directory, if it does not exist.
mkdir -p ~/.config/systemd/user
```
#### Systemd service.
### Systemd service
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`.
Here is an example template of how to use service file with hardcoded values you can set in the `wetty.service` file with all options enabled.
Use `nano` to open the file for editing.
Use `nano` to open a file for editing.
```bash
nano ~/.config/systemd/user/wetty.service
```
The copy and paste this code.
**Note:** This is an example service file based on all the options documented and configured so far. You may not want all these option enabled so please remove or modify the `ExecStart` command based on your needs.
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.
**Note:** This `ExecStart` assumes the location of your `config.json` to be `~/.config/wetty/config.json`. Please make sure you use the correct location for this file.
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 reverse 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/
@ -458,38 +458,38 @@ web root of `/` for nginx.
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` with `https://127.0.0.1:3000/wetty;` because we configured `wetty` to run via `https` using our self signed ssl certificates. If you chose not to run WeTTY with a self signed certificate you should changes this to `http://127.0.0.1:3000/wetty;`
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.
userdocs
4 years ago
GitHub