Logo       PBase-Foundation

GoTTY

Installation - Summary

Substitute your email and HTTP basic auth login username in the echo commands,
then run the yum commands as detailed below.

echo "myaddress@myemailprovider.com" > /root/DEFAULT_EMAIL_ADDRESS.txt
echo "shell" > /root/DEFAULT_SUB_DOMAIN.txt
echo "mark" > /root/DEFAULT_DESKTOP_USERNAME.txt
yum -y install https://pbase-foundation.com/pbase-repo.rpm
yum -y install pbase-preconfig-gotty
yum -y install pbase-gotty

Installation - Step by Step

Here is how to install an instance of the GoTTY terminal service. It assumes your host is registered in DNS on a "shell" subdomain like shell.myexample.com and the installer will use Let's Encrypt to setup HTTPS certificates.

Step 1: Provide your email address, optionally change the subdomain name, and define the login username that will be used for the HTTP basic authentication by using the echo command to create a text file.
For example:

echo "myaddress@myemailprovider.com" > /root/DEFAULT_EMAIL_ADDRESS.txt
echo "shell" > /root/DEFAULT_SUB_DOMAIN.txt echo "mark" > /root/DEFAULT_DESKTOP_USERNAME.txt

(Note: This is unrelated to any other username in your system, it is only used to access the GoTTY page.)

Step 2: Install the pbase-repo package with the command:
yum -y install https://pbase-foundation.com/pbase-repo.rpm

... when it runs, its output will point out the file pbase_repo.json that now holds copies of the defaults.

Step 3: Install the GoTTY dependencies and pre-configuration package with the command:
yum -y install pbase-preconfig-gotty

Step 4: It's output will tell you to review pbase_gotty.json in the module-config.d directory:
vi /usr/local/pbase-data/admin-only/module-config.d/pbase_gotty.json

... this file contains the values to customize the GoTTY service. It also contains a randomly generated password that will be used for the HTTP basic authentication.

Step 5: Install the pbase-gitea package with the command:
yum -y install pbase-gotty

When the pbase-gotty package completes you should have a full working instance of GoTTY ready to be administered at https://shell.myexample.com depending on your domain name.

It will present the HTTP basic auth dialog. Enter the user and password defined in the pbase_gotty.json file.

Extras

You should secure your server ports with pbase-firewall-enable and lock down SSH access with the pbase-ssh-fail2ban package.

yum -y install pbase-firewall-enable
yum -y install pbase-ssh-fail2ban

Compatibility

The pbase-gotty installer package has been tested on CentOS 7 and 8, Fedora 33, and Amazon Linux 2

Configuration Options

The first step of the installer is the pbase-repo package. It creates the module-config.d directory to hold customizable configuration option files:
/usr/local/pbase-data/admin-only/module-config.d/

The pbase-repo creates this file: pbase_repo.json
it must be edited to set the defaultEmailAddress field with your email.

{
"pbase_repo": {
"defaultEmailAddress": "myaddress@myexample.com",
"defaultDesktopUsername": "",
"defaultSmtpPassword": "9876543210987654321-87654321",
"defaultSubDomain": ""
}
}

The third step of the install is the pbase-preconfig-gotty package. It places the file described below under the /usr/local/pbase-data/admin-only/module-config.d/ directory.

This is the GoTTY configuration options file: pbase_gotty.json
These defaults are appropriate for most use cases.

{
"pbase_gotty": {
"enableAutoRenew": true,
"executeCertbotCmd": true,
"usePrebuiltBinary": false,
"urlSubDomain": "shell",
"additionalSubDomain": "",
"emailAddress": "pbase.foundation@gmail.com",
"basicAuthUsername": "myusername",
"basicAuthPassword": "uMDdiYzdh"
}
}

(Limitations: changing the usePrebuiltBinary or additionalSubDomain fields is not implemented in 1.0)

Subdomain name

The default install assumes the 'shell' subdomain is configured in DNS. But to configure a subdomain besides 'shell' you must edit the urlSubDomain field in the pbase_gotty.json file created in step two of the install.

The other option is to have GoTTY for your root domain. In this case, simply set the urlSubDomain fields to an empty string.

More about GoTTY

The GoTTY project's Github page:
https://github.com/yudai/gotty/
"GoTTY - Share your terminal as a web application."

Restrict Access

This service exposes a login screen and as such, access to it needs to be restricted. Specifically: Only run it behind a firewall the only grants access to known clients addresses. Only launch the gotty service when needed and stop when done. Do not install on production servers.