Connect to a Linux instance using EC2 Instance Connect Endpoint - Amazon Elastic Compute Cloud
PrerequisitesConnect using the consoleConnect to your Linux instance using SSHConnect using the Amazon CLITroubleshoot
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Connect to a Linux instance using EC2 Instance Connect Endpoint

You can use EC2 Instance Connect Endpoint to connect to a Linux instance that supports SSH.

For information about how to connect to a Windows instance, see Connect to a Windows instance using EC2 Instance Connect Endpoint in the Amazon EC2 User Guide for Windows Instances.

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 (Amazon 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.

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

Connect to your Linux instance using the Amazon EC2 console

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.amazonaws.cn/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.

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 Amazon CLI to connect to your instance using SSH, see Connect using the Amazon 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 Amazon 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 Amazon 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.

Connect to your Linux instance using the Amazon CLI

If you only know your instance ID, you can use the ec2-instance-connect Amazon 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 Amazon CLI.

Prerequisites

Install Amazon CLI version 2 and configure it using your credentials. For more information, see Install or update to the latest version of the Amazon CLI and Configure the Amazon CLI in the Amazon Command Line Interface User Guide. Alternatively, open Amazon CloudShell and run Amazon 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 Amazon CLI version 2. The ssh parameter is only available in Amazon CLI version 2. For more information, see About Amazon CLI version 2 in the Amazon Command Line Interface User Guide.

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, see Troubleshoot connecting to your 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 Amazon CLI Command Reference.