Connect using EC2 Instance Connect Endpoint to a Linux instance - Amazon Elastic Compute Cloud

Connect using EC2 Instance Connect Endpoint to a Linux instance

EC2 Instance Connect Endpoint allows you to connect to an instance without requiring the instance to have a public IPv4 address. You can connect to any instances that support TCP.

To connect to an instance, specify the instance ID. You can optionally provide the EC2 Instance Connect Endpoint.

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

Limitations

  • Only ports 22 and 3389 are supported.

  • EC2 Instance Connect Endpoint doesn't support connections to an instance using IPv6 addresses.

  • Each EC2 Instance Connect Endpoint can support up to 20 concurrent connections.

  • EC2 Instance Connect Endpoint is intended specifically for management traffic use cases and not for high volume data transfers. High volume data
 transfers are throttled.

  • Maximum duration for an established TCP connection: 1 hour (3,600 seconds). You can specify the maximum allowed duration in an IAM policy, which can be 3,600 seconds or less. For more information, see Allow users to use EC2 Instance Connect Endpoint to connect to instances.

  • When client IP preservation is enabled, the instance to connect to must be in the same VPC as the EC2 Instance Connect Endpoint.

  • Client IP preservation is not supported when traffic is routed through an AWS Transit Gateway.

  • The following instance types do not support client IP preservation: C1, CG1, CG2, G1, HI1, M1, M2, M3, and T1. If you are using these instance types, set the preserveClientIp parameter to false, otherwise attempting to connect to these instance types using EC2 Instance Connect Endpoint will fail. For more information about the preserveClientIp parameter, see step 3.d in the Create an EC2 Instance Connect Endpoint console procedure.

Prerequisites

Connect to your Linux instance using the Amazon EC2 console

You can connect to an instance using the Amazon EC2 console by selecting the instance from the console and choosing to connect using EC2 Instance Connect, which handles the permissions and provides a successful connection.

To connect to your instance using the browser-based client from the Amazon EC2 console
  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, and then do the following:

    
                            Dialog box for connecting to an instance using an
                                EC2 Instance Connect Endpoint.
    1. Choose the EC2 Instance Connect tab.

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

    3. For EC2 Instance Connect Endpoint, choose the EC2 Instance Connect Endpoint in the instance’s VPC. If there is no endpoint to choose, see Create an EC2 Instance Connect Endpoint.

    4. For Username, verify the username.

    5. For Max tunnel duration (seconds), enter the maximum allowed duration for the SSH connection.

      The duration must comply with the maxTunnelDuration condition specified in the IAM policy. If you don't have access to the IAM policy, ask your administrator to verify it. If maxTunnelDuration is not specified in the IAM policy, enter the default, which is 3600 seconds (1 hour).

    6. Choose Connect to open a terminal window.

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

Connect to your Linux instance using the AWS CLI

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.

Important

Before you connect with this method, ensure that you have configured the AWS CLI, including the credentials that it uses, and that you're using the latest version of the AWS CLI. For more information, see Installing or updating the latest version of the AWS CLI and Configuring the AWS CLI in the AWS Command Line Interface User Guide.

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.

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 IAM 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 AWS CLI Command Reference.