SSM Port Forwarding Guide

Learn how to securely connect to private databases and services using AWS Systems Manager Session Manager with hostname support.

Quick Start

Permissions required for hostname forwarding

devo ssm hosts setup modifies /etc/hosts. On Linux/macOS it will prompt for your sudo password. On Windows run your terminal as Administrator.

# 1. Add database
devo ssm database add \
  --name mydb \
  --bastion i-0123456789abcdef0 \
  --host mydb.cluster-xyz.us-east-1.rds.amazonaws.com \
  --port 5432

# 2. Setup hostname forwarding (requires sudo on Linux/macOS)
devo ssm hosts setup

# 3. Connect
devo ssm connect mydb

Your application can now use the real hostname without code changes!

How It Works

Your App -> mydb.rds.amazonaws.com:5432
         |
         v
/etc/hosts resolves to 127.0.0.2
         |
         v
Port forwarder -> 127.0.0.1:local_port
         |
         v
SSM Session Manager (encrypted tunnel)
         |
         v
Bastion Instance
         |
         v
Database (RDS, ElastiCache, etc.)

Prerequisites

Install Session Manager Plugin

This is required for all platforms and is different from AWS CLI:

# Verify installation
session-manager-plugin

Installation guides:

• Windows
• macOS
• Linux (Debian/Ubuntu)
• Linux (RedHat/CentOS)

Platform-Specific Requirements

Linux/macOS:

• devo ssm hosts setup uses sudo tee to write /etc/hosts — you will be prompted for your password
• On macOS, loopback aliases (127.0.0.x) are also configured automatically with sudo ifconfig — expect two sudo prompts on first setup

# Install socat
brew install socat  # macOS
sudo apt-get install socat  # Ubuntu/Debian

Windows:

• Run terminal as Administrator for hostname forwarding setup — devo ssm hosts setup requires elevated privileges to write C:\Windows\System32\drivers\etc\hosts
• netsh portproxy is built-in, no installation needed

Common Workflows

Single Database Setup

Connect to one database:

# 1. Add database configuration
devo ssm database add \
  --name myapp-dev \
  --bastion i-0123456789abcdef0 \
  --host myapp-dev.cluster-xyz.us-east-1.rds.amazonaws.com \
  --port 5432 \
  --profile dev

# 2. Setup hostname forwarding
devo ssm hosts setup

# 3. Connect
devo ssm connect myapp-dev

Your application uses:

# .env
DATABASE_HOST=myapp-dev.cluster-xyz.us-east-1.rds.amazonaws.com
DATABASE_PORT=5432

No code changes needed!

Multiple Databases

Connect to multiple databases simultaneously:

# Add databases
devo ssm database add --name dev-db --bastion i-xxx --host dev.rds.amazonaws.com --port 5432
devo ssm database add --name prod-db --bastion i-yyy --host prod.rds.amazonaws.com --port 5432
devo ssm database add --name redis --bastion i-xxx --host redis.cache.amazonaws.com --port 6379

# Setup all at once
devo ssm hosts setup

# Connect to all
devo ssm connect
# Select: "Connect to all databases"

Each database gets a unique loopback IP automatically, avoiding port conflicts.

Team Configuration Sharing

Share database configurations with your team:

# Export SSM configuration
devo config export -s ssm -o team-ssm-config.json

# Share file via git, Slack, etc.

# Team members import to their config
devo config import team-ssm-config.json -s ssm

# Each person runs setup
devo ssm hosts setup

# Connect
devo ssm connect

Multi-Environment Setup

Manage databases across different environments:

# Add databases for each environment
devo ssm database add \
  --name myapp-dev \
  --bastion i-dev \
  --host dev.rds.amazonaws.com \
  --port 5432 \
  --profile dev

devo ssm database add \
  --name myapp-staging \
  --bastion i-staging \
  --host staging.rds.amazonaws.com \
  --port 5432 \
  --profile staging

devo ssm database add \
  --name myapp-prod \
  --bastion i-prod \
  --host prod.rds.amazonaws.com \
  --port 5432 \
  --profile prod

# Setup
devo ssm hosts setup

Your microservices use environment variables:

# .env.dev
DATABASE_HOST=dev.rds.amazonaws.com
DATABASE_PORT=5432

# .env.staging
DATABASE_HOST=staging.rds.amazonaws.com
DATABASE_PORT=5432

# .env.prod
DATABASE_HOST=prod.rds.amazonaws.com
DATABASE_PORT=5432

No code changes needed across environments!

Temporary Connection

Quick connection without saving configuration:

devo ssm forward \
  --bastion i-0123456789abcdef0 \
  --host mydb.cluster-xyz.us-east-1.rds.amazonaws.com \
  --port 5432 \
  --profile dev

