AWS Cloud Operations Blog

Use port forwarding in AWS Systems Manager Session Manager to connect to remote hosts

We recently announced a new capability within AWS Systems Manager Session Manager that allows forwarding connections from client machines to ports on remote hosts. This enables users to securely access and manage remote servers (databases, web servers, etc.) in the private networks without needing to setup bastion hosts or open additional ports to the outside networks. In this post, I’ll walk you through an example of setting up port forwarding to remote hosts using this new capability of Session Manager.

About AWS Systems Manager Session Manager

AWS Systems Manager Session Manager is a fully-managed Systems Manager capability. Session Manager lets you connect to and manage your instances, edge devices, as well as on-premises servers and virtual machines (VMs). You can use either an interactive one-click browser-based shell or the or the AWS Command Line Interface (AWS CLI).

Scenario

Let’s say you are trying to use a graphical tool on your local machine (e.g. SQL Workbench/J) to manage a (MySQL) instance that is inside a subnet within an Amazon Virtual Private Cloud (Amazon VPC) (Figure 1). Typically, this would require you to open up TCP port 3306 to allow connection to this database over the Internet, however this is not a best practice from the security standpoint. Alternatively, you could also try to setup a bastion host (jump server) and install all the tools on it but that would require lot of extra work to setup and maintain. In the next section, I will show how “port forwarding” in Session Manager can be used to connect to remote MySQL database from local client without the hassle of setting up a jump host.

] Image showing overall solution architecture. On the left hand side, we show a client opening up SSH session to a Systems Manager managed instance. The SSM is forwarding port 1053 on localhost to TCP port 3306 on remote SQL server

Figure 1: Overall solution for connecting to remote hosts in private networks

Prerequisites

Note that Systems Manager Session Manager sessions can be launched from or AWS CLI. For this post I will use the CLI method

Step 1: Instance setup and verification

Verify that you can connect to the Systems Manager managed instance from your local machine. Open your favorite terminal program (putty, or Mac Terminal etc.) and enter the following command. Replace ssm-managed-instance-id with the EC2 instance id of your SSM managed instance.

aws ssm start-session --target <ssm-managed-instance-id>

If the connection is successful, setup is verified. You can close the connection and proceed to the next step.

Step 2: Open a connection forwarding session to a remote port on MySQL server

In this step, you will relaunch the Session Manager session, but this time we’ll execute a Systems Manager Document that will initiate a connection forwarding session to the remote database server. Enter the following command in the terminal replacing ssm-managed-instance-id and remote-database-host-name with their corresponding values based on your setup.

Note: In this example, we are using local port 1053, but you can choose a different local port if you prefer

aws ssm start-session --target <ssm-managed-instance-id> --document-name AWS-StartPortForwardingSessionToRemoteHost --parameters '{"portNumber":["3306"],"localPortNumber":["1053"],"host":[" remote-database-host-name"]}'

Please leave this running until the end of this exercise.

Step 3: (Optional) Verify that connection forwarding is working

You can verify that the connection forwarding is working by running the following command in a new terminal window. This will allow you connect to the database over CLI session.

mysql -h 127.0.0.1 --port 1053 -u admin -p

Step 4: Connect using SQL Workbench/J

Launch SQL Workbench/J on your local machine. If you already have a connection profile for this database, you can use it, otherwise you can create a new one based on the connection parameters (Username, password etc.) specific to your database. Please note that instead of using the remote IP or hostname of your database, you will be using local host IP address in the URL field.

Jdbc:mysql://127.0.0.1:1053/<database-name>

A screenshot from 'SQL Workbench' showing 'Connection Profile' window with the relevant fields filled out. These fields include Driver, URL, Username, and Password

Figure 2: SQL Workbench – Connection Profile

Hit “OK”, and you will now be connected to your remote database.

A screenshot from 'SQL Workbench/J' showing the SQL query and subsequent results in the bottom section resulting from running that query indicating the success connection

Figure 3: SQL Workbench showing query results

Conclusion

In this post I showed you how to connect to remote servers inside of private networks using Systems Manager Session Manager via the “port forwarding to remote host” feature. I used RDS mySQL server as an example. However, this same method can be used to remotely manage any type of hosts using your favorite management software from local client.

About the author:

Faraz Rehman

Faraz Rehman is senior Solutions Architect at AWS based in the San Francisco Bay Area. For the past few years he has been focused on helping ISV customers build and operate business critical, production scale workloads on AWS. His expertise includes cloud operations, management and governance.