Connect to an Amazon EC2 instance using EC2 Instance Connect Endpoint
You can use EC2 Instance Connect Endpoint to connect to an Amazon EC2 instance that supports SSH or RDP.
Prerequisites
-
You must have the required IAM permission to connect to an EC2 Instance Connect Endpoint. For more information, see Permissions to use EC2 Instance Connect Endpoint to connect to instances.
-
The EC2 Instance Connect Endpoint must be in the Available (console) or
create-complete
(AWS CLI) state. If you do not have an EC2 Instance Connect Endpoint for your VPC, you can create one. For more information, see Create an EC2 Instance Connect Endpoint. -
Your instance must have an IPv4 address (either private or public). EC2 Instance Connect Endpoint does not support connecting to instances using IPv6 addresses.
-
(Linux instances) To use the Amazon EC2 console to connect to your instance, or to use the CLI to connect and have EC2 Instance Connect handle the ephemeral key, your instance must have EC2 Instance Connect installed. For more information, see Install EC2 Instance Connect.
-
Ensure that the security group of the instance allows inbound SSH traffic from the EC2 Instance Connect Endpoint. For more information, see Target instance security group rules.
Connection options
Connect to your Linux instance using the Amazon EC2 console
You can connect to an instance using the Amazon EC2 console (a browser-based client) as follows.
To connect to your instance using the Amazon EC2 console
-
Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/
. -
In the navigation pane, choose Instances.
-
Select the instance, and then choose Connect.
-
Choose the EC2 Instance Connect tab.
-
For Connection type, choose Connect using EC2 Instance Connect Endpoint.
-
For EC2 Instance Connect Endpoint, choose the ID of the EC2 Instance Connect Endpoint.
-
For Username, if the AMI that you used to launch the instance uses a username other than
ec2-user
, enter the correct username. -
For Max tunnel duration (seconds), enter the maximum allowed duration for the SSH connection.
The duration must comply with any
maxTunnelDuration
condition specified in the IAM policy. If you don't have access to the IAM policy, contact your administrator. -
Choose Connect. This opens a terminal window for your instance.
Connect to your Linux instance using SSH
You can use SSH to connect to your Linux instance, and use the
open-tunnel
command to establish a private tunnel. You can use
open-tunnel
in single connection or multi-connection mode.
For information about using the AWS CLI to connect to your instance using SSH, see Connect using the AWS CLI.
The following examples use OpenSSH
Single connection
To allow only a single connection to an instance using
SSH and the open-tunnel
command
Use ssh
and the open-tunnel-o
proxy command encloses the open-tunnel
command
that creates the private tunnel to the instance.
ssh -i
my-key-pair
.pemec2-user
@i-0123456789example
\ -o ProxyCommand='aws ec2-instance-connect open-tunnel --instance-idi-0123456789example
'
For:
-
-i
– Specify the key pair that was used to launch the instance. -
– Specify the username of the AMI that was used to launch the instance, and the instance ID.ec2-user
@i-0123456789example
-
--instance-id
– Specify the ID of the instance to connect to. Alternatively, specify%h
, which extracts the instance ID from the user.
Multi-connection
To allow multiple connections to an instance, first run the open-tunnelssh
to create a new TCP
connection and a private tunnel to your instance.
To allow multiple connections to your instance using SSH and the
open-tunnel
command
-
Run the following command to start listening for new TCP connections on the specified port on your local machine.
aws ec2-instance-connect open-tunnel \ --instance-id
i-0123456789example
\ --local-port8888
Expected output
Listening for connections on port 8888.
-
In a new terminal window, run the following
ssh
command to create a new TCP connection and a private tunnel to your instance.ssh -i
my-key-pair
.pem ec2-user@localhost -p8888
Expected output – In the first terminal window, you'll see the following:
[1] Accepted new tcp connection, opening websocket tunnel.
You might also see the following:
[1] Closing tcp connection.
Connect to your Linux instance using the AWS CLI
If you only know your instance ID, you can use the ec2-instance-connect
Prerequisites
Install AWS CLI version 2 and configure it using your credentials. For more information, see Install or update to the latest version of the AWS CLI and Configure the AWS CLI in the AWS Command Line Interface User Guide. Alternatively, open AWS CloudShell and run AWS CLI commands in its pre-authenticated shell.
To connect to an instance using the instance ID and an EC2 Instance Connect Endpoint
If you only know the instance ID, use the ec2-instance-connectssh
command, the instance ID, and the --connection-type
parameter with
the eice
value.
aws ec2-instance-connect ssh --instance-id
i-1234567890example
--os-userec2-user
--connection-type eice
Tip
If you get an error when using this command, make sure that you're using AWS CLI
version 2. The ssh
parameter is only available in AWS CLI version 2.
For more information, see About
AWS CLI version 2 in the AWS Command Line Interface User Guide.
Connect to your Windows instance using RDP
You can use Remote Desktop Protocol (RDP) over EC2 Instance Connect Endpoint to connect to a Windows instance without a public IPv4 address or public DNS name.
To connect to your Windows instance using an RDP client
-
Complete Steps 1 – 8 in Connect to your Windows instance using RDP. After downloading the RDP desktop file at Step 8, you'll get an Unable to connect message, which is to be expected because your instance does not have a public IP address.
-
Run the following command to establish a private tunnel to the VPC in which the instance is located.
--remote-port
must be3389
because RDP uses port 3389 by default.aws ec2-instance-connect open-tunnel \ --instance-id
i-0123456789example
\ --remote-port 3389 \ --local-portany-port
-
In your Downloads folder, find the RDP desktop file that you downloaded, and drag it onto the RDP client window.
-
Right-click the RDP desktop file and choose Edit.
-
In the Edit PC window, for PC name (the instance to connect to), enter
localhost:
, wherelocal-port
uses the same value as you specified in Step 2, and then choose Save.local-port
Note that the following screenshot of the Edit PC window is from Microsoft Remote Desktop on a Mac. If you are using a Windows client, the window might be different.
-
In the RDP client, right-click the PC (that you just configured) and choose Connect to connect to your instance.
-
At the prompt, enter the decrypted password for the administrator account.
Troubleshoot
Use the following information to help diagnose and fix issues that you might encounter when using EC2 Instance Connect Endpoint to connect an instance.
Can't connect to your instance
The following are common reasons why you might not be able to connect to your instance.
-
Security groups – Check the security groups assigned to the EC2 Instance Connect Endpoint and your instance. For more information about the required security group rules, see Security groups for EC2 Instance Connect Endpoint.
-
Instance state – Verify that your instance is in the
running
state. -
Key pair – If the command you're using to connect requires a private key, verify that your instance has a public key and that you have the corresponding private key.
-
IAM permissions – Verify that you have the required IAM permissions. For more information, see Grant permissions to use EC2 Instance Connect Endpoint.
For more troubleshooting tips for Linux instances, see Troubleshoot issues connecting to your Amazon EC2 Linux instance. For troubleshooting tips for Windows instances, see Troubleshoot issues connecting to your Amazon EC2 Windows instance.
ErrorCode: AccessDeniedException
If you receive an AccessDeniedException
error, and the
maxTunnelDuration
condition is specified in the IAM policy, be
sure to specify the --max-tunnel-duration
parameter when connecting
to an instance. For more information about this parameter, see open-tunnel