Installation and Setup

Prerequisites

Before installing TSWebTerm, the following packages must be installed on your system:

• libwebsockets-dev
• libuv-dev ( or libuv1-dev )
• libjson-c-dev ( or json-c-dev )
• zlib-dev
• sshpass

To install the prerequisites and TSWebTerm you must be logged in as root. Commands that require root privileges will begin with the root prompt (#).

To install on rpm-based systems (i.e. Red Hat, AlmaLinux, Rocky Linux):

# dnf install epel-release
# dnf install libwebsockets-devel libuv-devel json-c-devel zlib-devel sshpass

To install on Debian-based systems (i.e. Debian, Ubuntu):

# apt-get install -y libwebsockets-dev libuv1-dev libjson-c-dev zlib-dev sshpass

To install on SUSE-based systems (i.e. SUSE Linux, openSUSE):

# install libwebsockets-devel libjson-c-devel libuv-devel openssl-devel libopenssl-3-devel
sshpass

After a package is successfully installed, the output from the command will display “Complete!”.

Installing and Activating TSWebTerm

To install TSWebTerm, first unpack the master file:

# cd /opt/tbred
# mkdir tswebterm

# Copy the downloaded product file into /opt/tbred/tswebterm
# cd tswebterm

./install

# umask 0
# cpio -ivBumd < TSWT

The /usr/lib/basic, /usr/lib/basic/tmp and /var/log/tbred directories are required for activating and running TSWebTerm. The setup.sh script will create these directories if they do not exist. The /usr/lib/basic/tmp directory is required for generating PDFs. The setup.sh script will also install the tswebterm terminfo definition and setup log rotation for the TSWebTerm log files.

./setup.sh

# cd tswebterm/bin

To manually create the /usr/lib/basic, /usr/lib/basic/tmp and /var/log/tbred directories:

# mkdir /usr/lib/basic
# chmod 777 basic
# mkdir /usr/lib/basic/tmp
# chmod 777 /usr/lib/basic/tmp
# mkdir /var/log/tbred

After the /usr/lib/basic, /usr/lib/basic/tmp and /var/log/tbred directories have been created, either manually or via the setup.sh script, TSWebTerm must be installed and activated:

./install

# cd /opt/tbred/tswebterm
#./tswtact

Terminfo

TSWebTerm sets the UNIX/Linux TERM variable to ‘tswebterm’. This requires a terminfo entry. The tswebterm terminfo file is included with the TSWebTerm install and is located in the terminfo/t directory.

To manually install the TSWebTerm terminal definition:

# cp /opt/tbred/tswebterm/terminfo/t/tswebterm /usr/share/terminfo/t/tswebterm

Log Rotation

To manually setup log rotation for the TSWebTerm log files:

# cp /opt/tbred/tswebterm/bin/tswebterm.logrotate /etc/logrotate.d/tswebterm

Update the Firewall

Once installed, the TSWebTerm port and a range of ephemeral ( i.e. redirect ) ports must be opened in your firewall. The default TSWebTerm port number is 5622. The default range of ephemeral ( i.e. redirect ) ports used by TSWebTerm is 56220 to 60315. If a different port number or port range is to be used when connecting to TSWebTerm, use the desired port numbers when updating the firewall.

If not using a firewall appliance, the TSWebTerm port number and port range must be added to the system’s firewall.

To open the default port and port range via firewall-cmd, do the following:

# firewall-cmd --permanent --add-port=5622/tcp
# firewall-cmd --permanent --add-port=56220-60315/tcp
# firewall-cmd --reload

To open the default port and port range via ufw, do the following:

60315/tcp

# ufw allow 5622/tcp

When defining the redirect port range, the number of ports must be
greater than the user count.

Starting TSWebTerm

TSWebTerm Usage:	can be	started via the command line or as a service.
	tswebterm [options]
Options:
	-p, –port	Port to listen (default: 5622)
	-H, –ssh-host	ssh server host
	-P, –ssh-port	ssh server port (default: 22)
	-R, –rd-port-start	Redirect child port range start (default: 56220)
	-E, –rd-port-end	Redirect child port range end (default: 60315)
	-c, –child-timeout	Child process connection timeout (seconds) (default: 10)
	-C, –ssl-cert	SSL certificate file path
	-K, –ssl-key	SSL key file path
	-A, –ssl-ca	SSL CA file path for client certificate verification
	-s, –signal	Signal to send to the command when exit it (default: 1, SIGHUP)
	-T, –terminal-type	Terminal type to report, default: tswebterm
	-k, –ping-interval	Websocket ping interval (minutes) (default: 5)
	-6, –ipv6	Enable IPv6 support
	-d, –debug	Set tswebterm log level (default: 7)
	-D, –ws-debug	Set Websocket log level (default: 0)
	-h, –help	Print this text and exit

To start TSWebTerm via the command line, run the start script as root:

./start

# cd /opt/tbred/tswebterm

The start script:

# startup script - Thoroughbred Web Terminal
#

# wtport=5622

# Use the following on Ubuntu:
# UV_USE_IO_URING=0
# export UV_USE_IO_URING

wt_exe=/opt/tbred/tswebterm/tswebterm
# wt_param1=--port=$wtport
# wt_param2=--ssh-host=<system-name>
# wt_param3=--ssh-port=<port-number>
# wt_param4="--rd-port-start=<starting port number> --rd-port-end=<ending port number>"
# wt_param5="--ssl-key=<key file name> --ssl-cert=<cert file name> --ssl-ca=<ca file name>"
wt_cmd="$wt_exe $wt_param1 $wt_param2 $wt_param3 $wt_param4 $wt_param5"

$wt_cmd

To check that TSWebTerm is started and listening, run the following:

$ ps --ef | grep -w tswebterm
$ netstat --na | grep 5622

When running TSWebTerm on Ubuntu, it is recommended to disable the libuv library’s use of the io_uring kernel subsystem for asynchronous I/O to prevent issues such as high CPU usage.

By default, when the TSWebTerm server is started by the start script, it will allow HTTP connections on port 5622. To connect on a different port number, uncomment and change wtport to the desired port number and then uncomment wt_param2 to start TSWebTerm on the desired port:

wtport=2265

wt_parm2=–port=$wtport

The default ssh port number is 22. To run with a different ssh port number, uncomment and change wt_param3 to the desired port number to start TSWebTerm with the desired ssh-port:

wt_parm3=–ssh-port=22022

The default range of redirect ports used by TSWebTerm is 56220 to 60315. If a different range of ports is required, uncomment and change wt_param4 to start TSWebTerm with the desired port range:

wt_param4=“–rd-port-start=56220 –rd-port-end=57243”

To enable HTTPS connections, TSWebTerm must me started with the –ssl-key and –ssl-cert options. The –ssl-ca option is optional. Uncomment and change wt_param6 with the SSL information to start the TSWebTerm to allow HTTPS connections:

wt_parm5=“—ssl-key=./key.pem –ssl-cert=./cert.pem”

The specified private key file must be unencrypted ( i.e. no password/passphrase ). If the specified private key file is encrypted, TSWebTerm will not start.

Installing the TSWebTerm Service

The tswebterm.systemd service file:

# systemd unit file - Thoroughbred Web Terminal
#

[Unit]
Description=Thoroughbred Web Terminal
After=network.target
[Service]
Type=simple
UMask=000
# Use the following on Ubuntu:
# Environment=UV_USE_IO_URING=0
WorkingDirectory=/opt/tbred/tswebterm
ExecStart=/opt/tbred/tswebterm/tswebterm --ssh-host %H
# ExecStart=/opt/tbred/tswebterm/tswebterm --ssh-host %H --rd-port-start 56220 \

–rd-port-end 60315

# ExecStart=/opt/tbred/tswebterm/tswebterm –ssh-host %H –ssl-cert <cert file name> \

–ssl-key <key file name> –ssl-ca <ca file name>

[Install]
WantedBy=multi-user.target

To install the TSWebTerm service, the loadservice.sh script will copy the tsweberm.systemd file from the bin directory to the appropriate system directories or the service file can be loaded manually.

To install the TSWebTerm service via the script, run the following:

./loadservice.sh

# cd /opt/tbred/tswebterm/bin

By default, when the TSWebTerm server is started as a service, it will allow HTTP connections on port 5622. Similar to the start script, the service file can be modified to use a different port when connecting to TSWebTerm, to use a different port for ssh connections, to use a different redirect port range and to enable HTTPS connections.

If the TSWebTerm service needs to be modified, it is recommended that changes are made to the tswebterm.systemd file and then reloaded with the loadservice.sh script.

systemd

To manually install the TSWebTerm service:

# cp /opt/tbred/tswebterm/bin/tswebterm.systemd /etc/systemd/system/tswebterm.service
# systemctl daemon-reload

To start the TSWebTerm service:

# systemctl start tswebterm

To have the TSWebTerm service start automatically when the system boots:

# systemctl enable tswebterm

To stop the TSWebTerm service:

# systemctl stop tswebterm

To prevent the TSWebTerm service from starting automatically when the system boots:

# systemctl disable tswebterm

SELinux Configuration

If the TSWebTerm service does not start, check to see if SELinux is enabled and enforcing on the system.

# sestatus

To label the tswebterm program, do the following:

# semanage fcontext -a -t unconfined_exec_t /opt/tbred/tswebterm/tswebterm
# restorecon -v /opt/tbred/tswebterm/tswebterm

After relabeling the tswebterm program, restart the TSWebTerm service:

# systemctl start tswebterm

The wtservice.sh script

To perform all of the above service commands, run the tcservice.sh script located in the tswebterm/bin directory. This script must be run as root and will start, stop, restart, enable or disable the TSWebTerm service.

To start the TSWebTerm service:

# cd /opt/tbred/tswebterm/bin
# ./wtservice.sh start

To stop the TSWebTerm service:

# cd /opt/tbred/tswebterm/bin
# ./wtservice.sh stop

Stopping TSWebTerm

If TSWebTerm was started using the start script, search for the running tswebterm process and then kill the process:

# ps -ef | grep -w tswebterm
# kill < tswebterm process id>

If TSWebTerm was started as a service, then stop the service by either the systemctl command or the wtservice.sh script.

When TSWebTerm is stopped, all TSWebTerm connections will be terminated and display the reconnect message. When TSWebTerm starts again, these connections in reconnect mode will automatically restart the connection.

Terminal Table

TSWebTerm uses the TSWEBTRM terminal table, modify your TERM.MAP file accordingly. For more information on TERM.MAP please see the Basic Customization and Tuning Guide System Files manual.

tswebterm:TSWEBTRM

TSWebTerm as a Gateway

TSWebterm can function as a secure web-based gateway that allows users to access multiple systems on your network.

When running multiple TSWebTerm processes on a system, it is recommended that each TSWebTerm process is run from a different service file and uses a different range of redirect ports.

For example, to connect to system1.company.com, the system running TSWebTerm,, tswebterm.systemd:

ExecStart=/opt/tbred/tswebterm/tswebterm –ssh-host %H –rd-port-start 56220 –rd-port-end 56319

To connect to system2.company.com, tswebterm-5623.systemd:

ExecStart=/opt/tbred/tswebterm/tswebterm –port 5623 –ssh-host system2.company.com \

–rd-port-start 56320 –rd-port-end 56419

To connect to system3.company.com, tswebterm-5624.systemd:

ExecStart=/opt/tbred/tswebterm/tswebterm –port 5624 –ssh-host system2.company.com \

–rd-port-start 56320 –rd-port-end 56519

It is recommended that changes are made to each systemd service file in the /opt/tbred/tswebterm/bin directory and that the loadservice.sh script is updated to copy all systemd service files, then reloaded with the loadservice.sh script.

From the Thoroughbred Web Terminal Reference, version 8.9.1. Open this page in the PDF