Connect using EC2 Instance Connect - Amazon Elastic Compute Cloud
LimitationsPrerequisitesConnect using EC2 Instance ConnectTroubleshoot
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 using EC2 Instance Connect

The following instructions explain how to connect to your Linux instance using EC2 Instance Connect.

Limitations

  • Supported Linux distributions:

    • Amazon Linux 2 (any version)

    • Ubuntu 16.04 or later

  • Supported in all Amazon Web Services Regions except Africa (Cape Town), Asia Pacific (Hong Kong), Asia Pacific (Jakarta), Asia Pacific (Osaka), China (Beijing), China (Ningxia), Europe (Milan), Middle East (Bahrain), and Middle East (UAE).

  • To connect using the Amazon EC2 console, the instance must have a public IPv4 address.

  • If the instance does not have a public IP address, you can connect to the instance over a private network using an SSH client or the EC2 Instance Connect CLI. For example, you can connect from within the same VPC or through a VPN connection, transit gateway, or Amazon Direct Connect.

  • EC2 Instance Connect does not support connecting using an IPv6 address.

Prerequisites

  • Install EC2 Instance Connect on your instance.

    For more information, see Set up EC2 Instance Connect.

  • (Optional) Install an SSH client on your local computer.

    There is no need to install an SSH client if users only use the Amazon EC2 console or the EC2 Instance Connect CLI to connect to an instance. Your local computer most likely has an SSH client installed by default. You can check for an SSH client by typing ssh at the command line. If your local computer doesn't recognize the command, you can install an SSH client. For information about installing an SSH client on Linux or macOS X, see http://www.openssh.com. For information about installing an SSH client on Windows 10, see OpenSSH in Windows.

  • (Optional) Install the EC2 Instance Connect CLI on your local computer.

    There is no need to install the EC2 Instance Connect CLI if users only use the Amazon EC2 console or an SSH client to connect to an instance. For more information, see Task 3: (Optional) Install the EC2 Instance Connect CLI on your computer. This connection method works for instances with public IP addresses.

Connect using EC2 Instance Connect

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

  2. In the navigation pane, choose Instances.

  3. Select the instance and choose Connect.

  4. Choose EC2 Instance Connect.

  5. Verify the user name and choose Connect to open a terminal window.

Connect using the EC2 Instance Connect CLI

You can connect to an instance using the EC2 Instance Connect CLI by providing only the instance ID, while the Instance Connect CLI performs the following three actions in one call: it generates a one-time-use SSH public key, pushes the key to the instance where it remains for 60 seconds, and connects the user to the instance. You can use basic SSH/SFTP commands with the Instance Connect CLI.

This connection method works for instances with public and private IP addresses. When connecting to an instance that only has private IP addresses, the local computer from which you are initiating the session must have connectivity to the EC2 Instance Connect service endpoint (to push your SSH public key to the instance) as well as network connectivity to the instance's private IP address. The EC2 Instance Connect service endpoint is reachable over the internet or over an Amazon Direct Connect public virtual interface. To connect to the instance's private IP address, you can leverage services such as Amazon Direct Connect, Amazon Site-to-Site VPN, or VPC peering.

Note

-i is not supported when using mssh. When using the mssh command to connect to your instance, you do not need to specify any kind of identity file because Instance Connect manages the key pair.

Amazon Linux 2
To connect to an instance using the EC2 Instance Connect CLI

Use the mssh command with the instance ID as follows. You do not need to specify the user name for the AMI.

$ mssh i-001234a4bf70dec41EXAMPLE
Ubuntu
To connect to an instance using the EC2 Instance Connect CLI

Use the mssh command with the instance ID and the default user name for the Ubuntu AMI as follows. You must specify the user name for the AMI or you get the following error: Authentication failed.

$ mssh ubuntu@i-001234a4bf70dec41EXAMPLE

Connect using your own key and SSH client

You can use your own SSH key and connect to your instance from the SSH client of your choice while using the EC2 Instance Connect API. This enables you to benefit from the Instance Connect capability to push a public key to the instance. This connection method works for instances with public and private IP addresses.

Requirements

  • Requirements for key pairs

  • When connecting to an instance that only has private IP addresses, the local computer from which you are initiating the SSH session must have connectivity to the EC2 Instance Connect service endpoint (to push your SSH public key to the instance) as well as network connectivity to the instance's private IP address to establish the SSH session. The EC2 Instance Connect service endpoint is reachable over the internet or over an Amazon Direct Connect public virtual interface. To connect to the instance's private IP address, you can leverage services such as Amazon Direct Connect, Amazon Site-to-Site VPN, or VPC peering.

To connect to your instance using your own key and any SSH client
  1. (Optional) Generate new SSH private and public keys

    You can generate new SSH private and public keys, my_key and my_key.pub, using the following command:

    $ ssh-keygen -t rsa -f my_key
  2. Push your SSH public key to the instance

    Use the send-ssh-public-key command to push your SSH public key to the instance. If you launched your instance using Amazon Linux 2, the default user name for the AMI is ec2-user. If you launched your instance using Ubuntu, the default user name for the AMI is ubuntu.

    The following example pushes the public key to the specified instance in the specified Availability Zone, to authenticate ec2-user.

    $ aws ec2-instance-connect send-ssh-public-key \
    --region us-west-2 \
    --availability-zone us-west-2b \
    --instance-id i-001234a4bf70dec41EXAMPLE \
    --instance-os-user ec2-user \
    --ssh-public-key file://my_key.pub
  3. Connect to the instance using your private key

    Use the ssh command to connect to the instance using the private key before the public key is removed from the instance metadata (you have 60 seconds before it is removed). Specify the private key that corresponds to the public key, the default user name for the AMI that you used to launch your instance, and the instance's public DNS name (if connecting over a private network, specify the private DNS name or IP address). Add the IdentitiesOnly=yes option to ensure that only the files in the ssh config and the specified key are used for the connection. 

    $ ssh -o "IdentitiesOnly=yes" -i my_key ec2-user@ec2-198-51-100-1.compute-1.amazonaws.com

Troubleshoot

If you receive an error while attempting to connect to your instance, see the following: