How to Connect to Your Koha EC2 Server

There are three ways to get a terminal session on your Koha EC2 instance. SSM Session Manager is the recommended method — it requires no open ports, no key pairs, and works even when the instance has no public IP.

Method 1 — SSM Session Manager ✅ Recommended

SSM Session Manager lets you open a terminal session without port 22, without a key pair, and without a public IP. The instance calls out to the SSM service — no inbound firewall rules needed.

Requirements:

• The instance must have an IAM instance profile with the AmazonSSMManagedInstanceCore policy attached
• The SSM agent must be running (pre-installed and enabled on all KohaSupport AMIs)
• Your local AWS CLI must have session-manager-plugin installed (for CLI connections)

Check if SSM is available for your instance

EC2 Console → Instances → select your instance → Actions → Connect → Session Manager tab. If the tab shows a Connect button (not greyed out), SSM is ready.

If it is greyed out, the instance likely does not have an instance profile attached — see below.

Attach an instance profile (if not already done)

If your instance was launched without an IAM instance profile:

1. EC2 Console → select your instance → Actions → Security → Modify IAM role
2. Attach a role that includes AmazonSSMManagedInstanceCore
3. Wait ~2 minutes for the SSM agent to register

If you need to create a new role: IAM Console → Roles → Create role → EC2 → attach AmazonSSMManagedInstanceCore → name it (e.g. KohaSSMRole) → create.

Connect from the AWS Console

1. EC2 Console → select your instance → Connect → Session Manager → Connect

A browser terminal opens.

Connect from the AWS CLI

Install the Session Manager plugin: https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html

aws ssm start-session \
  --target i-0123456789abcdef0 \
  --profile your-aws-profile \
  --region us-east-1

You will land in a session as ssm-user. To switch to ubuntu:

sudo su - ubuntu

Or start a session directly as ubuntu:

aws ssm start-session \
  --target i-0123456789abcdef0 \
  --document-name AWS-StartInteractiveCommand \
  --parameters '{"command":["sudo su - ubuntu"]}' \
  --profile your-aws-profile \
  --region us-east-1

Method 2 — EC2 Instance Connect (browser-based)

No key pair or local SSH client needed. Works from the AWS Console in your browser. Requires port 22 open and the instance in a public subnet.

From the AWS Console

1. EC2 Console → Instances → select your Koha instance
2. Click Connect
3. Choose the EC2 Instance Connect tab
4. Set Username to ubuntu
5. Click Connect

A browser terminal opens directly.

From the AWS CLI

aws ec2-instance-connect ssh \
  --instance-id i-0123456789abcdef0 \
  --os-user ubuntu

If the instance is in a private subnet (no public IP)

You need an EC2 Instance Connect Endpoint first:

1. VPC Console (not EC2) → Endpoints → Create endpoint
2. Service category: EC2 Instance Connect Endpoint
3. Select the VPC and subnet where your instance runs
4. After the endpoint becomes Available, go back to EC2 → Connect → Instance Connect tab
5. Change Connection type to Connect using EC2 Instance Connect Endpoint
6. Select the endpoint and click Connect

EC2 Instance Connect Endpoints have an hourly charge. See the AWS Pricing Calculator for current rates.

Method 3 — SSH with a key pair

The classic approach. Requires port 22 open in the instance security group and an EC2 key pair.

Step 1 — Confirm port 22 is open

In the EC2 console, select your instance → Security tab → Security groups → check inbound rules include TCP port 22 from your IP (or 0.0.0.0/0 for open access).

Step 2 — Get your key pair file

If you created a key pair during launch, locate your .pem file. If you have lost it, you cannot recover it — you will need to create a new key pair and replace the public key on the instance, or use one of the other methods above to get in.

Step 3 — Connect

macOS / Linux:

chmod 400 ~/Downloads/your-key.pem
ssh -i ~/Downloads/your-key.pem ubuntu@<public-ip-or-elastic-ip>

Windows (PowerShell with OpenSSH installed):

ssh -i C:\Users\you\Downloads\your-key.pem ubuntu@<public-ip-or-elastic-ip>

Windows (PuTTY): Use a .ppk key file. In PuTTY → Connection → SSH → Auth → browse to your .ppk file. Set the host to <public-ip> and username to ubuntu.

Default username is ubuntu on all KohaSupport AMIs. Do not use ec2-user, admin, or root.

Creating a new key pair

If you need to create one:

1. EC2 Console → Network & Security → Key Pairs → Create key pair
2. Name it (e.g. koha-ssh-key), choose RSA, format .pem
3. Save the downloaded file — it cannot be re-downloaded
4. The key pair must be in the same AWS region as your instance

“Permission denied (publickey)”
Wrong key file, wrong username, or the key pair does not match. Confirm the username is ubuntu and the .pem matches the key pair selected at launch.

“Connection timed out” on port 22
Port 22 is not open in the security group, or the instance has no public IP. Use EC2 Instance Connect or SSM Session Manager instead, or add an inbound rule for port 22.

EC2 Instance Connect “Unable to connect”
The instance may be in a private subnet. Set up an EC2 Instance Connect Endpoint (see Method 2 above).

SSM Session Manager tab is greyed out
The instance has no IAM instance profile with AmazonSSMManagedInstanceCore. Attach one (see Method 1 above).

SSM session opens as ssm-user, not ubuntu
Run sudo su - ubuntu after connecting to switch to the application user.