How can I use an SSH tunnel through Systems Manager to access my private VPC resources?

6 minute read

I want to use an SSH tunnel through AWS Systems Manager to access my private Amazon Virtual Private Cloud (Amazon VPC) resources.

Short description

SSH tunneling, or SSH port forwarding, is a way to transport data over an encrypted SSH connection. SSH tunnels allow you to forward connections made to a local port to a remote machine through a secure channel. To create an SSH tunnel, use Session Manager. Session Manager is a capability of AWS Systems Manager that lets you use port forwarding for remote hosts. This feature is supported on SSM Agent versions 3.1.1374.0 and later. Port forwarding is an alternative to the following steps. For more information, see Starting a session (port forwarding to a remote host).

Session Manager uses the Systems Manager infrastructure to create a session with an instance similar to SSH. Session Manager tunnels real SSH connections, and allows you to tunnel to another resource within your Amazon VPC directly from your local machine. A managed instance that you create acts as a bastion host, or gateway, to your AWS resources.

The following points are benefits of this configuration:

Increased Security: This configuration uses one Amazon Elastic Compute Cloud (Amazon EC2) instance (the bastion host), and connects outbound port 443 to Systems Manager infrastructure. This allows you to use Session Manager without any inbound connections. The local resource must allow inbound traffic from only the instance that acts as the bastion host. This removes the need to open any inbound rule publicly.
Ease of use: Access resources in your private VPC directly from your local machine.

Note: For instructions on how to access your EC2 instances with a terminal or a single port forwarding, see Setting up Session Manager.

Prerequisites

Complete the following prerequisites:

Note: You must have the following installed to use the SSH feature:

SSM Agent v2.3.672.0 or newer
Session Manager Plugin v1.1.23 or newer on your local machine
AWS CLI v1.16.12 or newer on your local machine

Resolution

Note: If you receive errors when running AWS CLI commands, make sure that you're using the most recent version of the AWS CLI.

To use Session Manager to start the SSH tunnel, complete the following steps:

1. Run the following command to start the SSH tunnel:

ssh -i /path/my-key-pair.pem username@instance-id -L localport:targethost:destport

2. Run the following command to test access to the tunnel on the target port that you created:

telnet 127.0.0.1 localport

In the preceding example, 127.0.0.1 and localport translate to access targethost:destport.

Example configuration: Use SSM host as a bastion host to create a tunnel from a local machine to a MySQL database

Create a tunnel from your local machine to access a MySQL database. The database must run on an EC2 instance and use the SSM host as a bastion host.

Resources used

instance1: An EC2 instance that acts as a bastion host and is managed by AWS Systems Manager
Hostname = ec2-198-51-100-1.compute-1.amazonaws.com, Instance id = i-0123456789abcdefa

instance2: An EC2 instance that's running MySQL Database on the default port 3306
Hostname = ec2-198-51-100-2.compute-1.amazonaws.com

1. From a local machine (for example, your laptop), run the following SSH command to connect to instance1. This command uses Session Manager-based SSH and establishes a tunnel to port 3306 on instance2. It presents in your local machine on port 9090.

ssh -i /path/key-pair_instance1.pem username_of_instance1@i-0123456789abcdefa -L 9090:ec2-198-51-100-2.compute-1.amazonaws.com:3306

Note: In the preceding example, port 9090 is available on the local machine.

2. From the local machine, use the available port from step 1 (port 9090 in this example) to access the database.

mysql -u user -h 127.0.0.1 -P 9090 -p password

Note: instance2 must allow traffic from instance1. This includes all security groups, network access control list (network ACL), security rules, and third-party security software that exist on instance2. In the preceding example, instance2 must allow port 3306 access from instance1.

Example configuration: Create tunnels over a single SSH connection to access MySQL database and webserver instance

Create three tunnels over a single SSH connection from your local machine to:

Connect to the SSH port in instance1
Access a MySQL database in RDS instance
Access a webserver in instance3

Resources used

instance1: An EC2 instance that acts as a bastion host and is managed by AWS Systems Manager
Hostname = ec2-198-51-100-1.compute-1.amazonaws.com, Instance id = i-0123456789abcdefa

RDS instance: A MySQL RDS instance that's located in a private subnet
Hostname = DBinstanceidentifier.abcdefg12345.region.rds.amazonaws.com

instance3: An EC2 instance that's located in a private subnet
Hostname = ec2-198-51-100-3.compute-3.amazonaws.com

1. Run the following SSH command to start the session with three tunnels. There are three separate tunnel invocations in the command.

ssh -i /path/key-pair_instance1.pem username_of_instance1@i-0123456789abcdefa -L 8080:ec2-198-51-100-1.compute-1.amazonaws.com:22 -L 9090:DBinstanceidentifier.abcdefg12345.region.rds.amazonaws.com:3306 -L 9091:ec2-198-51-100-3.compute-1.amazonaws.com:80

Note: In the preceding example, ports 8080, 9090, and 9091 are available on the local machine.

2. Access SSH from the local machine to instance1. The local port 8080 tunnels to the SSH port (22) on instance1. The key-pair and username are for the instance you're tunneling to (instance1, in this example).

ssh -i /path/key-pair_instance1.pem username_of_instance1@127.0.0.1 -p 8080

3. Access the database on the RDS instance. The local port 9090 tunnels to port 3306 on the RDS instance. Use the GUI in MySQL workbench to access the DB server with 127.0.0.1 as hostname and 9090 as port. Or, run the following command in the shell command prompt:

mysql -u user -h 127.0.0.1 -P 9090 -p password

4. To access the website on instance3, open the browser from the local machine and navigate to the website.

http://127.0.0.1:9091

Important: Any security groups, network ACL, security rules, or third-party security software that exist on RDS instance and instance3 must allow traffic from instance1. In the preceding example, instance3 must allow port 80 access from instance1.