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

Short description

Session Manager port forwarding creates encrypted tunnels between your local machine and private VPC resources through a managed Amazon Elastic Compute Cloud (Amazon EC2) instance. This feature uses native Systems Manager capabilities. It doesn't require SSH keys, open inbound ports, or a bastion host configuration.

Use the AWS-StartPortForwardingSession document to forward traffic to a port on the managed Amazon EC2 instance. Use the AWS-StartPortForwardingSessionToRemoteHost document to forward traffic through the EC2 instance to another host in your VPC. Examples of other hosts include Amazon Relational Database Service (Amazon RDS) databases and private web servers.

Note: The AWS-StartPortForwardingSessionToRemoteHost document requires Systems Manager Agent (SSM Agent) version 3.1.1374.0 or later. Systems Manager doesn't need to manage the remote host.

Resolution

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

Complete the prerequisites

Before you start a port forwarding session, complete the following steps:

1. Complete the Session Manager prerequisites.
2. Install the Session Manager plugin for the AWS CLI.
3. Confirm that the managed instance has an AWS Identity and Access Management (IAM) instance profile with the AmazonSSMManagedInstanceCore policy attached.
4. Confirm that the managed instance has network connectivity to the Systems Manager service endpoints. Use a NAT gateway, internet gateway, or VPC endpoints for Systems Manager.
5. For remote forwarding, check that the managed instance can reach the target resource. The security group on the target resource must allow inbound traffic from the managed instance on the required port.
   Note: You don't need to open any inbound ports on the security group of the managed instance. SSM Agent initiates all connections outbound on port 443.

Forward a port to the managed instance

Use the AWS-StartPortForwardingSession document to forward traffic from your local machine to a port on the managed instance.

To start a port forwarding session, run the following start-session AWS CLI command based on your operating system (OS):

For Linux and macOS:

aws ssm start-session 
    --target INSTANCE-ID 
    --document-name AWS-StartPortForwardingSession 
    --parameters '{"portNumber":["PORT-NUMBER"],"localPortNumber":["LOCAL-PORT-NUMBER"]}'

For Windows:

aws ssm start-session ^
    --target INSTANCE-ID ^
    --document-name AWS-StartPortForwardingSession ^
    --parameters portNumber="PORT-NUMBER",localPortNumber="LOCAL-PORT-NUMBER"

Note: Replace INSTANCE-ID with the ID of your managed instance. Replace PORT-NUMBER with the port that you must forward to. Replace LOCAL-PORT-NUMBER with the port on your local machine.

After the session starts, connect to IP_ADDRESS:LOCAL-PORT-NUMBER on your local machine to access the service on the managed instance. Replace IP_ADDRESS with the IP address of the localhost (127.0.01) or the real IPv4 address of your local machine.

Forward a port to a remote host through the managed instance

Use the AWS-StartPortForwardingSessionToRemoteHost document to forward traffic from your local machine through the managed instance to another host in your VPC.

To start a remote host port forwarding session, run the following start-session AWS CLI command based on your OS:

For Linux and macOS:

aws ssm start-session \
    --target INSTANCE-ID \
    --document-name AWS-StartPortForwardingSessionToRemoteHost \
    --parameters '{"host":["REMOTE-HOST"],"portNumber":["PORT-NUMBER"],"localPortNumber":["LOCAL-PORT-NUMBER"]}'

For Windows:

aws ssm start-session ^
    --target INSTANCE-ID ^
    --document-name AWS-StartPortForwardingSessionToRemoteHost ^
    --parameters host="REMOTE-HOST",portNumber="PORT-NUMBER",localPortNumber="LOCAL-PORT-NUMBER"

Note: Replace INSTANCE-ID with the ID of your managed instance. Replace REMOTE-HOST with the hostname or IP address of the target resource. Replace PORT-NUMBER with the port on the remote host. Replace LOCAL-PORT-NUMBER with the port on your local machine.

After the session starts, connect to IP_ADDRESS:LOCAL-PORT-NUMBER on your local machine to access the remote resource. Replace IP_ADDRESS with the IP address of the localhost (127.0.01) or the real IPV4 address of your local machine. Replace LOCAL-PORT-NUMBER with the port on your local machine.

Access an Amazon RDS database through port forwarding

In the following example, you access a MySQL database on Amazon RDS through a managed instance in the same VPC. In the example, the managed instance has the instance ID i-0123456789abcdefa. The hostname of the RDS instance is mydb.example.us-east-2.rds.amazonaws.com, and it uses port 3306.

Run the following command to start the port forwarding session:

aws ssm start-session \
    --target i-0123456789abcdefa \
    --document-name AWS-StartPortForwardingSessionToRemoteHost \
    --parameters '{"host":["mydb.example.us-east-2.rds.amazonaws.com"],"portNumber":["3306"],"localPortNumber":["3306"]}'

In a new terminal window, connect to the database on your local machine:

mysql -u USER -h IP_ADDRESS -P 3306 -p

Note: Replace USER with your database username. Replace IP_ADDRESS with the IP address of the localhost (127.0.01) or the real IPv4 address of your local machine.

Access a private web server through port forwarding

In the following example, you access a web server that runs on a private EC2 instance through a managed instance. In the example, the managed instance has the instance ID i-0123456789abcdefa. The hostname of the private web server is ec2-123.12.34.45.compute-1.amazonaws.com, and the private web server uses port 80. 

Note: The security group of the private web server must allow inbound traffic on port 80 from the managed instance.

Run the following command to start the port forwarding session:

aws ssm start-session \
    --target i-0123456789abcdefa \
    --document-name AWS-StartPortForwardingSessionToRemoteHost \
    --parameters '{"host":[" ec2-123.12.34.45.compute-1.amazonaws.com "],"portNumber":["80"],"localPortNumber":["8080"]}'

Open a browser on your local machine and navigate to http:IP_ADDRESS:8080. Replace IP_ADDRESS with the IP address of the localhost (127.0.01) or the real IPV4 address of your local machine.

Related information

Starting a session (port forwarding to remote host)

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

Port forwarding using AWS Systems Manager Session Manager