Notes on SSH tunnels
Author: Merlin Hansen
Date: 2020-03-20 / 2024-03-11
Summary
This document provides information on using SSH tunnels to access various services hosted on CSCI servers from external non-VIU computers.
Several CSCI services are on VIU private networks which are not externally accessible. To access these services one can set up a SSH tunnel through otter.csci.viu.ca to the computer hosting the service on the CSCI network. The tunnel will then allow targeted network traffic to travel from the external local computer, through otter.csci.viu.ca, and to the desired server.
Example scenarios include accessing:
- web applications on wwwstu.csci.viu.ca from off campus
- database applications on marie.csci.viu.ca (aka dolphin.csci.viu.ca, and wwwstu.csci.viu.ca) from off campus
- Tomcat applications running on a lab machine (pup1 - pup19, cub1 - cub16, or kit1 - kit4)
- the CSCI assignment Git server from off campus
- the CSCI GitLab server from off campus.
This tutorial should be referenced on a as-needed basis. It is recommended to only complete the configuration for the service you currently need to access.
SSH Tunnel Resources
The following links have examples and general descriptions on how ssh tunnels work.
Prerequisites
Before attempting any of the procedures outlined below it is strongly recommended to configure SSH Keys and the SSH ProxyJump option as outlined in the CSCI tutorial Tutorial-sshClient.md, on Dave's Tech Notes page.
CSCI use of SSH tunnels
The following scenarios are typical:
- Accessing web pages on wwwstu.csci.viu.ca (dolphin)
- Accessing MySQL/MariaDB on dolpin.csci.viu.ca (wwwstu.csci.viu.ca or marie.csci.viu.ca))
- Access Tomcat on a cub lab machine
- Accessing the CSCI Git Assignment server on cscidb
- Copying a file stored on a specific lab machine to a local external computer
For this tutorial the following is used throughout:
- An example user named "exstu" is used for the login username where needed.
- Replace "exstu" with your CSCI username in the example commands in this tutorial.
- Command line SSH client is used. Examples include:
- Bash terminal on Linux or Apple OS X.
- PowerShell prompt on Windows 10+.
- Note: PowerShell has built in aliases that match most of the commands used in this tutorial. It is the recommended command-line tool to use on Windows.
- Windows Terminal app (found in the Microsoft store and is published by Microsoft, and provides tabs and other great features)
- Note: The app uses PowerShell as the command-line shell by default.
- Command prompt on Windows 10+.
- Note: Some commands in the examples are different in Windows vs Linux (ex:
dir
instead of ls
).
- Git Bash prompt, installed on Windows 10.
- Linux Terminal on Windows (using Windows Subsystem for Linux - WSL), running the Bash shell.
Accessing web pages hosted on wwwstu.csci.viu.ca
Using command line only and not utilizing an ssh config file
- Create an ssh tunnel from the local computer to wwwstu.csci.viu.ca via otter.csci.viu.ca
- Bash/PowerShell:
ssh -N -L 8080:wwwstu.csci.viu.ca:80 exstu@otter.csci.viu.ca
- Creates a tunnel from localhost:8080 to wwwstu.csci.viu.ca:80 (web port) via otter.csci.viu.ca
- Port 8080 on the local machine is chosen to avoid ports below 1024 which are reserved and typically secured.
- -N indicates that no prompt or command is desired on the remote server otter.csci.viu.ca
- No prompt will appear after successful authentication
- -L 8080:wwwstu.csci.viu.ca:80 specifies the tunnel to be created
- Test the tunnel using a web browser on the local computer
- Browse to desired location on wwwstu.csci.viu.ca
- http://localhost:8080/~exstu/index.html
- Opens the index.html file stored in user's ~/public_html folder
- In some cases "127.0.0.1" must be used in place of "localhost". Try this only if using localhost does not work.
- To exit the ssh tunnel, exit the ssh connection by typing ctrl-c in the terminal
Accessing MySQL/MariaDB on dolphin.csci.viu.ca (wwwstu.csci.viu.ca)
Using command line only and not utilizing an ssh config file
- Create an ssh tunnel from the local computer to dolphin.csci.viu.ca via otter.csci.viu.ca
- Bash/PowerShell:
ssh -N -L 3306:dolphin.csci.viu.ca:3306 exstu@otter.csci.viu.ca
- Creates a tunnel from localhost:3306 to dolphin.csci.viu.ca vi otter.csci.viu.ca
- Port 3306 on the local machine is the entry point to the tunnel and is the well-known MySQL port
- -N indicates that no prompt or command is desired on the remote server otter.csci.viu.ca
- -L 3306:dolphin.csci.viu.ca:3306 specifies the tunnel to be created
- Test the tunnel using a mysql tool on the local computer
- Use either the MySQL command line tool (if installed) or a graphical database tool
- Bash/PowerShell:
mysql --user=exstu --host=localhost --password
- The short form of the above is
mysql -u exstu -h localhost -p
- In some cases "127.0.0.1" must be used in place of "localhost". Try this only if using localhost does not work.
- To exit the ssh tunnel, exit the ssh connection by typing ctrl-c in the terminal
DBeaver Community is a free open source tool for working with databases. It has built-in ability to connect to remote databases using direct connections, SSH Tunnels, or even SSH Jumpboxes. It is beyond the scope of this tutorial to provide specific configuration details for DBeaver. However, there is plenty of information on the DBeaver website: DBeaver.io.
Accessing a Tomcat instance running on a lab machine
Using command line only and not utilizing an ssh config file
- Connect to the desired lab through otter.csci.viu.ca and launch the Tomcat instance
- Bash/PowerShell:
ssh exstu@otter.csci.viu.ca
- From otter, connect to a desired lab machine
- Bash/Powershell:
ssh exstu@cub5.csci.viu.ca
- Launch the Tomcat instance on the lab machine
- Create an ssh tunnel from the local computer to the Tomcat instance running on the lab machine
- Note Tomcat typically listens on 2 or 3 ports: 8080 (http), 8443 (https), and (8009 AJP)
- Tomcat ports can be configured in the server.xml file
- Either separate tunnels for each port can be created or multiple connections can be established through one tunnel
- Bash/PowerShell:
ssh -N -L 8080:cub5.csci.viu.ca:8080 -L 8009:cub5.csci.viu.ca:8009 exstu@otter.csci.viu.ca
- This creates two tunneled connections at once: port 8080 and port 8009.
- Test the tunnel using a web browser on the local computer
- Browse to the Tomcat port connected to cub5.csci.viu.ca
- http://localhost:8080
- In some cases "127.0.0.1" must be used in place of "localhost". Try this only if using localhost does not work.
- To exit the ssh tunnel, exit the ssh connection by typing ctrl-c in the terminal
Creating one ssh tunnel to access multiple services
Using command line only and not utilizing an ssh config file
SSH can support multiple tunnel connections to different hosts through a single tunnel via a gateway. Here the gateway is otter.csci.viu.ca and the connections are one to MySQL on dolphin (wwwstu.csci.viu.ca) and one to a Tomcat instance on cub5.csci.viu.ca.
- This example assumes a connection has been established to cub5 and a Tomcat instance launched
- See the previous section on how to do this
- Create an ssh tunnel from the local computer to both the Tomcat instance on cub5 and to MySQL on dolphin
- Bash/Powershell:
ssh -N -L 8080:cub5.csci.viu.ca:8080 -L 3306:dolphin.csci.viu.ca:3306 exstu@otter.csci.viu.ca
- Test the tunneled connection to the Tomcat instance
- Browse to the Tomcat port on cub5.csci.viu.ca
- Test the tunneled connection to MySQL on wwwstu.csci.viu.ca (dolphin.csci.viu.ca)
- Use either the MySQL command line tool (if installed) or a graphical database tool
- Bash/PowerShell:
mysql --user=exstu --host=localhost --password
- The short form of the above is
mysql -u exstu -h localhost -p
- In some cases "127.0.0.1" must be used in place of "localhost". Try this only if using localhost does not work.
- To exit the ssh tunnel, exit the ssh connection by typing ctrl-c in the terminal
Accessing git repositories on cscidb.csci.viu.ca from off campus
SSH tunnels can be used to establish a connection from a local computer to cscidb.csci.viu.ca via otter.csci.viu.ca. The tunnel is established in much the same way as the above examples. However, for local git commands to access repositories on csci servers additional ssh configuration must be made.
The following steps are common for both of the sections below and should be completed prior to continuing.
Now that the basic configuration is done the next step is to connect to the CSCI internal Git Server. Connecting to the CSCI Git server involves establishing a SSH tunnel through otter.csci.viu.ca to the Git server. This connection must be in place in order to use any remote Git commands.
Example Git commands which act locally only: git status
, git add
, git commit
, git log
, git stage
, etc. Example Git commands which talk to the remote Git server: git fetch
, git pull
, git push
git clone
, etc. Specific CSCI Git commands which talk to the remote Git server: ssh csci info
, ssh csci fork
, etc.
Use one of the methods outlined in the following sections to connect to the CSCI Git server.
Without first following the SSH Client configuration tutorial
It is highly recommended that you configure your SSH setup as outlined in Tutorial-sshClient.md. However, if you decide against this then the following procedure can be used.
This method requires you to manually establish a separate SSH tunnel anytime you want to use a remote Git command. The tunnel must stay connected until you are finished the remote commands.
- Establish the ssh tunnel to the Git server via otter.csci.viu.ca
- Bash/PowerShell:
ssh -N -L 1234:cscidb.csci.viu.ca:22 exstu@otter.csci.viu.ca
- Enter your CSCI password when prompted. No further output will be generated.
- Use ctrl-c to exit the tunnel connection when remote Git commands are no longer needed
- Note: if you changed the local Port setting in the config file above, use the that same port in this command instead of 1234.
- Test the tunnel connection
- Bash/PowerShell:
ssh csci info
- The Git server will return a greeting along a list of repositories you have access to, if the tunnel connection is established.
- Use remote Git commands as needed and exit the tunnel when finished.
At this point your configuration is complete.
After completing the SSH Client configuration tutorial
Once you have completed the SSH setup as outlined in Tutorial-sshClient.md, you can use the procedure outlined below to modify your SSH config file for remote git server access.
The config file, ~/.ssh/config
can be modified to use otter.csci.viu.ca as a jumpbox, similar to how one accesses a CSCI lab machine.
- Edit the existing
~/.ssh/config
file created as part of the procedures outlined in Tutorial-sshClient.md and add the following entry.
Host csci
Hostname cscidb
ProxyJump cscijump
User csciadm
IdentityFile ~/.ssh/csci
- Note: The entry can be anywhere after the "Host cscijump" entry. A logical place is to add it just before the "Host otter otter.csci.viu.ca" entry.
- Test the connection to the CSCI internal Git server
- Bash/PowerShell:
ssh csci info
- The Git server will return a greeting along a list of repositories you have access to, if the tunnel connection is established.
With the above entry in the config file CSCI Git repositories can be manipulated remotely using remote Git commands outlined previously.
Copying a file stored on a specific lab machine to a local external computer
In CSCI 251 it is typical to have a logical volume drive created on a particular lab machine for storage of large files such as virtual machines and ISO image files. Since lab machines are not directly accessible from off campus, copying files to and from these spaces directly is not possible. Two options are available:
- Copy the desired files onto otter and then to/from the external local computer
- Has the risk of exceeding the user's quota
- Is a two step process
- Create an ssh tunnel to the lab machine and use scp to copy the files directly
- This is the method shown below
For this example the follow assumptions are made: * The user's login name is exstu * The desired file is stored in a logical volume on cub5 (cub5:/.exstu/myfile)
- Create an ssh tunnel from the local computer to cub5 via otter.csci.viu.ca
- Bash/PowerShell
ssh -N -L 2222:cub5.csci.viu.ca:22 exstu@otter.csci.viu.ca
- Localhost:2222 is the local start point of the tunnel
- cub5.csci.viu:22 (ssh port used by the scp command) is the end point of the tunnel
- Use scp to copy the desired file from cub5 to the current directory on the local computer
- Bash/PowerShell
scp -P 2222 exstu@localhost:/.exstu/myfile .
- The -P option tells scp to use port 2222 (the start point of the ssh tunnel created above)
- Specifying "@localhost" connects scp through the ssh tunnel to cub5.csci.viu.ca via otter.csci.viu.ca
- In some cases "127.0.0.1" must be used in place of "localhost". Try this only if using localhost does not work.
- Exit the ssh tunnel by pressing ctrl-c in the terminal where the tunnel was established
Using graphical programs such as PuTTY to create ssh tunnels
- References:
- There are many good references and videos on the net explaining how to configure PuTTY. The following two have decent examples of using both command line and PuTTY
- https://security.berkeley.edu/education-awareness/how-articles/system-application-security/securing-network-traffic-ssh-tunnels
- https://www.howtogeek.com/168145/how-to-use-ssh-tunneling/
- Looking at one of the command line examples above in this tutorial:
- Bash/PowerShell:
ssh -N -L 8080:wwwstu.csci.viu.ca:80 exstu@otter.csci.viu.ca
- "8080" is the Source port on the local computer (localhost), or the local end of the ssh tunnel
- "wwwstu.csci.viu.ca:80" is the destination host and port, or the remote end of the ssh tunnel
- PuTTY configuration of the above
- Open the PuTTY client user interface
- In the Session window, configure the following connection
- Host Name (or IP address): otter.csci.viu.ca
- Port: 22
- Connection type: SSH
- On the left pane where options are shown, navigate to Connection -> SSH -> Tunnels
- Under "Add new forwarded port:"
- Source port: 8080
- Destination: wwwstu.csci.viu.ca:80
- Select "Local" and "Auto"
- Click "Add"
- Give the session a name, such as "wwwstu tunnel" and save the session
- Open the connection and establish the tunnel by selecting the "wwwstu tunnel" and clicking Open
- Enter a CSCI username and password
- Test the tunnel connection using a local web browser
- Browse to http://localhost:8080/~exstu to view what is stored in the user's ~/public_html folder