Connect to an Amazon EC2 instance using EC2 Instance Connect Endpoint - Amazon Elastic Compute Cloud
PrerequisitesTroubleshoot

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.

  • (Linux instances) To use the 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.

You can connect to an instance using the Amazon EC2 console as follows.

To connect to your instance using the browser-based client

  1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

  2. In the navigation pane, choose Instances.

  3. Select the instance, choose Connect.

  4. Choose the EC2 Instance Connect tab.

  5. For Connection type, choose Connect using EC2 Instance Connect Endpoint.

  6. For EC2 Instance Connect Endpoint, choose the ID of the EC2 Instance Connect Endpoint.

  7. For Username, if the AMI that you used to launch the instance uses a user name other than ec2-user, enter the correct user name.

  8. 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.

  9. Choose Connect. This opens a terminal window for your instance.

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. You can use any other SSH client that supports a proxy mode.

Single connection

To allow only a single connection to an instance using SSH and the open-tunnel command

Use ssh and the open-tunnel AWS CLI command as follows. The -o proxy command encloses the open-tunnel command that creates the private tunnel to the instance.

ssh -i my-key-pair.pem ec2-user@i-0123456789example \
    -o ProxyCommand='aws ec2-instance-connect open-tunnel --instance-id i-0123456789example'

For:

  • -i – Specify the key pair that was used to launch the instance.

  • ec2-user@i-0123456789example – Specify the username of the AMI that was used to launch the instance, and the instance ID.

  • --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-tunnel AWS CLI command to start listening for new TCP connections, and then use ssh 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

  1. 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-port 8888

    Expected output

    Listening for connections on port 8888.

  2. 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 -p 8888

    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.

If you only know your instance ID, you can use the ec2-instance-connect AWS CLI command to connect to your instance using an SSH client. For more information about using the ec2-instance-connect command, see Connect using the AWS CLI.

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-connect CLI command, and specify the ssh command, the instance ID, and the --connection-type parameter with the eice value.

aws ec2-instance-connect ssh --instance-id i-1234567890example --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.

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

  1. 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.

  2. Run the following command to establish a private tunnel to the VPC in which the instance is located. --remote-port must be 3389 because RDP uses port 3389 by default.

    aws ec2-instance-connect open-tunnel \
    --instance-id i-0123456789example \
    --remote-port 3389 \
    --local-port any-port

  3. In your Downloads folder, find the RDP desktop file that you downloaded, and drag it onto the RDP client window.

  4. Right-click the RDP desktop file and choose Edit.

  5. In the Edit PC window, for PC name (the instance to connect to), enter localhost:local-port, where local-port uses the same value as you specified in Step 2, and then choose Save.

    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.

    The RDP client with the example "localhost:5555" in the PC name field.

  6. In the RDP client, right-click the PC (that you just configured) and choose Connect to connect to your instance.

  7. 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 connecting to your Linux instance. For troubleshooting tips for Windows instances, see Troubleshoot connecting to your 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 in the AWS CLI Command Reference.