Skip to content

Configure AWS for StormTunnel

StormTunnel sends a port-forwarding session through an EC2 instance managed by AWS Systems Manager (SSM). The instance must reach the private destination, such as an RDS endpoint. The user's Mac runs AWS CLI v2 and the Session Manager plugin. The AWS identity in the user's profile starts and ends the session; the EC2 instance role lets SSM Agent communicate with Systems Manager; VPC routes and security groups control the separate path from EC2 to the destination.

Connection Path

  1. StormTunnel uses the selected AWS profile to request a Session Manager port-forwarding session.
  2. The SSM-managed EC2 instance opens a connection to the configured private host and port.
  3. The user's database or service client connects to a local port on the Mac.

The EC2 instance does not need an inbound SSH rule. AWS IAM access, SSM connectivity, and database network access are separate requirements.

Set Up the EC2 Instance

Use an EC2 instance in a VPC and subnet that can route to the RDS database or internal service.

  1. Attach an instance role that allows SSM Agent to register and communicate with Systems Manager. AWS's AmazonSSMManagedInstanceCore managed policy is the standard starting point.
  2. Confirm that SSM Agent is installed and the instance appears as Online in Systems Manager.
  3. Allow outbound HTTPS (TCP 443) from the instance to Systems Manager endpoints. Use NAT or the required VPC interface endpoints.
  4. For remote-host port forwarding, use SSM Agent 3.1.1374.0 or later. This is the AWS requirement for forwarding to a database or service on a different host from the managed instance.
  5. Confirm the instance can resolve and connect to the destination host and port.

See AWS documentation for instance permissions and managed node setup.

Allow Access to RDS

The RDS security group should allow inbound database traffic from the EC2 instance's security group on the database port. Do not open the database to the public internet for this workflow.

Also check:

  • VPC routes and network ACLs between the instance and database.
  • DNS resolution for the RDS endpoint from the instance's subnet.
  • Any firewalls between the instance and destination.

Grant User Permissions

The AWS user or role selected in StormTunnel needs permission to start the remote-host port-forwarding session to the intended EC2 instance and end its own sessions. Instance discovery and status checks may require describe permissions.

Scope the policy to the required instances, regions, accounts, and session documents. See AWS IAM permissions and AWS's Session Manager end-user policy examples.

AmazonSSMManagedInstanceCore belongs on the EC2 instance role. It does not grant the end user permission to start a session.

Prepare the Mac

Install AWS CLI v2 and the Session Manager plugin. If you use Homebrew, you can install both with brew install awscli session-manager-plugin. Or follow AWS's instructions for AWS CLI v2 on macOS and the Session Manager plugin on macOS. Verify the commands are available in Terminal:

aws --version
session-manager-plugin --version

StormTunnel looks for the tools in /opt/homebrew/bin and /usr/local/bin, and for the plugin in the AWS installer location (/usr/local/sessionmanagerplugin/bin). Open Settings > AWS and click Verify AWS Setup… to confirm the app can find both tools.

Configure the AWS profile StormTunnel should use. StormTunnel resolves credentials through AWS CLI v2 (aws configure export-credentials), so the profile must work with the aws command. For IAM Identity Center profiles, sign in with aws sso login --profile PROFILE, or use StormTunnel's in-app SSO sign-in with a Premium license.

See AWS SSO authentication.

Verify the Setup

Check that the instance is online:

aws ssm describe-instance-information --filters "Key=InstanceIds,Values=i-0123456789abcdef0" --region us-east-1

Test port forwarding from the Mac, replacing the profile, region, instance ID, database endpoint, and ports with your values:

aws ssm start-session \
    --profile PROFILE \
    --region us-east-1 \
    --target i-0123456789abcdef0 \
    --document-name AWS-StartPortForwardingSessionToRemoteHost \
    --parameters '{"host":["mydb.example.us-east-1.rds.amazonaws.com"],"portNumber":["5432"],"localPortNumber":["5432"]}'

Connect a database client to 127.0.0.1:5432. Press Ctrl+C in the terminal to end the test session. AWS requires SSM Agent 3.1.1374.0 or later for remote-host port forwarding.

After the CLI test succeeds, create the same tunnel in StormTunnel. In the tunnel editor, Validate checks your credentials and the managed instance's status when AWS permissions allow. Test Permissions checks read-only discovery permissions; ssm:StartSession and ssm:TerminateSession remain Unverified in that check. Starting the tunnel exercises ssm:StartSession, and stopping it exercises ssm:TerminateSession. Neither check tests the EC2-to-database network path. See AWS IAM permissions and Connect to a private RDS database.

Troubleshooting

  • Instance is missing or offline: Check the instance role, SSM Agent, outbound HTTPS, VPC endpoints or NAT, and Systems Manager status.
  • Access denied: Check the user's IAM policy, session document access (AWS-StartPortForwardingSessionToRemoteHost), permission boundaries, and organization policies.
  • Port forwarding fails: Confirm the SSM Agent version, AWS region, and Session Manager plugin installation.
  • Connection to RDS fails: From the EC2 instance, verify DNS, routes, network ACLs, and the RDS security group rule.

For application-side errors, see Troubleshooting.