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.
• Recover access with a private key stored in AWS Secrets Manager

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, always]
   users:
     - name: username
       ssh-authorized-keys:
         - PublicKeypair
   --//--

   Note: Replace username with the default username or a previously created custom username. Replace PublicKeypair with the entire public key line.

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.

Recover access with a private key stored in AWS Secrets Manager

If you backed up your private key to AWS Secrets Manager as a binary secret before you lost local access, then you can retrieve the key and reuse the original key pair. The matching public key is still in the instance's authorized_keys file from the initial launch, so the recovered private key reconnects you directly.

Complete the following steps:

1. To retrieve the private key and save it as a .pem file, run the following command:

   aws secretsmanager get-secret-value --secret-id secret-name --query SecretBinary --output text | base64 --decode > key-pair-name.pem 

   Note: Replace secret-name with the name or ARN of your secret and key-pair-name with your key pair's name.

2. To set the required permissions on the .pem file, run the following command:

   chmod 400 key-pair-name.pem

3. Use the .pem file to connect to your instance.

4. To re-register the key pair in Amazon EC2, derive the public key from the private key and import it. Run the following command to derive the public key:

   ssh-keygen -y -f key-pair-name.pem > key-pair-name.pub 

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

5. To import the public key as an Amazon EC2 key pair, run the following command:

   aws ec2 import-key-pair --key-name key-pair-name --public-key-material fileb://key-pair-name.pub 

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