Database Types

PostgreSQL / RDS

devo ssm database add \
  --name postgres-db \
  --bastion i-xxx \
  --host mydb.cluster-xyz.us-east-1.rds.amazonaws.com \
  --port 5432

MySQL / Aurora

devo ssm database add \
  --name mysql-db \
  --bastion i-xxx \
  --host mydb.cluster-xyz.us-east-1.rds.amazonaws.com \
  --port 3306

Redis / ElastiCache

devo ssm database add \
  --name redis \
  --bastion i-xxx \
  --host redis.cache.amazonaws.com \
  --port 6379

MongoDB / DocumentDB

devo ssm database add \
  --name mongodb \
  --bastion i-xxx \
  --host docdb.cluster-xyz.us-east-1.docdb.amazonaws.com \
  --port 27017

Managing Connections

List Configured Databases

devo ssm database list

Connect to Specific Database

devo ssm connect mydb

Connect Without Hostname Forwarding

Use localhost instead of real hostname:

devo ssm connect mydb --no-hosts

Your application uses:

DATABASE_HOST=localhost
DATABASE_PORT=5432

Stop Connections

Press Ctrl+C to stop connections and clean up port forwarding rules.

Hostname Management

Setup All Hostnames

devo ssm hosts setup

Automatically:

• Assigns unique loopback IPs (127.0.0.2, 127.0.0.3, etc.)
• Updates /etc/hosts
• Configures port forwarding

List Managed Hostnames

devo ssm hosts list

Add Single Hostname

devo ssm hosts add mydb

Remove Hostname

devo ssm hosts remove mydb

Clear All Hostnames

devo ssm hosts clear

EC2 Instance Management

Add Instance for Shell Access

devo ssm instance add \
  --name bastion-dev \
  --instance-id i-0123456789abcdef0 \
  --region us-east-1 \
  --profile dev

Connect to Instance

devo ssm shell bastion-dev

List Instances

devo ssm instance list

Remove Instance

devo ssm instance remove bastion-dev

Configuration Management

View SSM Configuration

The SSM configuration is stored under the ssm key in ~/.devo/config.json. View it with:

devo config show -s ssm

Share Configuration

To share your SSM configuration with team members:

# Export SSM section
devo config export -s ssm -o team-ssm-config.json

# Share the file with your team (via git, Slack, etc.)

Import Configuration

To use a shared configuration:

# Import and merge with existing config
devo config import team-ssm-config.json -s ssm

Troubleshooting

Session Manager Plugin Not Found

Install the plugin (separate from AWS CLI):

# Verify installation
session-manager-plugin

# If not found, install from AWS documentation

Permission Denied (Linux/macOS)

The tool automatically uses sudo tee to write /etc/hosts and will prompt for your password. If you see permission errors, make sure your user has sudo rights.

Access Denied (Windows)

Run terminal as Administrator:

1. Right-click Command Prompt/PowerShell
2. Select "Run as administrator"
3. Run devo ssm hosts setup

Connection Refused

Check:

1. Bastion instance is running
2. Security groups allow SSM connections
3. SSM agent is installed on bastion
4. IAM permissions for SSM sessions

Database Not in /etc/hosts

# Run setup to configure hostname forwarding
devo ssm hosts setup

Port Already in Use

Each database automatically gets a unique loopback IP, avoiding conflicts. Check configuration:

devo ssm database list

Cleanup Port Forwarding (Windows)

# List all port proxy rules
netsh interface portproxy show all

# Delete specific rule
netsh interface portproxy delete v4tov4 listenaddress=127.0.0.2 listenport=5432

# Delete all rules
netsh interface portproxy reset

Security Considerations

• Loopback IPs (127.0.0.x) are only accessible from your local machine
• All traffic goes through encrypted SSM tunnels (TLS 1.2+)
• No SSH keys or direct bastion access required
• IAM policies control access to SSM sessions
• /etc/hosts entries are managed in a dedicated section

Best Practices

1. Use descriptive names: myapp-dev-db instead of db1
2. Run setup after adding databases: devo ssm hosts setup
3. Export configuration for team: devo config export -s ssm -o team-ssm-config.json
4. Use environment-specific profiles: set --profile when adding databases with devo ssm database add
5. Install Session Manager Plugin first: Verify before using SSM commands
6. Clean up on exit: Press Ctrl+C to properly stop connections
7. Test connections: Verify with devo ssm connect before deploying

Next Steps

• SSM Command Reference - Full command options
• AWS Setup - Configure AWS credentials
• DynamoDB Export - Export DynamoDB data