How do I connect to my Amazon EC2 instance if I lose my SSH key pair after the initial instance launch?

Short description

To connect to an EC2 instance when you lose your SSH key pair, use one of the following methods:

• Enter user data to create a new key pair.
• For instances that are managed nodes, use AWS Systems Manager to recover your key pair.
• For instances that run Amazon Linux 2 (AL2) version 2.0.20190618 and later or Amazon Linux 2023 (AL2023), use EC2 Instance Connect.
• If you can reach your instance and you have access to the EC2 Serial Console, then use the serial console.
  Note: This method doesn't require you to stop and start your instance.
• Create a rescue instance to create a new public key.

Important: Before you stop and start your instance, take the following actions:

• Create a backup of your Amazon Elastic Block Store (Amazon EBS) volume.
  Note: If your instance is instance store-backed or has instance store volumes that contains data, then Amazon EC2 deletes the data when you stop the instance.
• Set the instance shutdown behavior to Stop to make sure that the instances don't terminate when you stop them.

Note: When you stop and start an instance, the instance's public IP address changes. It's a best practice to use an Elastic IP address to route external traffic to your instance instead of a public IP address.

Resolution

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

Enter user data script

Important: Don't store sensitive data in user data scripts. Instead, use secure methods such as AWS Secrets Manager.

If your instance doesn't have access to cloud-init or you experience cloud-init issues, then proceed to Use a rescue instance.

Create the new key pair

Complete the following steps:

1. Create a new key pair.
2. If you create the private key on the Amazon EC2 console, then retrieve the public key for the key pair.
3. Open the Amazon EC2 console.
4. Stop your instance.
5. Choose Actions, and then choose Instance settings.
6. Choose Edit user data, and then enter the following script:

   Content-Type: multipart/mixed; boundary="//"
   MIME-Version: 1.0
   
   --//
   Content-Type: text/cloud-config; charset="us-ascii"
   MIME-Version: 1.0
   Content-Transfer-Encoding: 7bit
   Content-Disposition: attachment; filename="cloud-config.txt"
   
   #cloud-config
   cloud_final_modules:
   - [users-groups, once]
   users:
   - name: username
   ssh-authorized-keys:
   - PublicKeypair

   Note: Replace username with the default username or a previously created custom username. Replace PublicKeypair with the public key. When you enter the entire public key, start with ssh-rsa.
7. Choose Save.
8. Start your instance.

Confirm that the cloud-init phase completes

In the instance console output, check for the following factors to make sure that the cloud-init phase is complete:

• There are no error messages.
• All cloud-init directives list as Executed.
• You see a Finished message for cloud-init similar to the following example: "Finished [0;1;39mCloud-init: Final Stage[0m Cloud-init v. A.B.C finished at ..".

Remove the commands from the instance's User data

Complete the following steps:

1. Stop your instance.
2. Choose Actions, and then choose Instance settings.
3. Choose Edit user data, and then clear all content from the field.
4. Choose Save.
5. Start your instance.

Use Systems Manager

To recover an instance that's a managed node in Systems Manager, use the AWSSupport-ResetAccess runbook to recover the key pair. AWSSupport-ResetAccess uses EC2Rescue to automatically generate and add a new SSH key pair on the instance.

Systems Manager encrypts and saves the new SSH private key for your instance in Parameter Store, a capability of AWS Systems Manager as /ec2rl/openssh/instance_id/key.

To get the private SSH key from Parameter Store, run the get-parameters AWS CLI command:

aws ssm get-parameters --names "/ec2rl/openssh/instance_id/key" --with-decryption --output json --query  "Parameters[0].Value" | sed 's:\\n:\n:g; s:^"::; s:"$::' >  key-pair-name

Note: Replace instance_id with your instance ID and key-pair-name with your key pair's name.

Then, create a new .pem file with the parameter's value as the content. Use the .pem file to reconnect to your unreachable instance.

To convert the private key to a .pem file, run the following command:

ssh-keygen -f key-pair-name -e -m pem > key-pair-name.pem

Note: Replace key-pair-name with your key pair's name.

The automation runbook creates a password-activated backup Amazon Machine Image (AMI). Amazon EC2 doesn't automatically delete the new AMI, so it remains in your AWS account.

To locate the AMI, complete the following steps:

1. Open the Amazon EC2 console.
2. Choose AMIs.
3. Enter the Automation ID in the search field.

Use EC2 Instance Connect

To connect to an Amazon Linux instance, see Connect to a Linux instance using EC2 Instance Connect.

Use the EC2 Serial Console

If you can access the EC2 Serial Console for Linux, then use the console to troubleshoot supported Nitro-based instance types. For more information see, Configure access to the EC2 Serial Console.

Use a rescue instance

Complete the following steps:

1. Stop the instance.

2. Detach the root EBS volume from the instance.

3. Launch a rescue instance in the same Availability Zone as the original instance.

4. Attach the original instance's root volume to the rescue instance as a secondary volume.

5. Start the rescue instance.

6. To get the root volume device name, run the following command:

   sudo lsblk -f 

   Example output:

   NAME FSTYPE LABEL UUID MOUNTPOINT 
   xvda └─xvda1 xfs 1234abcd-56ef-78gh-90ij-1234klmnopqr /
    xvdf └─xvdf1 xfs abcd1234-ef56-gh78-ij90-qr1234klmnop 

7. To mount the attached volume to the rescue instance, run the following commands:

   sudo mkdir /mnt/target
   sudo mount /dev/xvdf1 /mnt/target 

   Note: Replace /dev/xvdf1 with the original instance's root volume device name.

8. To create a new public key, run the following command:

   sudo mkdir -p /mnt/target/home/USER/.ssh 
   echo "your_new_public_key" | sudo tee -a /mnt/target/home/USER/.ssh/authorized_keys

   Note: Replace USER with the original instance's username and your_new_public_key with your public key. The public key name starts with ssh-rsa.

9. To configure access to the key in the instance, run the following command:

   OS_USER=os-user
   sudo chown -R $OS_USER:$OS_USER /mnt/target/home/$OS_USER/.ssh 
   sudo chmod 700 /mnt/target/home/$OS_USER/.ssh 
   sudo chmod 600 /mnt/target/home/$OS_USER/.ssh/authorized_keys

   Note: Replace os-user with the username associated with the AMI that you used to launch your instance.

10. To unmount the volume, run the following command:

    sudo umount /mnt/target

11. Detach the volume from the rescue instance, and reattach it to the original instance.

12. Start the original instance.