/path/my-key-pair.pem ~/WSL-path/my-key-pair.pem
```
For information about uninstalling Windows Subsystem for Linux, see [How do I uninstall a WSL Distribution?](https://learn.microsoft.com/en-us/windows/wsl/faq#how-do-i-uninstall-a-wsl-distribution-).
## Connect to your Linux instance using an SSH client
Use the following procedure to connect to your Linux instance using an SSH client.
**To connect to your instance using an SSH client**
1. Open a terminal window on your computer.
1. Use the **ssh** command to connect to the instance. You need the details about your instance that you gathered as part of the prerequisites. For example, you need the location of the private key (`.pem` file), the username, and the public DNS name or IPv6 address. The following are example commands.
+ (Public DNS) To use the public DNS name, enter the following command.
```
ssh -i /path/key-pair-name.pem instance-user-name@instance-public-dns-name
```
+ (IPv6) Alternatively, if your instance has an IPv6 address, enter the following command to use the IPv6 address.
```
ssh -i /path/key-pair-name.pem instance-user-name@2001:db8::1234:5678:1.2.3.4
```
The following is an example response.
```
The authenticity of host 'ec2-198-51-100-1.compute-1.amazonaws.com (198-51-100-1)' can't be established.
ECDSA key fingerprint is l4UB/neBad9tvkgJf1QZWxheQmR59WgrgzEimCG6kZY.
Are you sure you want to continue connecting (yes/no)?
```
1. (Optional) Verify that the fingerprint in the security alert matches the fingerprint. If these fingerprints don't match, someone might be attempting a man-in-the-middle attack. If they match, continue to the next step. For more information, see [Get the instance fingerprint](connection-prereqs-general.md#connection-prereqs-fingerprint).
1. Enter **yes**.
You see a response like the following:
```
Warning: Permanently added 'ec2-198-51-100-1.compute-1.amazonaws.com' (ECDSA) to the list of known hosts.
```
# Connect to your Linux instance using PuTTY
Connect using PuTTY
You can connect to your Linux instance using PuTTY, a free SSH client for Windows.
If you're running Windows Server 2019 or later, we recommend that you use OpenSSH, an open source connectivity tool for remote login using the SSH protocol.
**Note**
If you receive an error while attempting to connect to your instance, make sure that your instance meets all of the [SSH connection prerequisites](connect-linux-inst-ssh.md#ssh-prereqs-linux-from-linux-macos). If it meets all of the prerequisites, and you're still not able to connect to your Linux instance, see [Troubleshoot issues connecting to your Amazon EC2 Linux instance](TroubleshootingInstancesConnecting.md).
**Topics**
+ [
## Prerequisites
](#putty-prereqs)
+ [Convert your private key using PuTTYgen](#putty-private-key)
+ [
## Connect to your Linux instance
](#putty-ssh)
## Prerequisites
Before you connect to your Linux instance using PuTTY, complete the following tasks.
**Complete the general prerequisites.**
+ Check that your instance has passed its status checks. It can take a few minutes for an instance to be ready to accept connection requests. For more information, see [View status checks](viewing_status.md).
+ [Get the required instance details](connection-prereqs-general.md#connection-prereqs-get-info-about-instance).
+ [Locate the private key and set permissions](connection-prereqs-general.md#connection-prereqs-private-key).
+ [(Optional) Get the instance fingerprint](connection-prereqs-general.md#connection-prereqs-fingerprint).
**Allow inbound SSH traffic from your IP address.**
Ensure that the security group associated with your instance allows incoming SSH traffic from your IP address. For more information, see [Rules to connect to instances from your computer](security-group-rules-reference.md#sg-rules-local-access).
**Install PuTTY on your local computer (if needed).**
Download and install PuTTY from the [PuTTY download page](https://www.chiark.greenend.org.uk/~sgtatham/putty/). If you already have an earlier version of PuTTY installed, we recommend that you download the latest version. Be sure to install the entire suite.
**Convert your private key to PPK format using PuTTYgen.**
You must specify the private key for the key pair that you specified when you launched the instance. If you created the private key in .pem format, you must convert it to a PPK file for use with PuTTY. Locate the private key (.pem file), and then follow the steps in [Convert your private key using PuTTYgen](#putty-private-key).
## (Optional) Convert your private key using PuTTYgen
Convert your private key using PuTTYgen
PuTTY does not natively support the PEM format for SSH keys. PuTTY provides a tool named PuTTYgen, which converts PEM keys to the required PPK format for PuTTY. If you created the key using PEM format instead of PPK format, you must convert your private key (.pem file) into this format (.ppk file) for use with PuTTY.
**To convert your private key from PEM to PPK format**
1. From the **Start** menu, choose **All Programs**, **PuTTY**, **PuTTYgen**.
1. Under **Type of key to generate**, choose **RSA**. If your version of PuTTYgen does not include this option, choose **SSH-2 RSA**.
![\[RSA key in PuTTYgen.\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/puttygen-key-type.png)
1. Choose **Load**. By default, PuTTYgen displays only files with the extension `.ppk`. To locate your `.pem` file, choose the option to display files of all types.
![\[Select all file types.\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/puttygen-load-key.png)
1. Select your `.pem` file for the key pair that you specified when you launched your instance and choose **Open**. PuTTYgen displays a notice that the `.pem` file was successfully imported. Choose **OK**.
1. To save the key in the format that PuTTY can use, choose **Save private key**. PuTTYgen displays a warning about saving the key without a passphrase. Choose **Yes**.
**Note**
A passphrase on a private key is an extra layer of protection. Even if your private key is discovered, it can't be used without the passphrase. The downside to using a passphrase is that it makes automation harder because human intervention is needed to log on to an instance, or to copy files to an instance.
1. Specify the same name for the key that you used for the key pair (for example, `key-pair-name`) and choose **Save**. PuTTY automatically adds the `.ppk` file extension.
Your private key is now in the correct format for use with PuTTY. You can now connect to your instance using PuTTY's SSH client.
## Connect to your Linux instance
Use the following procedure to connect to your Linux instance using PuTTY. You need the `.ppk` file that you created for your private key. For more information, see [(Optional) Convert your private key using PuTTYgen](#putty-private-key) in the preceding section. If you receive an error while attempting to connect to your instance, see [Troubleshoot issues connecting to your Amazon EC2 Linux instance](TroubleshootingInstancesConnecting.md).
**Last tested version** – PuTTY .78
**To connect to your instance using PuTTY**
1. Start PuTTY (from the **Start** menu, search for **PuTTY** and then choose **Open**).
1. In the **Category** pane, choose **Session** and complete the following fields:
1. In the **Host Name** box, do one of the following:
+ (Public DNS) To connect using your instance's public DNS name, enter *instance-user-name*@*instance-public-dns-name*.
+ (IPv6) Alternatively, if your instance has an IPv6 address, to connect using your instance's IPv6 address, enter *instance-user-name*@*2001:db8::1234:5678:1.2.3.4*.
For information about how to get the username for your instance, and the public DNS name or IPv6 address of your instance, see [Get the required instance details](connection-prereqs-general.md#connection-prereqs-get-info-about-instance).
1. Ensure that the **Port** value is 22.
1. Under **Connection type**, select **SSH**.
![\[PuTTY configuration - Session.\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/putty-session-config.png)
1. (Optional) You can configure PuTTY to automatically send 'keepalive' data at regular intervals to keep the session active. This is useful to avoid disconnecting from your instance due to session inactivity. In the **Category** pane, choose **Connection**, and then enter the required interval in **Seconds between keepalives**. For example, if your session disconnects after 10 minutes of inactivity, enter 180 to configure PuTTY to send keepalive data every 3 minutes.
1. In the **Category** pane, expand **Connection**, **SSH**, and **Auth**. Choose **Credentials**.
1. Next to **Private key file for authentication**, choose **Browse**. In the **Select private key file** dialog box, select the `.ppk` file that you generated for your key pair. You can either double-click the file or choose **Open** in the **Select private key file** dialog box.
1. (Optional) If you plan to connect to this instance again after this session, you can save the session information for future use. In the **Category** pane, choose **Session**. Enter a name for the session in **Saved Sessions**, and then choose **Save**.
1. To connect to the instance, choose **Open**.
1. If this is the first time you have connected to this instance, PuTTY displays a security alert dialog box that asks whether you trust the host to which you are connecting.
1. (Optional) Verify that the fingerprint in the security alert dialog box matches the fingerprint that you previously obtained in [(Optional) Get the instance fingerprint](connection-prereqs-general.md#connection-prereqs-fingerprint). If these fingerprints don't match, someone might be attempting a "man-in-the-middle" attack. If they match, continue to the next step.
1. Choose **Accept**. A window opens and you are connected to your instance.
**Note**
If you specified a passphrase when you converted your private key to the PuTTY format, you must provide that passphrase when you log in to the instance.
If you receive an error while attempting to connect to your instance, see [Troubleshoot issues connecting to your Amazon EC2 Linux instance](TroubleshootingInstancesConnecting.md).
# Transfer files to a Linux instance using SCP
Transfer files using SCP
One way to transfer files between your local computer and a Linux instance is to use the secure copy protocol (SCP). SCP is a good option for simple operations, such as as one-time file copies. SCP secures files transfers using the same .pem file that you use to connect to an instance using SSH. If you need to keep files synchronized, or if the files are large, **rsync** is faster and more efficient than SCP. For security, use **rsync** over SSH, as **rsync** transfers data using plain text by default.
Before you connect to your Linux instance using SCP, complete the following tasks:
+ **Complete the general prerequisites.**
+ Check that your instance has passed its status checks. It can take a few minutes for an instance to be ready to accept connection requests. For more information, see [View status checks](viewing_status.md).
+ [Get the required instance details](connection-prereqs-general.md#connection-prereqs-get-info-about-instance).
+ [Locate the private key and set permissions](connection-prereqs-general.md#connection-prereqs-private-key).
+ [(Optional) Get the instance fingerprint](connection-prereqs-general.md#connection-prereqs-fingerprint).
+ **Allow inbound SSH traffic from your IP address.**
Ensure that the security group associated with your instance allows incoming SSH traffic from your IP address. For more information, see [Rules to connect to instances from your computer](security-group-rules-reference.md#sg-rules-local-access).
+ **Install an SCP client.**
Most Linux, Unix, and Apple computers include an SCP client by default. If yours doesn't, the OpenSSH project provides a free implementation of the full suite of SSH tools, including an SCP client. For more information, see [https://www.openssh.com](https://www.openssh.com).
The following procedure steps you through using SCP to transfer a file using the instance's public DNS name, or the IPv6 address if your instance has one.
**To use SCP to transfer files between your computer and your instance**
1. Determine the location of the source file on your computer and the destination path on the instance. In the following examples, the name of the private key file is `key-pair-name.pem`, the file to transfer is `my-file.txt`, the username for the instance is ec2-user, the public DNS name of the instance is `instance-public-dns-name`, and the IPv6 address of the instance is `2001:db8::1234:5678:1.2.3.4`.
+ (Public DNS) To transfer a file to the destination on the instance, enter the following command from your computer.
```
scp -i /path/key-pair-name.pem /path/my-file.txt ec2-user@instance-public-dns-name:path/
```
+ (IPv6) To transfer a file to the destination on the instance if the instance has an IPv6 address, enter the following command from your computer. The IPv6 address must be enclosed in square brackets (`[ ]`), which must be escaped (`\`).
```
scp -i /path/key-pair-name.pem /path/my-file.txt ec2-user@\[2001:db8::1234:5678:1.2.3.4\]:path/
```
1. If you haven't already connected to the instance using SSH, you see a response like the following:
```
The authenticity of host 'ec2-198-51-100-1.compute-1.amazonaws.com (10.254.142.33)'
can't be established.
RSA key fingerprint is 1f:51:ae:28:bf:89:e9:d8:1f:25:5d:37:2d:7d:b8:ca:9f:f5:f1:6f.
Are you sure you want to continue connecting (yes/no)?
```
(Optional) You can optionally verify that the fingerprint in the security alert matches the instance fingerprint. For more information, see [(Optional) Get the instance fingerprint](connection-prereqs-general.md#connection-prereqs-fingerprint).
Enter **yes**.
1. If the transfer is successful, the response is similar to the following:
```
Warning: Permanently added 'ec2-198-51-100-1.compute-1.amazonaws.com' (RSA)
to the list of known hosts.
my-file.txt 100% 480 24.4KB/s 00:00
```
1. To transfer a file in the other direction (from your Amazon EC2 instance to your computer), reverse the order of the host parameters. For example, you can transfer `my-file.txt` from your EC2 instance to the a destination on your local computer as `my-file2.txt`, as shown in the following examples.
+ (Public DNS) To transfer a file to a destination on your computer, enter the following command from your computer.
```
scp -i /path/key-pair-name.pem ec2-user@instance-public-dns-name:path/my-file.txt path/my-file2.txt
```
+ (IPv6) To transfer a file to a destination on your computer if the instance has an IPv6 address, enter the following command from your computer. The IPv6 address must be enclosed in square brackets (`[ ]`), which must be escaped (`\`).
```
scp -i /path/key-pair-name.pem ec2-user@\[2001:db8::1234:5678:1.2.3.4\]:path/my-file.txt path/my-file2.txt
```
# Manage system users on your Amazon EC2 Linux instance
Manage Linux system users
Each Linux instance launches with a default Linux system user. You can add users to your instance and delete users.
For the default user, the [default username](#ami-default-user-names) is determined by the AMI that was specified when you launched the instance.
**Note**
By default, password authentication and root login are disabled, and sudo is enabled. To log in to your instance, you must use a key pair. For more information about logging in, see [Connect to your Linux instance using SSH](connect-to-linux-instance.md).
You can allow password authentication and root login for your instance. For more information, see the documentation for your operating system.
**Note**
Linux system users should not be confused with IAM users. For more information, see [IAM users](https://docs.aws.amazon.com/IAM/latest/UserGuide/id.html#id_iam-users) in the *IAM User Guide*.
**Topics**
+ [
## Default usernames
](#ami-default-user-names)
+ [
## Considerations
](#add-user-best-practice)
+ [
## Create a user
](#create-user-account)
+ [
## Remove a user
](#delete-user-account)
## Default usernames
The default username for your EC2 instance is determined by the AMI that was specified when you launched the instance.
The default usernames are:
+ For an Amazon Linux AMI, the username is `ec2-user`.
+ For a CentOS AMI, the username is `centos` or `ec2-user`.
+ For a Debian AMI, the username is `admin`.
+ For a Fedora AMI, the username is `fedora` or `ec2-user`.
+ For a FreeBSD AMI, the username is `ec2-user`.
+ For a RHEL AMI, the username is `ec2-user` or `root`.
+ For a SUSE AMI, the username is `ec2-user` or `root`.
+ For an Ubuntu AMI, the username is `ubuntu`.
+ For an Oracle AMI, the username is `ec2-user`.
+ For a Bitnami AMI, the username is `bitnami`.
**Note**
To find the default username for other Linux distributions, check with the AMI provider.
## Considerations
Using the default user is adequate for many applications. However, you may choose to add users so that individuals can have their own files and workspaces. Furthermore, creating users for new users is much more secure than granting multiple (possibly inexperienced) users access to the default user, because the default user can cause a lot of damage to a system when used improperly. For more information, see [Tips for Securing Your EC2 Instance](https://aws.amazon.com/articles/tips-for-securing-your-ec2-instance/).
To enable users SSH access to your EC2 instance using a Linux system user, you must share the SSH key with the user. Alternatively, you can use EC2 Instance Connect to provide access to users without the need to share and manage SSH keys. For more information, see [Connect to your Linux instance using a public IP address and EC2 Instance Connect](connect-linux-inst-eic.md).
## Create a user
First create the user, and then add the SSH public key that allows the user to connect to and log into the instance.
**Important**
In Step 1 of this procedure, you create a new key pair. Because a key pair functions like a password, it's crucial to handle it securely. If you create a key pair for a user, you must ensure that the private key is sent to them securely. Alternatively, the user can complete Steps 1 and 2 by creating their own key pair, keeping the private key secure on their machine, and then sending you the public key to complete the procedure from Step 3.
**To create a user**
1. [Create a new key pair](create-key-pairs.md#having-ec2-create-your-key-pair). You must provide the `.pem` file to the user for whom you are creating the user. They must use this file to connect to the instance.
1. Retrieve the public key from the key pair that you created in the previous step.
```
$ ssh-keygen -y -f /path_to_key_pair/key-pair-name.pem
```
The command returns the public key, as shown in the following example.
```
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQClKsfkNkuSevGj3eYhCe53pcjqP3maAhDFcvBS7O6Vhz2ItxCih+PnDSUaw+WNQn/mZphTk/a/gU8jEzoOWbkM4yxyb/wB96xbiFveSFJuOp/d6RJhJOI0iBXrlsLnBItntckiJ7FbtxJMXLvvwJryDUilBMTjYtwB+QhYXUMOzce5Pjz5/i8SeJtjnV3iAoG/cQk+0FzZqaeJAAHco+CY/5WrUBkrHmFJr6HcXkvJdWPkYQS3xqC0+FmUZofz221CBt5IMucxXPkX4rWi+z7wB3RbBQoQzd8v7yeb7OzlPnWOyN0qFU0XA246RA8QFYiCNYwI3f05p6KLxEXAMPLE
```
1. Connect to the instance.
1. Use the **adduser** command to create the user and add it to the system (with an entry in the `/etc/passwd` file). The command also creates a group and a home directory for the user. In this example, the user is named `newuser`.
+ AL2023 and Amazon Linux 2
With AL2023 and Amazon Linux 2, the user is created with password authentication disabled by default.
```
[ec2-user ~]$ sudo adduser newuser
```
+ Ubuntu
Include the `--disabled-password` parameter to create the user with password authentication disabled.
```
[ubuntu ~]$ sudo adduser newuser --disabled-password
```
1. Switch to the new user so that the directory and file that you create will have the proper ownership.
```
[ec2-user ~]$ sudo su - newuser
```
The prompt changes from `ec2-user` to `newuser` to indicate that you have switched the shell session to the new user.
1. Add the SSH public key to the user. First create a directory in the user's home directory for the SSH key file, then create the key file, and finally paste the public key into the key file, as described in the following sub-steps.
1. Create a `.ssh` directory in the `newuser` home directory and change its file permissions to `700` (only the owner can read, write, or open the directory).
```
[newuser ~]$ mkdir .ssh
```
```
[newuser ~]$ chmod 700 .ssh
```
**Important**
Without these exact file permissions, the user will not be able to log in.
1. Create a file named `authorized_keys` in the `.ssh` directory and change its file permissions to `600` (only the owner can read or write to the file).
```
[newuser ~]$ touch .ssh/authorized_keys
```
```
[newuser ~]$ chmod 600 .ssh/authorized_keys
```
**Important**
Without these exact file permissions, the user will not be able to log in.
1. Open the `authorized_keys` file using your favorite text editor (such as **vim** or **nano**).
```
[newuser ~]$ nano .ssh/authorized_keys
```
Paste the public key that you retrieved in **Step 2** into the file and save the changes.
**Important**
Ensure that you paste the public key in one continuous line. The public key must not be split over multiple lines.
The user should now be able to log into the `newuser` user on your instance, using the private key that corresponds to the public key that you added to the `authorized_keys` file. For more information about the different methods of connecting to a Linux instance, see [Connect to your Linux instance using SSH](connect-to-linux-instance.md).
## Remove a user
If a user is no longer needed, you can remove that user so that it can no longer be used.
Use the **userdel** command to remove the user from the system. When you specify the `-r` parameter, the user's home directory and mail spool are deleted. To keep the user's home directory and mail spool, omit the `-r` parameter.
```
[ec2-user ~]$ sudo userdel -r olduser
```
# Connect to your Windows instance using RDP
You can connect to Amazon EC2 instances created from most Windows Amazon Machine Images (AMIs) using Remote Desktop. Remote Desktop uses the Remote Desktop Protocol (RDP) to connect to and use your instance in the same way you use a computer sitting in front of you (local computer). It is available on most editions of Windows and is also available for Mac OS.
The license for the Windows Server operating system allows two simultaneous remote connections for administrative purposes. The license for Windows Server is included in the price of your Windows instance. If you require more than two simultaneous remote connections, you must purchase a Remote Desktop Services (RDS) license. If you attempt a third connection, an error occurs.
**Tip**
If you need to connect to your instance in order to troubleshoot boot, network configuration, and other issues for instances built on the [AWS Nitro System](https://aws.amazon.com/ec2/nitro/), you can use the [EC2 Serial Console for instances](ec2-serial-console.md).
**Topics**
+ [
# Connect to your Windows instance using an RDP client
](connect-rdp.md)
+ [
# Connect to your Windows instance using Fleet Manager
](connect-rdp-fleet-manager.md)
+ [
# Transfer files to a Windows instance using RDP
](connect-to-linux-instanceWindowsFileTransfer.md)
# Connect to your Windows instance using an RDP client
Connect using an RDP client
You can connect to your Windows instance using an RDP client as follows.
**Tip**
Alternatively, you can connect to your Windows instance using [Systems Manager Fleet Manager](connect-rdp-fleet-manager.md) or [EC2 Instance Connect Endpoint](connect-with-ec2-instance-connect-endpoint.md).
## Prerequisites
You must meet the following prerequisites to connect to your Windows instance using an RDP client.
+ **Complete the general prerequisites.**
+ Check that your instance has passed its status checks. It can take a few minutes for an instance to be ready to accept connection requests. For more information, see [View status checks](viewing_status.md).
+ [Get the required instance details](connection-prereqs-general.md#connection-prereqs-get-info-about-instance).
+ [Locate the private key and set permissions](connection-prereqs-general.md#connection-prereqs-private-key).
+ [(Optional) Get the instance fingerprint](connection-prereqs-general.md#connection-prereqs-fingerprint).
+ **Install an RDP client.**
+ (Windows) Windows includes an RDP client by default. To verify, type **mstsc** at a Command Prompt window. If your computer doesn't recognize this command, download the [Microsoft Remote Desktop app](https://apps.microsoft.com/detail/9wzdncrfj3ps) from the Microsoft Store.
+ (macOS X) Download the [Windows App for Mac (previously named Microsoft Remote Desktop](https://apps.apple.com/us/app/windows-app/id1295203466?mt=12) from the Mac App Store.
+ (Linux) Use [Remmina](https://remmina.org/).
+ **Allow inbound RDP traffic from your IP address.**
Ensure that the security group associated with your instance allows incoming RDP traffic from your IP address. For more information, see [Rules to connect to instances from your computer](security-group-rules-reference.md#sg-rules-local-access).
## Retrieve the administrator password
If you joined your instance to a domain, you can connect to your instance using the domain credentials from Directory Service. On the Remote Desktop login screen, instead of using the local computer name and the generated password, use the fully-qualified username for the administrator (for example, **corp.example.com\$1Admin**), and the password for this account.
To connect to a Windows instance using RDP, you must retrieve the initial administrator password and then enter this password when you connect to your instance. It takes a few minutes after instance launch before this password is available. Your account must have permission to call the [GetPasswordData](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_GetPasswordData.html) action. For more information, see [Example policies to control access the Amazon EC2 API](ExamplePolicies_EC2.md).
The default username for the Administrator account depends on the language of the operating system (OS) contained in the AMI. To determine the correct username, identify the language of the OS, and then choose the corresponding username. For example, for an English OS, the username is `Administrator`, for a French OS it's `Administrateur`, and for a Portuguese OS it's `Administrador`. If a language version of the OS does not have a username in the same language, choose the username `Administrator (Other)`. For more information, see [Localized Names for Administrator Account in Windows](https://learn.microsoft.com/en-us/archive/technet-wiki/13813.localized-names-for-administrator-account-in-windows) in the Microsoft website.
**To retrieve the initial administrator password**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation pane, choose **Instances**.
1. Select the instance and then choose **Connect**.
1. On the **Connect to instance** page, choose the **RDP client** tab.
1. For **Username**, choose the default username for the Administrator account. The username you choose must match the language of the operating system (OS) contained in the AMI that you used to launch your instance. If there is no username in the same language as your OS, choose **Administrator (Other)**.
1. Choose **Get password**.
1. On the **Get Windows password** page, do the following:
1. Choose **Upload private key file** and navigate to the private key (`.pem`) file that you specified when you launched the instance. Select the file and choose **Open** to copy the entire contents of the file to this window.
1. Choose **Decrypt password**. The **Get Windows password** page closes, and the default administrator password for the instance appears under **Password**, replacing the **Get password** link shown previously.
1. Copy the password and save it in a safe place. This password is required to connect to the instance.
## Connect to your Windows instance
The following procedure uses the Remote Desktop Connection client for Windows (MSTSC). If you're using a different RDP client, download the RDP file and then see the documentation for the RDP client for the steps to establish the RDP connection.
**To connect to a Windows instance using an RDP client**
1. On the **Connect to instance** page, choose **Download remote desktop file**. When the file download is finished, choose **Cancel** to return to the **Instances** page. The RDP file is downloaded to your `Downloads` folder.
1. Run `mstsc.exe` to open the RDP client.
1. Expand **Show options**, choose **Open**, and select the .rdp file from your `Downloads` folder.
1. By default, **Computer** is the public IPv4 DNS name of the instance and **User name** is the administrator account. To connect to the instance using IPv6 instead, replace the public IPv4 DNS name of the instance with its IPv6 address. Review the default settings and change them as needed.
1. Choose **Connect**. If you receive a warning that the publisher of the remote connection is unknown, choose **Connect** to continue.
1. Enter the password that you saved previously, and then choose **OK**.
1. Due to the nature of self-signed certificates, you might get a warning that the security certificate could not be authenticated. Do one of the following:
+ If you trust the certificate, choose **Yes** to connect to your instance.
+ [Windows] Before you proceed, compare the thumbprint of the certificate with the value in the system log to confirm the identity of the remote computer. Choose **View certificate** and then choose **Thumbprint** from the **Details** tab. Compare this value to the value of `RDPCERTIFICATE-THUMBPRINT` in **Actions**, **Monitor and troubleshoot**, **Get system log**.
+ [Mac OS X] Before you proceed, compare the fingerprint of the certificate with the value in the system log to confirm the identity of the remote computer. Choose **Show Certificate**, expand **Details**, and choose **SHA1 Fingerprints**. Compare this value to the value of `RDPCERTIFICATE-THUMBPRINT` in **Actions**, **Monitor and troubleshoot**, **Get system log**.
1. If the RDP connection is successful, the RDP client displays the Windows login screen and then the Windows desktop. If you receive an error message instead, see [Remote Desktop can't connect to the remote computer](troubleshoot-connect-windows-instance.md#rdp-issues). When you are finished with the RDP connection, you can close the RDP client.
## Configure user accounts
After you connect to your instance over RDP, we recommend that you perform the following tasks:
+ Change the administrator password from the default value. You [can change the password while you are logged on to the instance itself](https://support.microsoft.com/en-us/windows/change-or-reset-your-windows-password-8271d17c-9f9e-443f-835a-8318c8f68b9c), just as you would on any computer running Windows Server.
+ Create another user with administrator privileges on the instance. This is a safeguard in case you forget the administrator password or have a problem with the administrator account. The new user must have permission to access the instance remotely. Open **System Properties** by right-clicking on the **This PC** icon on your Windows desktop or File Explorer and selecting **Properties**. Choose **Remote settings**, and choose **Select Users** to add the user to the **Remote Desktop Users** group.
![\[System Properties window.\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/windows-connect-properties-rdp.png)
# Connect to your Windows instance using Fleet Manager
Connect using Fleet Manager
You can use Fleet Manager, a capability of AWS Systems Manager, to connect to Windows instances using the Remote Desktop Protocol (RDP) and display up to four Windows instances on the same page in the AWS Management Console. You can connect to the first instance in the Fleet Manager Remote Desktop directly from the **Instances** page in the Amazon EC2 console. For more information about Fleet Manager, see [Connect to a managed instance using Remote Desktop](https://docs.aws.amazon.com/systems-manager/latest/userguide/fleet-manager-remote-desktop-connections.html) in the *AWS Systems Manager User Guide*.
You do not need to specifically allow incoming RDP traffic from your IP address if you use Fleet Manager to connect. Fleet Manager handles that for you.
**Prerequisites**
Before attempting to connect to an instance using Fleet Manager, you must set up your environment. For more information, see [Setting up your environment](https://docs.aws.amazon.com/systems-manager/latest/userguide/fleet-manager-remote-desktop-connections.html#rdp-prerequisites) in the *AWS Systems Manager User Guide*.
**To connect to a Windows instance using Fleet Manager**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. From the navigation pane, choose **Instances**.
1. Select the instance and then choose **Connect**.
1. On the **RDP client** tab, for **Connection Type**, choose **Connect using Fleet Manager**.
1. Choose **Fleet Manager Remote Desktop**. This opens the **Fleet Manager Remote Desktop** page in the AWS Systems Manager console.
1. Enter your credentials and then choose **Connect**.
1. If the RDP connection is successful, Fleet Manager displays the Windows desktop. When you are finished with the session, choose **Actions**, **End session**.
For more information, see [Connecting to a Windows Server managed instance using Remote Desktop](https://docs.aws.amazon.com/systems-manager/latest/userguide/fleet-manager-remote-desktop-connections.html) in the *AWS Systems Manager User Guide*.
# Transfer files to a Windows instance using RDP
Transfer files using RDP
You can work with your Windows instance in the same way that you would work with any Windows server. For example, you can transfer files between a Windows instance and your local computer using the local file sharing feature of the Microsoft Remote Desktop Connection (RDP) software. You can access local files on hard disk drives, DVD drives, portable media drives, and mapped network drives.
To access your local files from your Windows instances, you must enable the local file sharing feature by mapping the remote session drive to your local drive. The steps are slightly different depending on whether your local computer operating system is Windows or macOS X.
For more information about the prerequisites to connect using RDP, see [Prerequisites](connect-rdp.md#rdp-prereqs).
------
#### [ Windows ]
**To map the remote session drive to your local drive on your local Windows computer**
1. Open the Remote Desktop Connection client.
1. Choose **Show Options**.
1. Add the instance host name to the **Computer** field and username to the **User name** field, as follows:
1. Under **Connection settings**, choose **Open...**, and browse to the RDP shortcut file that you downloaded from the Amazon EC2 console. The file contains the Public IPv4 DNS host name, which identifies the instance, and the Administrator user name.
1. Select the file and choose **Open**. The **Computer** and **User name** fields are populated with the values from the RDP shortcut file.
1. Choose **Save**.
1. Choose the **Local Resources** tab.
1. Under **Local devices and resources**, choose **More...**
![\[RDP Local Resources window.\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/windows-connect-rdp-local-resources.png)
1. Open **Drives** and select the local drive to map to your Windows instance.
1. Choose **OK**.
![\[RDP Local devices and resources window.\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/windows-connect-rdp-drives.png)
1. Choose **Connect** to connect to your Windows instance.
------
#### [ macOS X ]
**To map the remote session drive to your local folder on your local macOS X computer**
1. Open the Remote Desktop Connection client.
1. Browse to the RDP file that you downloaded from the Amazon EC2 console (when you initially connected to the instance), and drag it onto the Remote Desktop Connection client.
1. Right-click the RDP file, and choose **Edit**.
1. Choose the **Folders** tab, and select the **Redirect folders** checkbox.
![\[Microsoft Remote Desktop Edit PC window.\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/mac-map-folder-1.png)
1. Choose the **\$1** icon at bottom left, browse to the folder to map, and choose **Open**. Repeat this step for every folder to map.
1. Choose **Save**.
1. Choose **Connect** to connect to your Windows instance. You'll be prompted for the password.
1. On the instance, in File Explorer, expand **This PC**, and find the shared folder from which you can access your local files. In the following screenshot, the **Desktop** folder on the local computer was mapped to the remote session drive on the instance.
![\[Microsoft Remote Desktop Edit PC window.\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/mac-map-folder-2.png)
For more information on making local devices available to a remote session on a Mac computer, see [Get started with the macOS client](https://learn.microsoft.com/en-us/windows-server/remote/remote-desktop-services/clients/remote-desktop-mac).
------
# Connect to your Amazon EC2 instance using Session Manager
Connect using Session Manager
Session Manager is a fully-managed AWS Systems Manager capability for managing your Amazon EC2 instances through an interactive, one-click, browser-based shell, or through the AWS CLI. You can use Session Manager to start a session with an instance in your account. After the session is started, you can run interactive commands on the instance as you would for any other connection type. For more information about Session Manager, see [AWS Systems Manager Session Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager.html) in the *AWS Systems Manager User Guide*.
**Prerequisites**
Before you attempt to connect to an instance using Session Manager, you must complete the required setup steps. For example, the instance must be managed by SSM and must have an attached IAM role with the **AmazonSSMManagedInstanceCore** policy. For more information, see [Setting up Session Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-getting-started.html).
**To connect to an Amazon EC2 instance using Session Manager on the Amazon EC2 console**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation pane, choose **Instances**.
1. Select the instance and choose **Connect**.
1. For the connection method, choose **Session Manager**.
1. Choose **Connect** to start the session.
![\[The Connect button on the Session Manager tab.\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/connect-method-session-manager.png)
**Troubleshooting**
If you receive an error that you're not authorized to perform one or more Systems Manager actions (`ssm:command-name`), you must update your policies to allow you to start sessions from the Amazon EC2 console. For more information and instructions, see [Quickstart default IAM policies for Session Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/getting-started-restrict-access-quickstart.html) in the *AWS Systems Manager User Guide*.
# Connect to your Linux instance using a public IP address and EC2 Instance Connect
Connect using a public IP and EC2 Instance Connect
Amazon EC2 Instance Connect provides a secure way to connect to your Linux instances over Secure Shell (SSH). With EC2 Instance Connect, you use AWS Identity and Access Management (IAM) [policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) and [principals](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) to control SSH access to your instances, removing the need to share and manage SSH keys. All connection requests using EC2 Instance Connect are [logged to AWS CloudTrail](monitor-with-cloudtrail.md#ec2-instance-connect-cloudtrail) so that you can audit connection requests.
You can use EC2 Instance Connect to connect to your instances using the Amazon EC2 console or the SSH client of your choice.
When you connect to an instance using EC2 Instance Connect, the EC2 Instance Connect API pushes an SSH public key to the [instance metadata](ec2-instance-metadata.md) where it remains for 60 seconds. An IAM policy attached to your user authorizes your user to push the public key to the instance metadata. The SSH daemon uses `AuthorizedKeysCommand` and `AuthorizedKeysCommandUser`, which are configured when EC2 Instance Connect is installed, to look up the public key from the instance metadata for authentication, and connects you to the instance.
**Tip**
EC2 Instance Connect is one of the options to connect to your Linux instance. For other options, see [Connect to your Linux instance using SSH](connect-to-linux-instance.md). To connect to a Windows instance, see [Connect to your Windows instance using RDP](connecting_to_windows_instance.md).
**Pricing**
EC2 Instance Connect is available at no additional cost.
**Region availability**
EC2 Instance Connect is available in all AWS Regions. It is not supported in Local Zones.
**Topics**
+ [Tutorial](ec2-instance-connect-tutorial.md)
+ [Prerequisites](ec2-instance-connect-prerequisites.md)
+ [Permissions](ec2-instance-connect-configure-IAM-role.md)
+ [Install EC2 Instance Connect](ec2-instance-connect-set-up.md)
+ [Connect to an instance](ec2-instance-connect-methods.md)
+ [
# Uninstall EC2 Instance Connect
](ec2-instance-connect-uninstall.md)
For a blog post that discusses how to improve the security of your bastion hosts using EC2 Instance Connect, see [Securing your bastion hosts with Amazon EC2 Instance Connect](https://aws.amazon.com/blogs/infrastructure-and-automation/securing-your-bastion-hosts-with-amazon-ec2-instance-connect/).
# Tutorial: Complete the configuration required to connect to your instance using EC2 Instance Connect
Tutorial
To connect to your instance using EC2 Instance Connect in the Amazon EC2 console, you first need to complete the prerequisite configuration that will allow you to successfully connect to your instance. The purpose of this tutorial is to guide you through the tasks to complete the prerequisite configuration.
**Tutorial overview**
In this tutorial, you'll complete the following four tasks:
+ [Task 1: Grant permissions required to use EC2 Instance Connect](#eic-tut1-task1)
First you'll create an IAM policy that contains the IAM permissions that allow you to push a public key to the instance metadata. You'll attach this policy to your IAM identity (user, user group, or role) so that your IAM identity gets these permissions.
+ [Task 2: Allow inbound traffic from the EC2 Instance Connect service to your instance](#eic-tut1-task2)
Then you'll create a security group that allows traffic from the EC2 Instance Connect service to your instance. This is required when you use EC2 Instance Connect in the Amazon EC2 console to connect to your instance.
+ [Task 3: Launch your instance](#eic-tut1-task3)
You'll then launch an EC2 instance using an AMI that is pre-installed with EC2 Instance Connect and you'll add the security group that you created in the previous step.
+ [Task 4: Connect to your instance](#eic-tut1-task4)
Finally, you'll use EC2 Instance Connect in the Amazon EC2 console to connect to your instance. If you can connect, then you can be sure that the prerequisite configuration you completed in Tasks 1, 2, and 3 were successful.
## Task 1: Grant permissions required to use EC2 Instance Connect
When you connect to an instance using EC2 Instance Connect, the EC2 Instance Connect API pushes an SSH public key to the [instance metadata](ec2-instance-metadata.md) where it remains for 60 seconds. You need an IAM policy attached to your IAM identity (user, user group, or role) to grant you the required permission to push the public key to the instance metadata.
**Task objective**
You'll create the IAM policy that grants the permission to push the public key to the instance. The specific action to allow is `ec2-instance-connect:SendSSHPublicKey`. You must also allow the `ec2:DescribeInstances` action so that you can view and select your instance in the Amazon EC2 console.
After you've created the policy, you'll attach the policy to your IAM identity (user, user group, or role) so that your IAM identity gets the permissions.
You'll create a policy that is configured as follows:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": "ec2-instance-connect:SendSSHPublicKey",
"Resource": "*"
},
{
"Effect": "Allow",
"Action": "ec2:DescribeInstances",
"Resource": "*"
}
]
}
```
------
**Important**
The IAM policy created in this tutorial is a highly permissive policy; it allows you to connect to any instance using any AMI username. We're using this highly permissive policy to keep the tutorial simple and focused on the specific configurations that this tutorial is teaching. However, in a production environment, we recommend that your IAM policy is configured to provide [least-privilege permissions](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege). For example IAM policies, see [Grant IAM permissions for EC2 Instance Connect](ec2-instance-connect-configure-IAM-role.md).
**To create and attach an IAM policy that allows you to use EC2 Instance Connect to connect to your instances**
1. **First create the IAM policy**
1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. In the navigation pane, choose **Policies**.
1. Choose **Create policy**.
1. On the **Specify permission** page, do the following:
1. For **Service**, choose **EC2 Instance Connect**.
1. Under **Actions allowed**, in the search field start typing **send** to show the relevant actions, and then select **SendSSHPublicKey**.
1. Under **Resources**, choose **All**. For a production environment, we recommend specifying the instance by its ARN, but for this tutorial, you're allowing all instances.
1. Choose **Add more permissions**.
1. For **Service**, choose **EC2**.
1. Under **Actions allowed**, in the search field start typing **describein** to show the relevant actions, and then select **DescribeInstances**.
1. Choose **Next**.
1. On the **Review and create** page, do the following:
1. For **Policy name**, enter a name for the policy.
1. Choose **Create policy**.
1. **Then attach the policy to your identity**
1. In the IAM console, in the navigation pane, choose **Policies**.
1. In the list of policies, select the option button next to the name of the policy you created. You can use the search box to filter the list of policies.
1. Choose **Actions**, **Attach**.
1. Under **IAM entities**, select the checkbox next to your identity (user, user group, or role). You can use the search box to filter the list of entities.
1. Choose **Attach policy**.
### View an animation: Create an IAM policy
![\[This animation shows how to create an IAM policy. For the text version of this animation, see the steps in the preceding procedure.\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/eic-tut1-task1-create-iam-policy.gif)
### View an animation: Attach an IAM policy
![\[This animation shows how to attach an IAM policy to an IAM identity. For the text version of this animation, see the steps in the preceding procedure.\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/eic-tut1-task1-attach-iam-policy.gif)
## Task 2: Allow inbound traffic from the EC2 Instance Connect service to your instance
When you use EC2 Instance Connect in the Amazon EC2 console to connect to an instance, the traffic that must be allowed to reach the instance is traffic from the EC2 Instance Connect service. This is different to connecting from your local computer to an instance; in that case, you must allow traffic from your local computer to your instance. To allow traffic from the EC2 Instance Connect service, you must create a security group that allows inbound SSH traffic from the IP address range for the EC2 Instance Connect service.
AWS uses prefix lists to manage IP address ranges. The names of the EC2 Instance Connect prefix lists are as follows, with *region* replaced by the Region code:
+ IPv4 prefix list name: `com.amazonaws.region.ec2-instance-connect`
+ IPv6 prefix list name: `com.amazonaws.region.ipv6.ec2-instance-connect`
**Task objective**
You'll create a security group that allows inbound SSH traffic on port 22 from the IPv4 prefix list in the Region in which your instance is located.
**To create a security group that allows inbound traffic from the EC2 Instance Connect service to your instance**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation pane, choose **Security Groups**.
1. Choose **Create security group**.
1. Under **Basic details**, do the following:
1. For **Security group name**, enter a meaningful name for your security group.
1. For **Description**, enter a meaningful description for your security group.
1. Under **Inbound rules**, do the following:
1. Choose **Add rule**.
1. For **Type**, choose **SSH**.
1. For **Source**, leave **Custom**.
1. In the field next to **Source**, select the prefix list for EC2 Instance Connect.
For example, if your instance is located in the US East (N. Virginia) (`us-east-1`) Region and your users will connect to its public IPv4 address, choose the following prefix list: **com.amazonaws.us-east-1.ec2-instance-connect**
1. Choose **Create security group**.
### View an animation: Create the security group
![\[This animation shows how to configure a security group. For the text version of this animation, see the steps in the preceding procedure.\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/tut1-task2-eic-security-group.gif)
## Task 3: Launch your instance
When you launch an instance, you must specify an AMI that contains the information required to launch the instance. You can choose to launch an instance with or without EC2 Instance Connect pre-installed. In this task, we specify an AMI that comes pre-installed with EC2 Instance Connect.
If you launch your instance without EC2 Instance Connect pre-installed, and you want to use EC2 Instance Connect to connect to your instance, you'll need to perform additional configuration steps. These steps are outside the scope of this tutorial.
**Task objective**
You'll launch an instance with the Amazon Linux 2023 AMI, which comes pre-installed with EC2 Instance Connect. You'll also specify the security group that you created earlier so that you can use EC2 Instance Connect in the Amazon EC2 console to connect to your instance. Because you'll use EC2 Instance Connect to connect to your instance, which pushes a public key to your instance's metadata, you won't need to specify an SSH key when you launch your instance.
**To launch an instance that can use EC2 Instance Connect in the Amazon EC2 console for connection**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation bar at the top of the screen, the current AWS Region is displayed (for example, **Ireland**). Select a Region in which to launch your instance. This choice is important because you created a security group that allows traffic for a specific Region, so you must select the same Region in which to launch your instance.
1. From the Amazon EC2 console dashboard, choose **Launch instance**.
1. (Optional) Under **Name and tags**, for **Name**, enter a descriptive name for your instance.
1. Under **Application and OS Images (Amazon Machine Image)**, choose **Quick Start**. **Amazon Linux** is selected by default. Under **Amazon Machine Image (AMI)**, **Amazon Linux 2023 AMI** is selected by default. Keep the default selection for this task.
1. Under **Instance type**, for **Instance type**, keep the default selection, or choose a different instance type.
1. Under **Key pair (login)**, for **Key pair name**, choose **Proceed without a key pair (Not recommended)**. When you use EC2 Instance Connect to connect to an instance, EC2 Instance Connect pushes a key pair to the instance's metadata, and it is this key pair that is used for the connection.
1. Under **Network settings**, do the following:
1. For **Auto-assign public IP**, leave **Enable**.
**Note**
To use EC2 Instance Connect in the Amazon EC2 console to connect to an instance, the instance must have a public IPv4 or IPv6 address.
1. For **Firewall (security groups)**, choose **Select existing security group**.
1. Under **Common security groups**, choose the security group that you created earlier.
1. In the **Summary** panel, choose **Launch instance**.
### View an animation: Launch your instance
![\[This animation shows how to launch an instance. For the text version of this animation, see the steps in the preceding procedure.\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/tut1-task3-launch-an-instance.gif)
## Task 4: Connect to your instance
When you connect to an instance using EC2 Instance Connect, the EC2 Instance Connect API pushes an SSH public key to the [instance metadata](ec2-instance-metadata.md) where it remains for 60 seconds. The SSH daemon uses `AuthorizedKeysCommand` and `AuthorizedKeysCommandUser` to look up the public key from the instance metadata for authentication, and connects you to the instance.
**Task objective**
In this task, you'll connect to your instance using EC2 Instance Connect in the Amazon EC2 console. If you completed the prerequisite Tasks 1, 2, and 3, the connection should be successful.
**Steps to connect to your instance**
Use the following steps to connect to your instance. To view an animation of the steps, see [View an animation: Connect to your instance](#eic-tut1-task4-animation).
**To connect an instance using EC2 Instance Connect in the Amazon EC2 console**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation bar at the top of the screen, the current AWS Region is displayed (for example, **Ireland**). Select the Region in which your instance is located.
1. In the navigation pane, choose **Instances**.
1. Select your instance and choose **Connect**.
1. Choose the **EC2 Instance Connect** tab.
1. Choose **Connect using a Public IP**.
1. Choose **Connect**.
A terminal window opens in the browser, and you are connected to your instance.
### View an animation: Connect to your instance
![\[This animation shows how to connect an instance using EC2 Instance Connect. For the text version of this animation, see the steps in the preceding procedure.\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/eic-tut1-task4-connect.gif)
# Prerequisites for EC2 Instance Connect
Prerequisites
**Topics**
+ [
## Install EC2 Instance Connect
](#eic-prereqs-install-eic-on-instance)
+ [
## Ensure network connectivity
](#eic-prereqs-network-access)
+ [
## Allow inbound SSH traffic
](#ec2-instance-connect-setup-security-group)
+ [
## Grant permissions
](#eic-prereqs-grant-permissions)
+ [
## Install an SSH client on your local computer
](#eic-prereqs-install-ssh-client)
+ [
## Meet username requirements
](#eic-prereqs-username)
## Install EC2 Instance Connect
To use EC2 Instance Connect to connect to an instance, the instance must have EC2 Instance Connect installed. You can either launch the instance using an AMI that comes pre-installed with EC2 Instance Connect, or you can install EC2 Instance Connect on instances that are launched with supported AMIs. For more information, see [Install EC2 Instance Connect on your EC2 instances](ec2-instance-connect-set-up.md).
## Ensure network connectivity
Instances can be configured to allow users to connect to your instance over the internet or through the instance's private IP address. Depending on how your users will connect to your instance using EC2 Instance Connect, you must configure the following network access:
+ If your users will connect to your instance over the internet, then your instance must have a public IPv4 or IPv6 address and be in a public subnet with a route to the internet. If you haven't modified your default public subnet, then it contains a route to the internet for IPv4 only, and not for IPv6. For more information, see [Enable VPC internet access using internet gateways](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Internet_Gateway.html#vpc-igw-internet-access) in the *Amazon VPC User Guide*.
+ If your users will connect to your instance through the instance's private IPv4 address, then you must establish private network connectivity to your VPC, such as by using AWS Direct Connect, AWS Site-to-Site VPN, or VPC peering, so that your users can reach the instance's private IP address.
If your instance does not have a public IPv4 or IPv6 address and you prefer not to configure the network access as described above, you can consider EC2 Instance Connect Endpoint as an alternative to EC2 Instance Connect. With EC2 Instance Connect Endpoint, you can connect to an instance using SSH or RDP even if the instance does not have a public IPv4 or IPv6 address. For more information, see [Connect to your Linux instance using the Amazon EC2 console](connect-using-eice.md#connect-using-the-ec2-console).
## Allow inbound SSH traffic
**When using the Amazon EC2 console to connect to an instance**
When users connect to an instance using the Amazon EC2 console, the traffic that must be allowed to reach the instance is traffic from the EC2 Instance Connect service. The service is identified by specific IP address ranges, which AWS manages through prefix lists. You must create a security group that allows inbound SSH traffic from the EC2 Instance Connect service. To configure this, for the inbound rule, in the field next to **Source**, select the EC2 Instance Connect prefix list.
AWS provides different managed prefix lists for IPv4 and IPv6 addresses for each Region. The names of the EC2 Instance Connect prefix lists are as follows, with *region* replaced by the Region code:
+ IPv4 prefix list name: `com.amazonaws.region.ec2-instance-connect`
+ IPv6 prefix list name: `com.amazonaws.region.ipv6.ec2-instance-connect`
For the instructions for creating the security group, see [Task 2: Allow inbound traffic from the EC2 Instance Connect service to your instance](ec2-instance-connect-tutorial.md#eic-tut1-task2). For more information, see [Available AWS-managed prefix lists](https://docs.aws.amazon.com/vpc/latest/userguide/working-with-aws-managed-prefix-lists.html#available-aws-managed-prefix-lists) in the *Amazon VPC User Guide*.
**When using the CLI or SSH to connect to an instance**
Ensure that the security group associated with your instance [allows inbound SSH traffic](security-group-rules-reference.md#sg-rules-local-access) on port 22 from your IP address or from your network. The default security group for the VPC does not allow incoming SSH traffic by default. The security group created by the launch instance wizard allows incoming SSH traffic by default. For more information, see [Rules to connect to instances from your computer](security-group-rules-reference.md#sg-rules-local-access).
## Grant permissions
You must grant the required permissions to every IAM user who will use EC2 Instance Connect to connect to an instance. For more information, see [Grant IAM permissions for EC2 Instance Connect](ec2-instance-connect-configure-IAM-role.md).
## Install an SSH client on your local computer
If your users will connect using SSH, they must ensure that their local computer has an SSH client.
A user's local computer most likely has an SSH client installed by default. They can check for an SSH client by typing **ssh** at the command line. If their local computer doesn't recognize the command, they can install an SSH client. For information about installing an SSH client on Linux or macOS X, see [http://www.openssh.com](http://www.openssh.com/). For information about installing an SSH client on Windows 10, see [OpenSSH in Windows](https://learn.microsoft.com/en-us/windows-server/administration/OpenSSH/openssh-overview).
There is no need to install an SSH client on a local computer if your users use only the Amazon EC2 console to connect to an instance.
## Meet username requirements
When using EC2 Instance Connect to connect to an instance, the username must meet the following requirements:
+ First character: Must be a letter (`A-Z`, `a-z`), a digit (`0-9`), or an underscore (`_`)
+ Subsequent characters: Can be letters (`A-Z`, `a-z`), digits (`0-9`), or the following characters: `@ . _ -`
+ Minimum length: 1 character
+ Maximum length: 31 characters
# Grant IAM permissions for EC2 Instance Connect
Permissions
To connect to an instance using EC2 Instance Connect, you must create an IAM policy that grants your users permissions for the following actions and condition:
+ `ec2-instance-connect:SendSSHPublicKey` action – Grants permission to push the public key to an instance.
+ `ec2:osuser` condition – Specifies the name of the OS user that can push the public key to an instance. Use the default username for the AMI that you used to launch the instance. The default username for AL2023 and Amazon Linux 2 is `ec2-user`, and for Ubuntu it's `ubuntu`.
+ `ec2:DescribeInstances` action – Required when using the EC2 console because the wrapper calls this action. Users might already have permission to call this action from another policy.
+ `ec2:DescribeVpcs` action – Required when connecting to an IPv6 address.
Consider restricting access to specific EC2 instances. Otherwise, all IAM principals with permission for the `ec2-instance-connect:SendSSHPublicKey` action can connect to all EC2 instances. You can restrict access by specifying resource ARNs or by using resource tags as [condition keys](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonec2instanceconnect.html#amazonec2instanceconnect-policy-keys).
For more information, see [Actions, resources, and condition keys for Amazon EC2 Instance Connect](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonec2instanceconnect.html).
For information about creating IAM policies, see [Creating IAM policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) in the *IAM User Guide*.
## Allow users to connect to specific instances
The following IAM policy grants permission to connect to specific instances, identified by their resource ARNs.
In the following example IAM policy, the following actions and condition are specified:
+ The `ec2-instance-connect:SendSSHPublicKey` action grants users permission to connect to two instances, specified by the resource ARNs. To grant users permission to connect to *all* EC2 instances, replace the resource ARNs with the `*` wildcard.
+ The `ec2:osuser` condition grants permission to connect to the instances only if the *ami-username* is specified when connecting.
+ The `ec2:DescribeInstances` action is specified to grant permission to users who will use the console to connect to your instances. If your users will only use an SSH client to connect to your instances, you can omit `ec2:DescribeInstances`. Note that the `ec2:Describe*` API actions do not support resource-level permissions. Therefore, the `*` wildcard is necessary in the `Resource` element.
+ The `ec2:DescribeVpcs` action is specified to grant permission to users who will use the console to connect to your instances using an IPv6 address. If your users will only use a public IPv4 address, you can omit `ec2:DescribeVpcs`. Note that the `ec2:Describe*` API actions do not support resource-level permissions. Therefore, the `*` wildcard is necessary in the `Resource` element.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": "ec2-instance-connect:SendSSHPublicKey",
"Resource": [
"arn:aws:ec2:us-east-1:111122223333:instance/i-1234567890abcdef0",
"arn:aws:ec2:us-east-1:111122223333:instance/i-0598c7d356eba48d7"
],
"Condition": {
"StringEquals": {
"ec2:osuser": "ami-username"
}
}
},
{
"Effect": "Allow",
"Action": [
"ec2:DescribeInstances",
"ec2:DescribeVpcs"
],
"Resource": "*"
}
]
}
```
------
## Allow users to connect to instances with specific tags
Attribute-based access control (ABAC) is an authorization strategy that defines permissions based on tags that can be attached to users and AWS resources. You can use resource tags to control access to an instance. For more information about using tags to control access to your AWS resources, see [Controlling access to AWS resources](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_tags.html#access_tags_control-resources) in the *IAM User Guide*.
In the following example IAM policy, the `ec2-instance-connect:SendSSHPublicKey` action grants users permission to connect to any instance (indicated by the `*` wildcard in the resource ARN) on condition that the instance has a resource tag with key=`tag-key` and value=`tag-value`.
The `ec2:DescribeInstances` action is specified to grant permission to users who will use the console to connect to your instances. If your users will use only an SSH client to connect to your instances, you can omit `ec2:DescribeInstances`. Note that the `ec2:Describe*` API actions do not support resource-level permissions. Therefore, the `*` wildcard is necessary in the `Resource` element.
The `ec2:DescribeVpcs` action is specified to grant permission to users who will use the console to connect to your instances using an IPv6 address. If your users will only use a public IPv4 address, you can omit `ec2:DescribeVpcs`. Note that the `ec2:Describe*` API actions do not support resource-level permissions. Therefore, the `*` wildcard is necessary in the `Resource` element.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": "ec2-instance-connect:SendSSHPublicKey",
"Resource": "arn:aws:ec2:us-east-1:111122223333:instance/*",
"Condition": {
"StringEquals": {
"aws:ResourceTag/tag-key": "tag-value"
}
}
},
{
"Effect": "Allow",
"Action": [
"ec2:DescribeInstances",
"ec2:DescribeVpcs"
],
"Resource": "*"
}
]
}
```
------
# Install EC2 Instance Connect on your EC2 instances
Install EC2 Instance Connect
To connect to a Linux instance using EC2 Instance Connect, the instance must have EC2 Instance Connect installed. Installing EC2 Instance Connect configures the SSH daemon on the instance.
For more information about the EC2 Instance Connect package, see [aws/aws-ec2-instance-connect-config ](https://github.com/aws/aws-ec2-instance-connect-config) on the GitHub website.
**Note**
If you configured the `AuthorizedKeysCommand` and `AuthorizedKeysCommandUser` settings for SSH authentication, the EC2 Instance Connect installation will not update them. As a result, you can't use EC2 Instance Connect.
## Install prerequisites
Before you install EC2 Instance Connect, ensure that you meet the following prerequisites.
+ **Verify that the instance uses one of the following:**
+ Amazon Linux 2 prior to version 2.0.20190618 \$1
+ AL2023 minimal AMI or Amazon ECS-optimized AMI
+ CentOS Stream 8 and 9
+ macOS Sonoma prior to 14.2.1, Ventura prior to 13.6.3, and Monterey prior to 12.7.2 \$1
+ Red Hat Enterprise Linux (RHEL) 8 and 9
+ Ubuntu 16.04 and 18.04 \$1
**Tip**
\$1 For Amazon Linux 2, macOS, and Ubuntu: If you launched your instance using a later version than those listed above, EC2 Instance Connect comes preinstalled and no manual installation is required.
+ **Verify the general prerequisites for EC2 Instance Connect.**
For more information, see [Prerequisites for EC2 Instance Connect](ec2-instance-connect-prerequisites.md).
+ **Verify the prerequisites for connecting to your instance using an SSH client on your local machine.**
For more information, see [Connect to your Linux instance using SSH](connect-to-linux-instance.md).
+ **Get the ID of the instance.**
You can get the ID of your instance using the Amazon EC2 console (from the **Instance ID** column). If you prefer, you can use the [describe-instances](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instances.html) (AWS CLI) or [Get-EC2Instance](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-EC2Instance.html) (AWS Tools for Windows PowerShell) command.
## Manually install EC2 Instance Connect
**Note**
If you launched your instance using one of the following AMIs, EC2 Instance Connect is pre-installed and you can skip this procedure:
AL2023 standard AMI
Amazon Linux 2 2.0.20190618 or later
macOS Sonoma 14.2.1 or later
macOS Ventura 13.6.3 or later
macOS Monterey 12.7.2 or later
Ubuntu 20.04 or later
Use one of the following procedures for installing EC2 Instance Connect, depending on the operating system of your instance.
------
#### [ Amazon Linux 2 ]
**To install EC2 Instance Connect on an instance launched with Amazon Linux 2**
1. Connect to your instance using SSH.
Replace the example values in the following command with your values. Use the SSH key pair that was assigned to your instance when you launched it and the default username of the AMI that you used to launch your instance. For Amazon Linux 2, the default username is `ec2-user`.
```
$ ssh -i my_ec2_private_key.pem ec2-user@ec2-a-b-c-d.us-west-2.compute.amazonaws.com
```
For more information about connecting to your instance, see [Connect to your Linux instance using an SSH client](connect-linux-inst-ssh.md).
1. Install the EC2 Instance Connect package on your instance.
```
[ec2-user ~]$ sudo yum install ec2-instance-connect
```
You should see three new scripts in the `/opt/aws/bin/` folder:
```
eic_curl_authorized_keys
eic_parse_authorized_keys
eic_run_authorized_keys
```
1. (Optional) Verify that EC2 Instance Connect was successfully installed on your instance.
```
[ec2-user ~]$ sudo less /etc/ssh/sshd_config
```
EC2 Instance Connect was successfully installed if the `AuthorizedKeysCommand` and `AuthorizedKeysCommandUser` lines contain the following values:
```
AuthorizedKeysCommand /opt/aws/bin/eic_run_authorized_keys %u %f
AuthorizedKeysCommandUser ec2-instance-connect
```
+ `AuthorizedKeysCommand` sets the `eic_run_authorized_keys` script to look up the keys from the instance metadata
+ `AuthorizedKeysCommandUser` sets the system user as `ec2-instance-connect`
**Note**
If you previously configured `AuthorizedKeysCommand` and `AuthorizedKeysCommandUser`, the EC2 Instance Connect installation will not change the values and you will not be able to use EC2 Instance Connect.
------
#### [ CentOS ]
**To install EC2 Instance Connect on an instance launched with CentOS**
1. Connect to your instance using SSH.
Replace the example values in the following command with your values. Use the SSH key pair that was assigned to your instance when you launched it and the default username of the AMI that you used to launch your instance. For CentOS, the default username is `centos` or `ec2-user`.
```
$ ssh -i my_ec2_private_key.pem centos@ec2-a-b-c-d.us-west-2.compute.amazonaws.com
```
For more information about connecting to your instance, see [Connect to your Linux instance using an SSH client](connect-linux-inst-ssh.md).
1. If you use an HTTP or HTTPS proxy, you must set the `http_proxy` or `https_proxy` environment variables in the current shell session.
If you're not using a proxy, you can skip this step.
+ For an HTTP proxy server, run the following commands:
```
$ export http_proxy=http://hostname:port
$ export https_proxy=http://hostname:port
```
+ For an HTTPS proxy server, run the following commands:
```
$ export http_proxy=https://hostname:port
$ export https_proxy=https://hostname:port
```
1. Install the EC2 Instance Connect package on your instance by running the following commands.
The EC2 Instance Connect configuration files for CentOS are provided in a Red Hat Package Manager (RPM) package, with different RPM packages for CentOS 8 and CentOS 9 and for instance types that run on Intel/AMD (x86\$164) or ARM (AArch64).
Use the command block for your operating system and CPU architecture.
+ CentOS 8
Intel/AMD (x86\$164)
```
[ec2-user ~]$ mkdir /tmp/ec2-instance-connect
[ec2-user ~]$ curl https://amazon-ec2-instance-connect-us-west-2.s3.us-west-2.amazonaws.com/latest/linux_amd64/ec2-instance-connect-2.0.0-5.rhel8.x86_64.rpm -o /tmp/ec2-instance-connect/ec2-instance-connect.rpm
[ec2-user ~]$ curl https://amazon-ec2-instance-connect-us-west-2.s3.us-west-2.amazonaws.com/latest/linux_amd64/ec2-instance-connect-selinux-2.0.0-5.noarch.rpm -o /tmp/ec2-instance-connect/ec2-instance-connect-selinux.rpm
[ec2-user ~]$ sudo yum install -y /tmp/ec2-instance-connect/ec2-instance-connect.rpm /tmp/ec2-instance-connect/ec2-instance-connect-selinux.rpm
```
ARM (AArch64)
```
[ec2-user ~]$ mkdir /tmp/ec2-instance-connect
[ec2-user ~]$ curl https://amazon-ec2-instance-connect-us-west-2.s3.us-west-2.amazonaws.com/latest/linux_arm64/ec2-instance-connect-2.0.0-5.rhel8.aarch64.rpm -o /tmp/ec2-instance-connect/ec2-instance-connect.rpm
[ec2-user ~]$ curl https://amazon-ec2-instance-connect-us-west-2.s3.us-west-2.amazonaws.com/latest/linux_arm64/ec2-instance-connect-selinux-2.0.0-5.noarch.rpm -o /tmp/ec2-instance-connect/ec2-instance-connect-selinux.rpm
[ec2-user ~]$ sudo yum install -y /tmp/ec2-instance-connect/ec2-instance-connect.rpm /tmp/ec2-instance-connect/ec2-instance-connect-selinux.rpm
```
+ CentOS 9
Intel/AMD (x86\$164)
```
[ec2-user ~]$ mkdir /tmp/ec2-instance-connect
[ec2-user ~]$ curl https://amazon-ec2-instance-connect-us-west-2.s3.us-west-2.amazonaws.com/latest/linux_amd64/ec2-instance-connect-2.0.0-5.rhel9.x86_64.rpm -o /tmp/ec2-instance-connect/ec2-instance-connect.rpm
[ec2-user ~]$ curl https://amazon-ec2-instance-connect-us-west-2.s3.us-west-2.amazonaws.com/latest/linux_amd64/ec2-instance-connect-selinux-2.0.0-5.noarch.rpm -o /tmp/ec2-instance-connect/ec2-instance-connect-selinux.rpm
[ec2-user ~]$ sudo yum install -y /tmp/ec2-instance-connect/ec2-instance-connect.rpm /tmp/ec2-instance-connect/ec2-instance-connect-selinux.rpm
```
ARM (AArch64)
```
[ec2-user ~]$ mkdir /tmp/ec2-instance-connect
[ec2-user ~]$ curl https://amazon-ec2-instance-connect-us-west-2.s3.us-west-2.amazonaws.com/latest/linux_arm64/ec2-instance-connect-2.0.0-5.rhel9.aarch64.rpm -o /tmp/ec2-instance-connect/ec2-instance-connect.rpm
[ec2-user ~]$ curl https://amazon-ec2-instance-connect-us-west-2.s3.us-west-2.amazonaws.com/latest/linux_arm64/ec2-instance-connect-selinux-2.0.0-5.noarch.rpm -o /tmp/ec2-instance-connect/ec2-instance-connect-selinux.rpm
[ec2-user ~]$ sudo yum install -y /tmp/ec2-instance-connect/ec2-instance-connect.rpm /tmp/ec2-instance-connect/ec2-instance-connect-selinux.rpm
```
You should see the following new script in the `/opt/aws/bin/` folder:
```
eic_run_authorized_keys
```
1. (Optional) Verify that EC2 Instance Connect was successfully installed on your instance.
+ For CentOS 8:
```
[ec2-user ~]$ sudo less /lib/systemd/system/sshd.service.d/ec2-instance-connect.conf
```
+ For CentOS 9:
```
[ec2-user ~]$ sudo less /etc/ssh/sshd_config.d/60-ec2-instance-connect.conf
```
EC2 Instance Connect was successfully installed if the `AuthorizedKeysCommand` and `AuthorizedKeysCommandUser` lines contain the following values:
```
AuthorizedKeysCommand /opt/aws/bin/eic_run_authorized_keys %u %f
AuthorizedKeysCommandUser ec2-instance-connect
```
+ `AuthorizedKeysCommand` sets the `eic_run_authorized_keys` script to look up the keys from the instance metadata
+ `AuthorizedKeysCommandUser` sets the system user as `ec2-instance-connect`
**Note**
If you previously configured `AuthorizedKeysCommand` and `AuthorizedKeysCommandUser`, the EC2 Instance Connect installation will not change the values and you will not be able to use EC2 Instance Connect.
------
#### [ macOS ]
**To install EC2 Instance Connect on an instance launched with macOS**
1. Connect to your instance using SSH.
Replace the example values in the following command with your values. Use the SSH key pair that was assigned to your instance when you launched it and the default username of the AMI that you used to launch your instance. For macOS instances, the default username is `ec2-user`.
```
$ ssh -i my_ec2_private_key.pem ec2-user@ec2-a-b-c-d.us-west-2.compute.amazonaws.com
```
For more information about connecting to your instance, see [Connect to your Linux instance using an SSH client](connect-linux-inst-ssh.md).
1. Update Homebrew using the following command. The update will list the software that Homebrew knows about. The EC2 Instance Connect package is provided via Homebrew on macOS instances. For more information, see [Update the operating system and software on Amazon EC2 Mac instances](mac-instance-updates.md).
```
[ec2-user ~]$ brew update
```
1. Install the EC2 Instance Connect package on your instance. This will install the software and configure sshd to use it.
```
[ec2-user ~]$ brew install ec2-instance-connect
```
You should see the following new script in the `/opt/aws/bin/` folder:
```
eic_run_authorized_keys
```
1. (Optional) Verify that EC2 Instance Connect was successfully installed on your instance.
```
[ec2-user ~]$ sudo less /etc/ssh/sshd_config.d/60-ec2-instance-connect.conf
```
EC2 Instance Connect was successfully installed if the `AuthorizedKeysCommand` and `AuthorizedKeysCommandUser` lines contain the following values:
```
AuthorizedKeysCommand /opt/aws/bin/eic_run_authorized_keys %u %f
AuthorizedKeysCommandUser ec2-instance-connect
```
+ `AuthorizedKeysCommand` sets the `eic_run_authorized_keys` script to look up the keys from the instance metadata
+ `AuthorizedKeysCommandUser` sets the system user as `ec2-instance-connect`
**Note**
If you previously configured `AuthorizedKeysCommand` and `AuthorizedKeysCommandUser`, the EC2 Instance Connect installation will not change the values and you will not be able to use EC2 Instance Connect.
------
#### [ RHEL ]
**To install EC2 Instance Connect on an instance launched with Red Hat Enterprise Linux (RHEL)**
1. Connect to your instance using SSH.
Replace the example values in the following command with your values. Use the SSH key pair that was assigned to your instance when you launched it and the default username of the AMI that you used to launch your instance. For RHEL, the default username is `ec2-user` or `root`.
```
$ ssh -i my_ec2_private_key.pem ec2-user@ec2-a-b-c-d.us-west-2.compute.amazonaws.com
```
For more information about connecting to your instance, see [Connect to your Linux instance using an SSH client](connect-linux-inst-ssh.md).
1. If you use an HTTP or HTTPS proxy, you must set the `http_proxy` or `https_proxy` environment variables in the current shell session.
If you're not using a proxy, you can skip this step.
+ For an HTTP proxy server, run the following commands:
```
$ export http_proxy=http://hostname:port
$ export https_proxy=http://hostname:port
```
+ For an HTTPS proxy server, run the following commands:
```
$ export http_proxy=https://hostname:port
$ export https_proxy=https://hostname:port
```
1. Install the EC2 Instance Connect package on your instance by running the following commands.
The EC2 Instance Connect configuration files for RHEL are provided in a Red Hat Package Manager (RPM) package, with different RPM packages for RHEL 8 and RHEL 9 and for instance types that run on Intel/AMD (x86\$164) or ARM (AArch64).
Use the command block for your operating system and CPU architecture.
+ RHEL 8
Intel/AMD (x86\$164)
```
[ec2-user ~]$ mkdir /tmp/ec2-instance-connect
[ec2-user ~]$ curl https://amazon-ec2-instance-connect-us-west-2.s3.us-west-2.amazonaws.com/latest/linux_amd64/ec2-instance-connect-2.0.0-5.rhel8.x86_64.rpm -o /tmp/ec2-instance-connect/ec2-instance-connect.rpm
[ec2-user ~]$ curl https://amazon-ec2-instance-connect-us-west-2.s3.us-west-2.amazonaws.com/latest/linux_amd64/ec2-instance-connect-selinux-2.0.0-5.noarch.rpm -o /tmp/ec2-instance-connect/ec2-instance-connect-selinux.rpm
[ec2-user ~]$ sudo yum install -y /tmp/ec2-instance-connect/ec2-instance-connect.rpm /tmp/ec2-instance-connect/ec2-instance-connect-selinux.rpm
```
ARM (AArch64)
```
[ec2-user ~]$ mkdir /tmp/ec2-instance-connect
[ec2-user ~]$ curl https://amazon-ec2-instance-connect-us-west-2.s3.us-west-2.amazonaws.com/latest/linux_arm64/ec2-instance-connect-2.0.0-5.rhel8.aarch64.rpm -o /tmp/ec2-instance-connect/ec2-instance-connect.rpm
[ec2-user ~]$ curl https://amazon-ec2-instance-connect-us-west-2.s3.us-west-2.amazonaws.com/latest/linux_arm64/ec2-instance-connect-selinux-2.0.0-5.noarch.rpm -o /tmp/ec2-instance-connect/ec2-instance-connect-selinux.rpm
[ec2-user ~]$ sudo yum install -y /tmp/ec2-instance-connect/ec2-instance-connect.rpm /tmp/ec2-instance-connect/ec2-instance-connect-selinux.rpm
```
+ RHEL 9
Intel/AMD (x86\$164)
```
[ec2-user ~]$ mkdir /tmp/ec2-instance-connect
[ec2-user ~]$ curl https://amazon-ec2-instance-connect-us-west-2.s3.us-west-2.amazonaws.com/latest/linux_amd64/ec2-instance-connect-2.0.0-5.rhel9.x86_64.rpm -o /tmp/ec2-instance-connect/ec2-instance-connect.rpm
[ec2-user ~]$ curl https://amazon-ec2-instance-connect-us-west-2.s3.us-west-2.amazonaws.com/latest/linux_amd64/ec2-instance-connect-selinux-2.0.0-5.noarch.rpm -o /tmp/ec2-instance-connect/ec2-instance-connect-selinux.rpm
[ec2-user ~]$ sudo yum install -y /tmp/ec2-instance-connect/ec2-instance-connect.rpm /tmp/ec2-instance-connect/ec2-instance-connect-selinux.rpm
```
ARM (AArch64)
```
[ec2-user ~]$ mkdir /tmp/ec2-instance-connect
[ec2-user ~]$ curl https://amazon-ec2-instance-connect-us-west-2.s3.us-west-2.amazonaws.com/latest/linux_arm64/ec2-instance-connect-2.0.0-5.rhel9.aarch64.rpm -o /tmp/ec2-instance-connect/ec2-instance-connect.rpm
[ec2-user ~]$ curl https://amazon-ec2-instance-connect-us-west-2.s3.us-west-2.amazonaws.com/latest/linux_arm64/ec2-instance-connect-selinux-2.0.0-5.noarch.rpm -o /tmp/ec2-instance-connect/ec2-instance-connect-selinux.rpm
[ec2-user ~]$ sudo yum install -y /tmp/ec2-instance-connect/ec2-instance-connect.rpm /tmp/ec2-instance-connect/ec2-instance-connect-selinux.rpm
```
You should see the following new script in the `/opt/aws/bin/` folder:
```
eic_run_authorized_keys
```
1. (Optional) Verify that EC2 Instance Connect was successfully installed on your instance.
+ For RHEL 8:
```
[ec2-user ~]$ sudo less /lib/systemd/system/sshd.service.d/ec2-instance-connect.conf
```
+ For RHEL 9:
```
[ec2-user ~]$ sudo less /etc/ssh/sshd_config.d/60-ec2-instance-connect.conf
```
EC2 Instance Connect was successfully installed if the `AuthorizedKeysCommand` and `AuthorizedKeysCommandUser` lines contain the following values:
```
AuthorizedKeysCommand /opt/aws/bin/eic_run_authorized_keys %u %f
AuthorizedKeysCommandUser ec2-instance-connect
```
+ `AuthorizedKeysCommand` sets the `eic_run_authorized_keys` script to look up the keys from the instance metadata
+ `AuthorizedKeysCommandUser` sets the system user as `ec2-instance-connect`
**Note**
If you previously configured `AuthorizedKeysCommand` and `AuthorizedKeysCommandUser`, the EC2 Instance Connect installation will not change the values and you will not be able to use EC2 Instance Connect.
------
#### [ Ubuntu ]
**To install EC2 Instance Connect on an instance launched with Ubuntu 16.04 or later**
1. Connect to your instance using SSH.
Replace the example values in the following command with your values. Use the SSH key pair that was assigned to your instance when you launched it and use the default username of the AMI that you used to launch your instance. For an Ubuntu AMI, the username is `ubuntu`.
```
$ ssh -i my_ec2_private_key.pem ubuntu@ec2-a-b-c-d.us-west-2.compute.amazonaws.com
```
For more information about connecting to your instance, see [Connect to your Linux instance using an SSH client](connect-linux-inst-ssh.md).
1. (Optional) Ensure your instance has the latest Ubuntu AMI.
Run the following commands to update all the packages on your instance.
```
ubuntu:~$ sudo apt-get update
```
```
ubuntu:~$ sudo apt-get upgrade
```
1. Install the EC2 Instance Connect package on your instance.
```
ubuntu:~$ sudo apt-get install ec2-instance-connect
```
You should see three new scripts in the `/usr/share/ec2-instance-connect/` folder:
```
eic_curl_authorized_keys
eic_parse_authorized_keys
eic_run_authorized_keys
```
1. (Optional) Verify that EC2 Instance Connect was successfully installed on your instance.
```
ubuntu:~$ sudo less /lib/systemd/system/ssh.service.d/ec2-instance-connect.conf
```
EC2 Instance Connect was successfully installed if the `AuthorizedKeysCommand` and `AuthorizedKeysCommandUser` lines contain the following values:
```
AuthorizedKeysCommand /usr/share/ec2-instance-connect/eic_run_authorized_keys %%u %%f
AuthorizedKeysCommandUser ec2-instance-connect
```
+ `AuthorizedKeysCommand` sets the `eic_run_authorized_keys` script to look up the keys from the instance metadata
+ `AuthorizedKeysCommandUser` sets the system user as `ec2-instance-connect`
**Note**
If you previously configured `AuthorizedKeysCommand` and `AuthorizedKeysCommandUser`, the EC2 Instance Connect installation will not change the values and you will not be able to use EC2 Instance Connect.
------
# Connect to a Linux instance using EC2 Instance Connect
Connect to an instance
The following instructions explain how to connect to your Linux instance using EC2 Instance Connect through the Amazon EC2 console, the AWS CLI, or an SSH client.
When you connect to an instance using EC2 Instance Connect through the console or AWS CLI, the EC2 Instance Connect API automatically pushes an SSH public key to the [instance metadata](ec2-instance-metadata.md) where it remains for 60 seconds. An IAM policy attached to your user authorizes this action. If you prefer using your own SSH key, you can use an SSH client and explicitly push your SSH key to the instance using EC2 Instance Connect.
**Considerations**
After connecting to an instance using EC2 Instance Connect, the connection persists until the SSH session is terminated. The duration of the connection is not determined by the duration of your IAM credentials. If your IAM credentials expire, the connection continues to persist. When using the EC2 Instance Connect console experience, if your IAM credentials expire, terminate the connection by closing the browser page. When using your own SSH client and EC2 Instance Connect to push your key, you can set a SSH timeout value to terminate the SSH session automatically.
**Requirements**
Before you begin, be sure to review the [prerequisites](ec2-instance-connect-prerequisites.md).
**Topics**
+ [
## Connect using the Amazon EC2 console
](#ec2-instance-connect-connecting-console)
+ [
## Connect using the AWS CLI
](#connect-linux-inst-eic-cli-ssh)
+ [
## Connect using your own key and SSH client
](#ec2-instance-connect-connecting-aws-cli)
+ [
## Troubleshoot
](#ic-troubleshoot)
## Connect using the Amazon EC2 console
You can connect to an instance using EC2 Instance Connect through the Amazon EC2 console.
**Requirements**
To connect using the Amazon EC2 console, the instance must have either a public IPv4 or IPv6 address. If the instance only has a private IPv4 address, you can use the [ec2-instance-connect AWS CLI](#connect-linux-inst-eic-cli-ssh) to connect.
**To connect to your instance using the Amazon EC2 console**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation pane, choose **Instances**.
1. Select the instance and choose **Connect**.
1. Choose the **EC2 Instance Connect** tab.
1. Choose **Connect using a Public IP**.
1. If there is a choice, select the IP address to connect to. Otherwise, the IP address is selected automatically.
1. For **Username**, verify the username.
1. Choose **Connect** to establish a connection. An in-browser terminal window opens.
## Connect using the AWS CLI
You can use the [ec2-instance-connect](https://docs.aws.amazon.com/cli/latest/reference/ec2-instance-connect/index.html) AWS CLI to connect to your instance with an SSH client. EC2 Instance Connect attempts to establish a connection using an available IP address in a predefined order, based on the specified connection type. If an IP address isn't available, it automatically tries the next one in the order.Connection types
`auto` (default)
EC2 Instance Connect tries to connect using the instance's IP addresses in the following order and with the corresponding connection type:
1. Public IPv4: `direct`
1. Private IPv4: `eice`
1. IPv6: `direct`
`direct`
EC2 Instance Connect tries to connect using the instance's IP addresses in the following order:
1. Public IPv4
1. IPv6
1. Private IPv4 (it does not connect over an EC2 Instance Connect Endpoint)
`eice`
EC2 Instance Connect tries to connect using the instance's private IPv4 address and an [EC2 Instance Connect Endpoint](connect-with-ec2-instance-connect-endpoint.md).
**Note**
In the future, we might change the behavior of the `auto` connection type. To ensure that your desired connection type is used, we recommend that you explicitly set the `--connection-type` to either `direct` or `eice`.
**Requirements**
You must use AWS CLI version 2. For more information, see [Install or update to the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
**To connect to an instance using the instance ID**
If you only know the instance ID, and want to let EC2 Instance Connect determine the connection type to use when connecting to your instance, use the [ec2-instance-connect ssh](https://docs.aws.amazon.com/cli/latest/reference/ec2-instance-connect/ssh.html) CLI command with the instance ID.
```
aws ec2-instance-connect ssh --instance-id i-1234567890example
```
**To connect to an instance using the instance ID and an EC2 Instance Connect Endpoint**
If you want to connect to your instance over an [EC2 Instance Connect Endpoint](connect-with-ec2-instance-connect-endpoint.md), use the preceding command and also specify the `--connection-type` parameter with the `eice` value.
```
aws ec2-instance-connect ssh --instance-id i-1234567890example --connection-type eice
```
**To connect to an instance using the instance ID and your own private key file**
If you want to connect to your instance over an EC2 Instance Connect Endpoint using your own private key, specify the instance ID and the path to the private key file. Do not include *file://* in the path; the following example will fail: *file:///path/to/key*.
```
aws ec2-instance-connect ssh --instance-id i-1234567890example --private-key-file /path/to/key.pem
```
**Tip**
If you get an error when using these commands, make sure that you're using AWS CLI version 2, because the `ssh` command is only available in this major version. We also recommend regularly updating to the latest minor version of AWS CLI version 2 to access the latest features. For more information, see [About AWS CLI version 2](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html#welcome-versions-v2) in the *AWS Command Line Interface User Guide*.
## 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 EC2 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
+ Supported types: RSA (OpenSSH and SSH2) and ED25519
+ Supported lengths: 2048 and 4096
+ For more information, see [Create a key pair using a third-party tool and import the public key to Amazon EC2](create-key-pairs.md#how-to-generate-your-own-key-and-import-it-to-aws).
+ When connecting to an instance that has only 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 Direct Connect public virtual interface. To connect to the instance's private IP address, you can leverage services such as [Direct Connect](https://aws.amazon.com/directconnect/), [AWS Site-to-Site VPN](https://aws.amazon.com/vpn/), or [VPC peering](https://docs.aws.amazon.com/vpc/latest/peering/what-is-vpc-peering.html).
**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
```
1.
**Push your SSH public key to the instance**
Use the [https://docs.aws.amazon.com/cli/latest/reference/ec2-instance-connect/send-ssh-public-key.html](https://docs.aws.amazon.com/cli/latest/reference/ec2-instance-connect/send-ssh-public-key.html) command to push your SSH public key to the instance. If you launched your instance using AL2023 or Amazon Linux 2, the default username for the AMI is `ec2-user`. If you launched your instance using Ubuntu, the default username 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
```
1.
**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 username 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
```
The following example uses `timeout 3600` to set your SSH session to terminate after 1 hour. Processes started during the session may continue running on your instance after the session terminates.
```
timeout 3600 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:
+ [Troubleshoot issues connecting to your Amazon EC2 Linux instance](TroubleshootingInstancesConnecting.md)
+ [How do I troubleshoot issues connecting to my EC2 instance using EC2 Instance Connect?](https://repost.aws/knowledge-center/ec2-instance-connect-troubleshooting)
# Uninstall EC2 Instance Connect
To disable EC2 Instance Connect, connect to your Linux instance and uninstall the `ec2-instance-connect` package that is installed on the OS. If the `sshd` configuration matches what it was set to when you installed EC2 Instance Connect, uninstalling `ec2-instance-connect` also removes the `sshd` configuration. If you modified the `sshd` configuration after installing EC2 Instance Connect, you must update it manually.
------
#### [ Amazon Linux ]
You can uninstall EC2 Instance Connect on AL2023 and Amazon Linux 2 2.0.20190618 or later, where EC2 Instance Connect is preconfigured.
**To uninstall EC2 Instance Connect on an instance launched using Amazon Linux**
1. Connect to your instance using SSH. Specify the SSH key pair you used for your instance when you launched it and the default username for the AL2023 or Amazon Linux 2 AMI, which is `ec2-user`.
For example, the following **ssh** command connects to the instance with the public DNS name `ec2-a-b-c-d.us-west-2.compute.amazonaws.com`, using the key pair `my_ec2_private_key.pem`.
```
$ ssh -i my_ec2_private_key.pem ec2-user@ec2-a-b-c-d.us-west-2.compute.amazonaws.com
```
1. Uninstall the `ec2-instance-connect` package using the **yum** command.
```
[ec2-user ~]$ sudo yum remove ec2-instance-connect
```
------
#### [ Ubuntu ]
**To uninstall EC2 Instance Connect on an instance launched using an Ubuntu AMI**
1. Connect to your instance using SSH. Specify the SSH key pair you used for your instance when you launched it and the default username for the Ubuntu AMI, which is `ubuntu`.
For example, the following **ssh** command connects to the instance with the public DNS name `ec2-a-b-c-d.us-west-2.compute.amazonaws.com`, using the key pair `my_ec2_private_key.pem`.
```
$ ssh -i my_ec2_private_key.pem ubuntu@ec2-a-b-c-d.us-west-2.compute.amazonaws.com
```
1. Uninstall the `ec2-instance-connect` package using the **apt-get** command.
```
ubuntu:~$ sudo apt-get remove ec2-instance-connect
```
------
# Connect to your instances using a private IP address and EC2 Instance Connect Endpoint
Connect using a private IP and EC2 Instance Connect Endpoint
EC2 Instance Connect Endpoint allows you to connect securely to an instance from the internet, without using a bastion host, or requiring that your virtual private cloud (VPC) has direct internet connectivity.
**Benefits**
+ You can connect to your instances without requiring the instances to have a public IPv4 or IPv6 address. AWS charges for all public IPv4 addresses, including public IPv4 addresses associated with running instances and Elastic IP addresses. For more information, see the **Public IPv4 Address** tab on the [Amazon VPC pricing page](https://aws.amazon.com/vpc/pricing/).
+ You can connect to your instances from the internet without requiring that your VPC has direct internet connectivity through an [internet gateway](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Internet_Gateway.html).
+ You can control access to the creation and use of the EC2 Instance Connect Endpoints to connect to instances using [ IAM policies and permissions](permissions-for-ec2-instance-connect-endpoint.md).
+ All attempts to connect to your instances, both successful and unsuccessful, are logged to [CloudTrail](log-ec2-instance-connect-endpoint-using-cloudtrail.md).
**Pricing**
There is no additional cost for using EC2 Instance Connect Endpoints. If you use an EC2 Instance Connect Endpoint to connect to an instance in a different Availability Zone, there is an [additional charge for data transfer](https://aws.amazon.com/ec2/pricing/on-demand/#Data_Transfer_within_the_same_AWS_Region) across Availability Zones.
**Topics**
+ [
## How it works
](#how-eice-works)
+ [
## Considerations
](#ec2-instance-connect-endpoint-prerequisites)
+ [Permissions](permissions-for-ec2-instance-connect-endpoint.md)
+ [Security groups](eice-security-groups.md)
+ [
# Create an EC2 Instance Connect Endpoint
](create-ec2-instance-connect-endpoints.md)
+ [
# Modify an EC2 Instance Connect Endpoint
](modify-ec2-instance-connect-endpoint.md)
+ [
# Delete an EC2 Instance Connect Endpoint
](delete-ec2-instance-connect-endpoint.md)
+ [Connect to an instance](connect-using-eice.md)
+ [Log connections](log-ec2-instance-connect-endpoint-using-cloudtrail.md)
+ [Service-linked role](eice-slr.md)
+ [Quotas](eice-quotas.md)
## How it works
EC2 Instance Connect Endpoint is an identity-aware TCP proxy. The EC2 Instance Connect Endpoint Service establishes a private tunnel from your computer to the endpoint using the credentials for your IAM entity. Traffic is authenticated and authorized before it reaches your VPC.
You can [configure additional security group rules](eice-security-groups.md) to restrict inbound traffic to your instances. For example, you can use inbound rules to allow traffic on management ports only from the EC2 Instance Connect Endpoint.
You can configure route table rules to allow the endpoint to connect to any instance in any subnet of the VPC.
The following diagram shows how a user can connect to their instances from the internet using an EC2 Instance Connect Endpoint. First, create an **EC2 Instance Connect Endpoint** in subnet A. We create a network interface for the endpoint in the subnet, which serves as the entry point for traffic destined to your instances in the VPC. If the route table for subnet B allows traffic from subnet A, then you can use the endpoint to reach instances in subnet B.
![\[Overview of the EC2 Instance Connect Endpoint flow.\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/ec2-instance-connect-endpoint.png)
## Considerations
Before you begin, consider the following.
+ EC2 Instance Connect Endpoint is intended specifically for management traffic use cases, not for high volume data transfers. High volume data
transfers are throttled.
+ You can create an EC2 Instance Connect Endpoint to support traffic to an instance that has a private IPv4 address or IPv6 address. The IP address type of the endpoint must match the IP address of the instance. You can create an endpoint that supports all IP address types.
+ (Linux instances) If you use your own key pair, you can use any Linux AMI. Otherwise, your instance must have EC2 Instance Connect installed. For information about which AMIs include EC2 Instance Connect and how to install it on other supported AMIs, see [Install EC2 Instance Connect](ec2-instance-connect-set-up.md).
+ You can assign a security group to an EC2 Instance Connect Endpoint. Otherwise, we use the default security group for the VPC. The security group for an EC2 Instance Connect Endpoint must allow outbound traffic to the destination instances. For more information, see [Security groups for EC2 Instance Connect Endpoint](eice-security-groups.md).
+ You can configure an EC2 Instance Connect Endpoint to preserve the source IP addresses of clients when routing requests to the instances. Otherwise, the IP address of the network interface becomes the client IP address for all incoming traffic.
+ If you turn on client IP preservation, the security groups for the instances must allow traffic from the clients. Also, the instances must be in the same VPC as the EC2 Instance Connect Endpoint.
+ If you turn off client IP preservation, the security groups for the instances must allow traffic from the VPC. This is the default.
+ Client IP preservation is only supported on IPv4 EC2 Instance Connect Endpoints. To use client IP preservation, the IP address type of the EC2 Instance Connect Endpoint must be IPv4. Client IP preservation is not supported when the IP address type is dual-stack or IPv6.
+ The following instance types do not support client IP preservation: C1, CG1, CG2, G1, HI1, M1, M2, M3, and T1. If you turn on client IP preservation and attempt to connect to an instance with one of these instance types by using EC2 Instance Connect Endpoint, the connection fails.
+ Client IP preservation is not supported when traffic is routed through a transit gateway.
+ When you create an EC2 Instance Connect Endpoint, a service-linked role is automatically created for the Amazon EC2 service in AWS Identity and Access Management (IAM). Amazon EC2 uses the service-linked role to provision network interfaces in your account, which are required when creating EC2 Instance Connect Endpoints. For more information, see [Service-linked role for EC2 Instance Connect Endpoint](eice-slr.md).
+ You can create only 1 EC2 Instance Connect Endpoint per VPC and per subnet. For more information, see [Quotas for EC2 Instance Connect Endpoint](eice-quotas.md). If you need to create another EC2 Instance Connect Endpoint in a different Availability Zone within the same VPC, you must first delete the existing EC2 Instance Connect Endpoint. Otherwise, you'll receive a quota error.
+ Each EC2 Instance Connect Endpoint can support up to 20 concurrent connections.
+ The maximum duration for an established TCP connection is 1 hour (3,600 seconds). You can specify the maximum allowed duration in an IAM policy, which can be up to 3,600 seconds. For more information, see [Permissions to use EC2 Instance Connect Endpoint to connect to instances](permissions-for-ec2-instance-connect-endpoint.md#iam-OpenTunnel).
The duration of the connection is not determined by the duration of your IAM credentials. If your IAM credentials expire, the connection continues to persist until the specified maximum duration is reached. When you connect to an instance using the EC2 Instance Connect Endpoint console experience, set **Max tunnel duration (seconds)** to a value that is less than the duration of your IAM credentials. If your IAM credentials expire early, terminate the connection to your instance by closing the browser page.
# Grant permissions to use EC2 Instance Connect Endpoint
Permissions
By default, IAM entities don't have permission to create, describe, or modify EC2 Instance Connect Endpoints. An IAM administrator can create IAM policies that grant the permissions required to perform specific actions on the resources that they need.
For information about creating IAM policies, see [Creating IAM policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) in the *IAM User Guide*.
The following example policies show how you can control the permissions that users have to EC2 Instance Connect Endpoints.
**Topics**
+ [
## Permissions to create, describe, modify, and delete EC2 Instance Connect Endpoints
](#iam-CreateInstanceConnectEndpoint)
+ [
## Permissions to use EC2 Instance Connect Endpoint to connect to instances
](#iam-OpenTunnel)
+ [
## Permissions to connect only from a specific IP address range
](#iam-sourceip)
## Permissions to create, describe, modify, and delete EC2 Instance Connect Endpoints
Permissions to manage endpoints
To create and modify an EC2 Instance Connect Endpoint, users require permissions for the following actions:
+ `ec2:CreateInstanceConnectEndpoint`
+ `ec2:CreateNetworkInterface`
+ `ec2:CreateTags`
+ `ec2:ModifyInstanceConnectEndpoint`
+ `iam:CreateServiceLinkedRole`
To describe and delete EC2 Instance Connect Endpoints, users require permissions for the following actions:
+ `ec2:DescribeInstanceConnectEndpoints`
+ `ec2:DeleteInstanceConnectEndpoint`
You can create a policy that grants permission to create, describe, modify, and delete EC2 Instance Connect Endpoints in all subnets. Alternatively, you can restrict actions for specified subnets only by specifying the subnet ARNs as the allowed `Resource` or by using the `ec2:SubnetID` condition key. You can also use the `aws:ResourceTag` condition key to explicitly allow or deny endpoint creation with certain tags. For more information, see [Policies and permissions in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) in the *IAM User Guide*.
**Example IAM policy**
In the following example IAM policy, the `Resource` section grants permission to create, modify, and delete endpoints in all subnets, specified by the asterisk (`*`). The `ec2:Describe*` API actions do not support resource-level permissions. Therefore, the `*` wildcard is necessary in the `Resource` element.
## Permissions to use EC2 Instance Connect Endpoint to connect to instances
Permissions to use an endpoint to connect
The `ec2-instance-connect:OpenTunnel` action grants permission to establish a TCP connection to an instance to connect over the EC2 Instance Connect Endpoint. You can specify the EC2 Instance Connect Endpoint to use. Alternatively, a `Resource` with an asterisk (`*`) allows users to use any available EC2 Instance Connect Endpoint. You can also restrict access to instances based on the presence or absence of resource tags as condition keys.
**Conditions**
+ `ec2-instance-connect:remotePort` – The port on the instance that can be used to establish a TCP connection. When this condition key is used, attempting to connect to an instance on any other port other than the port specified in the policy results in a failure.
+ `ec2-instance-connect:privateIpAddress` – The destination private IP address associated with the instance that you want to establish a TCP connection with. You can specify a single IP address, such as `10.0.0.1/32`, or a range of IPs through CIDRs, such as `10.0.1.0/28`. When this condition key is used, attempting to connect to an instance with a different private IP address or outside the CIDR range results in a failure.
+ `ec2-instance-connect:maxTunnelDuration` – The maximum duration for an established TCP connection. The unit is seconds and the duration ranges from a minimum of 1 second to a maximum of 3,600 seconds (1 hour). If the condition is not specified, the default duration is set to 3,600 seconds (1 hour). Attempting to connect to an instance for longer than the specified duration in the IAM policy or for longer than the default maximum results in a failure. The connection is disconnected after the specified duration.
If `maxTunnelDuration` is specified in the IAM policy and the value specified is less than 3,600 seconds (the default), then you must specify `--max-tunnel-duration` in the command when connecting to an instance. For information about how to connect to an instance, see [Connect to an Amazon EC2 instance using EC2 Instance Connect Endpoint](connect-using-eice.md).
You can also grant a user access to establish connections to instances based on the presence of resource tags on the EC2 Instance Connect Endpoint. For more information, see [Policies and permissions in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) in the *IAM User Guide*.
For Linux instances, the `ec2-instance-connect:SendSSHPublicKey` action grants permission to push the public key to an instance. The `ec2:osuser` condition specifies the name of the OS (operating system) user that can push the public key to an instance. Use the [default username for the AMI](connection-prereqs-general.md#connection-prereqs-get-info-about-instance) that you used to launch the instance. For more information, see [Grant IAM permissions for EC2 Instance Connect](ec2-instance-connect-configure-IAM-role.md).
**Example IAM policy**
The following example IAM policies allow an IAM principal to connect to an instance using only the specified EC2 Instance Connect Endpoint, identified by the specified endpoint ID `eice-123456789abcdef`. The connection is successfully established only if all the conditions are satisfied.
**Note**
The `ec2:Describe*` API actions do not support resource-level permissions. Therefore, the `*` wildcard is necessary in the `Resource` element.
------
#### [ Linux ]
This example evaluates if the connection to the instance is established on —port 22 (SSH), if the private IP address of the instance lies within the range of `10.0.1.0/31` (between `10.0.1.0` and `10.0.1.1`), and the `maxTunnelDuration` is less than or equal to `3600` seconds. The connection is disconnected after `3600` seconds (1 hour).
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [{
"Sid": "EC2InstanceConnect",
"Action": "ec2-instance-connect:OpenTunnel",
"Effect": "Allow",
"Resource": "arn:aws:ec2:us-east-1:111122223333:instance-connect-endpoint/eice-123456789abcdef",
"Condition": {
"NumericEquals": {
"ec2-instance-connect:remotePort": "22"
},
"IpAddress": {
"ec2-instance-connect:privateIpAddress": "10.0.1.0/31"
},
"NumericLessThanEquals": {
"ec2-instance-connect:maxTunnelDuration": "3600"
}
}
},
{
"Sid": "SSHPublicKey",
"Effect": "Allow",
"Action": "ec2-instance-connect:SendSSHPublicKey",
"Resource": "*",
"Condition": {
"StringEquals": {
"ec2:osuser": "ami-username"
}
}
},
{
"Sid": "Describe",
"Action": [
"ec2:DescribeInstances",
"ec2:DescribeInstanceConnectEndpoints"
],
"Effect": "Allow",
"Resource": "*"
}
]
}
```
------
------
#### [ Windows ]
This example evaluates if the connection to the instance is established on port 3389 (RDP), if the private IP address of the instance lies within the range of `10.0.1.0/31` (between `10.0.1.0` and `10.0.1.1`), and the `maxTunnelDuration` is less than or equal to `3600` seconds. The connection is disconnected after `3600` seconds (1 hour).
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [{
"Sid": "EC2InstanceConnect",
"Action": "ec2-instance-connect:OpenTunnel",
"Effect": "Allow",
"Resource": "arn:aws:ec2:us-east-1:111122223333:instance-connect-endpoint/eice-123456789abcdef",
"Condition": {
"NumericEquals": {
"ec2-instance-connect:remotePort": "3389"
},
"IpAddress": {
"ec2-instance-connect:privateIpAddress": "10.0.1.0/31"
},
"NumericLessThanEquals": {
"ec2-instance-connect:maxTunnelDuration": "3600"
}
}
},
{
"Sid": "Describe",
"Action": [
"ec2:DescribeInstances",
"ec2:DescribeInstanceConnectEndpoints"
],
"Effect": "Allow",
"Resource": "*"
}
]
}
```
------
------
## Permissions to connect only from a specific IP address range
The following example IAM policy allows an IAM principal to connect to an instance on condition they are connecting from an IP address within the IP address range specified in the policy. If the IAM principal calls `OpenTunnel` from an IP address not within `192.0.2.0/24` (the example IP address range in this policy), the response is `Access Denied`. For more information, see [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourceip](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourceip) in the *IAM User Guide*.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": "ec2-instance-connect:OpenTunnel",
"Resource": "arn:aws:ec2:us-east-1:111122223333:instance-connect-endpoint/eice-123456789abcdef",
"Condition": {
"IpAddress": {
"aws:SourceIp": "192.0.2.0/24"
},
"NumericEquals": {
"ec2-instance-connect:remotePort": "22"
}
}
},
{
"Sid": "SSHPublicKey",
"Effect": "Allow",
"Action": "ec2-instance-connect:SendSSHPublicKey",
"Resource": "*",
"Condition": {
"StringEquals": {
"ec2:osuser": "ami-username"
}
}
},
{
"Effect": "Allow",
"Action": [
"ec2:DescribeInstances",
"ec2:DescribeInstanceConnectEndpoints"
],
"Resource": "*"
}
]
}
```
------
# Security groups for EC2 Instance Connect Endpoint
Security groups
A security group controls the traffic that is allowed to reach and leave the resources that it is associated with. For example, we deny traffic to and from an Amazon EC2 instance unless it is specifically allowed by the security groups associated with the instance.
The following examples show you how to configure the security group rules for the EC2 Instance Connect Endpoint and the target instances.
**Topics**
+ [
## EC2 Instance Connect Endpoint security group rules
](#eice-security-group-rules)
+ [
## Target instance security group rules
](#resource-security-group-rules)
## EC2 Instance Connect Endpoint security group rules
The security group rules for an EC2 Instance Connect Endpoint must allow outbound traffic destined for the target instances to leave the endpoint. You can specify either the instance security group or the IPv4 or IPv6 address range of the VPC as the destination.
Traffic to the endpoint originates from the EC2 Instance Connect Endpoint Service, and it is allowed regardless of the inbound rules for the endpoint security group. To control who can use EC2 Instance Connect Endpoint to connect to an instance, use an IAM policy. For more information, see [Permissions to use EC2 Instance Connect Endpoint to connect to instances](permissions-for-ec2-instance-connect-endpoint.md#iam-OpenTunnel).
**Example outbound rule: Security group referencing**
The following example uses security group referencing, which means that the destination is a security group associated with the target instances. This rule allows outbound traffic from the endpoint to all instances that use this security group.
| Protocol | Destination | Port range | Comment |
| --- | --- | --- | --- |
| TCP | ID of instance security group | 22 | Allows outbound SSH traffic to all instances associated with the instance security group |
**Example outbound rule: IPv4 address range**
The following example allows outbound traffic to the specified IPv4 address range. The IPv4 addresses of an instance is assigned from its subnet, so you can use the IPv4 address range of the VPC.
| Protocol | Destination | Port range | Comment |
| --- | --- | --- | --- |
| TCP | VPC IPv4 CIDR | 22 | Allows outbound SSH traffic to the VPC |
**Example outbound rule: IPv6 address range**
The following example allows outbound traffic to the specified IPv6 address range. The IPv6 addresses of an instance is assigned from its subnet, so you can use the IPv6 address range of the VPC.
| Protocol | Destination | Port range | Comment |
| --- | --- | --- | --- |
| TCP | VPC IPv6 CIDR | 22 | Allows outbound SSH traffic to the VPC |
## Target instance security group rules
The security group rules for target instances must allow inbound traffic from the EC2 Instance Connect Endpoint. You can specify either the endpoint security group or an IPv4 or IPv6 address range as the source. If you specify an IPv4 address range, the source depends on whether client IP preservation is off or on. For more information, see [Considerations](connect-with-ec2-instance-connect-endpoint.md#ec2-instance-connect-endpoint-prerequisites).
Because security groups are stateful, the response traffic is allowed to leave the VPC regardless of the outbound rules for the instance security group.
**Example inbound rule: Security group referencing**
The following example uses security group referencing, which means that the source is the security group associated with the endpoint. This rule allows inbound SSH traffic from the endpoint to all instances that use this security group, whether client IP preservation is on or off. If there are no other inbound security group rules for SSH, then the instances accept SSH traffic only from the endpoint.
| Protocol | Source | Port range | Comment |
| --- | --- | --- | --- |
| TCP | ID of endpoint security group | 22 | Allows inbound SSH traffic from the resources associated with the endpoint security group |
**Example inbound rule: Client IP preservation off**
The following example allows inbound SSH traffic from the specified IPv4 address range. Because client IP preservation is off, the source IPv4 address is the address of the endpoint network interface. The address of the endpoint network interface is assigned from its subnet, so you can use the IPv4 address range of the VPC to allow connections to all instances in the VPC.
| Protocol | Source | Port range | Comment |
| --- | --- | --- | --- |
| TCP | VPC IPv4 CIDR | 22 | Allows inbound SSH traffic from the VPC |
**Example inbound rule: Client IP preservation on**
The following example allows inbound SSH traffic from the specified IPv4 address range. Because client IP preservation is on, the source IPv4 address is the address of the client.
| Protocol | Source | Port range | Comment |
| --- | --- | --- | --- |
| TCP | Public IPv4 address range | 22 | Allows inbound traffic from the specified client IPv4 address range |
# Create an EC2 Instance Connect Endpoint
You can create an EC2 Instance Connect Endpoint to allow secure connection to your instances.
**Considerations**
+ **Shared subnets** – You can create an EC2 Instance Connect Endpoint in a subnet shared with you. However, you can't use EC2 Instance Connect Endpoints that the VPC owner created in a subnet shared with you.
+ **IP address types** – EC2 Instance Connect Endpoints support the following address types, which must be compatible with your subnet:
+ `ipv4` – Connect only to EC2 instances with private IPv4 addresses.
+ `dualstack` – Connect to EC2 instances with either private IPv4 addresses or IPv6 addresses.
+ `ipv6` – Connect only to EC2 instances with IPv6 addresses.
**Prerequisites**
You must have the required IAM permissions to create an EC2 Instance Connect Endpoint. For more information, see [Permissions to create, describe, modify, and delete EC2 Instance Connect Endpoints](permissions-for-ec2-instance-connect-endpoint.md#iam-CreateInstanceConnectEndpoint).
------
#### [ Console ]
**To create an EC2 Instance Connect Endpoint**
1. Open the Amazon VPC console at [https://console.aws.amazon.com/vpc/](https://console.aws.amazon.com/vpc/).
1. In the left navigation pane, choose **Endpoints**.
1. Choose **Create endpoint**, and then specify the endpoint settings as follows:
1. (Optional) For **Name tag**, enter a name for the endpoint.
1. For **Type**, choose **EC2 Instance Connect Endpoint**.
1. Under **Network settings**, for **VPC**, select the VPC that has the target instances.
1. (Optional) To preserve client IP addresses, expand **Additional settings** and select the **Preserve Client IP** check box. Otherwise, the default is to use the endpoint network interface as the client IP address.
**Note**
This option is only available when the endpoint's IP address type is configured as IPv4.
1. (Optional) For **Security groups**, select the security group to associate with the endpoint. Otherwise, the default is to use the default security group for the VPC. For more information, see [Security groups for EC2 Instance Connect Endpoint](eice-security-groups.md).
1. For **Subnet**, select the subnet in which to create the endpoint.
1. For **IP address type**, choose the IP address type for the endpoint. Choose **Dualstack** if you need to support both IPv4 and IPv6 connections to your instances. Choose **IPv4** if you need to support client IP preservation.
1. (Optional) To add a tag, choose **Add new tag** and enter the tag key and the tag value.
1. Review your settings and then choose **Create endpoint**.
The initial status of the endpoint is **Pending**. Before you can connect to an instance using this endpoint, you must wait until the endpoint status is **Available**. This can take a few minutes.
1. To connect to an instance using your endpoint, see [Connect to an instance](connect-using-eice.md).
------
#### [ AWS CLI ]
**To create an EC2 Instance Connect Endpoint**
Use the [https://docs.aws.amazon.com/cli/latest/reference/ec2/create-instance-connect-endpoint.html](https://docs.aws.amazon.com/cli/latest/reference/ec2/create-instance-connect-endpoint.html) command.
```
aws ec2 create-instance-connect-endpoint \
--subnet-id subnet-0123456789example
```
To specify the type of traffic that the endpoint supports, include the `--ip-address-type` parameter. Valid values are `ipv4`, `dualstack`, or `ipv6`. The subnet must support the IP address type that you specify. When the `--ip-address-type` parameter is omitted, the default value is determined by the IP address type supported by the subnet.
```
aws ec2 create-instance-connect-endpoint \
--subnet-id subnet-0123456789example \
--ip-address-type ipv4
```
The following is example output.
```
{
"OwnerId": "111111111111",
"InstanceConnectEndpointId": "eice-0123456789example",
"InstanceConnectEndpointArn": "arn:aws:ec2:us-east-1:111111111111:instance-connect-endpoint/eice-0123456789example",
"State": "create-complete",
"StateMessage": "",
"DnsName": "eice-0123456789example.0123abcd.ec2-instance-connect-endpoint.us-east-1.amazonaws.com",
"FipsDnsName": "eice-0123456789example.0123abcd.fips.ec2-instance-connect-endpoint.us-east-1.amazonaws.com",
"NetworkInterfaceIds": [
"eni-0123abcd"
],
"VpcId": "vpc-0123abcd",
"AvailabilityZone": "us-east-1a",
"AvailabilityZoneId": "use1-az4",
"CreatedAt": "2023-04-07T15:43:53.000Z",
"SubnetId": "subnet-0123abcd",
"PreserveClientIp": false,
"SecurityGroupIds": [
"sg-0123abcd"
],
"Tags": [],
"IpAddressType": "ipv4"
}
```
**To monitor the creation status**
The initial value for the `State` field is `create-in-progress`. Before you can connect to an instance using this endpoint, wait until the state is `create-complete`. Use the [https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instance-connect-endpoints.html](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instance-connect-endpoints.html) command to monitor the status of the EC2 Instance Connect Endpoint. The `--query` parameter filters the results to the `State` field.
```
aws ec2 describe-instance-connect-endpoints --instance-connect-endpoint-ids eice-0123456789example --query InstanceConnectEndpoints[*].State --output text
```
The following is example output.
```
create-complete
```
------
#### [ PowerShell ]
**To create the EC2 Instance Connect Endpoint**
Use the [https://docs.aws.amazon.com/powershell/latest/reference/items/New-EC2InstanceConnectEndpoint.html](https://docs.aws.amazon.com/powershell/latest/reference/items/New-EC2InstanceConnectEndpoint.html) cmdlet.
```
New-EC2InstanceConnectEndpoint -SubnetId subnet-0123456789example
```
To specify the type of traffic that the endpoint supports, include the `-IpAddressType` parameter. Valid values are `ipv4`, `dualstack`, or `ipv6`. The subnet must support the IP address type that you specify. When the `-IpAddressType` parameter is omitted, the default value is determined by the IP address type supported by the subnet.
```
New-EC2InstanceConnectEndpoint -SubnetId subnet-0123456789example -IpAddressType ipv4
```
The following is example output.
```
OwnerId : 111111111111
InstanceConnectEndpointId : eice-0123456789example
InstanceConnectEndpointArn : arn:aws:ec2:us-east-1:111111111111:instance-connect-endpoint/eice-0123456789example
State : create-complete
StateMessage :
DnsName : eice-0123456789example.0123abcd.ec2-instance-connect-endpoint.us-east-1.amazonaws.com
FipsDnsName : eice-0123456789example.0123abcd.fips.ec2-instance-connect-endpoint.us-east-1.amazonaws.com
NetworkInterfaceIds : {eni-0123abcd}
VpcId : vpc-0123abcd
AvailabilityZone : us-east-1a
AvailabilityZoneId : use1-az4
CreatedAt : 4/7/2023 3:43:53 PM
SubnetId : subnet-0123abcd
PreserveClientIp : False
SecurityGroupIds : {sg-0123abcd}
Tags : {}
IpAddressType : ipv4
```
**To monitor the creation status**
The initial value for the `State` field is `create-in-progress`. Before you can connect to an instance using this endpoint, wait until the state is `create-complete`. Use the [https://docs.aws.amazon.com/powershell/latest/reference/items/Get-EC2InstanceConnectEndpoint.html](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-EC2InstanceConnectEndpoint.html) cmdlet to monitor the status of the EC2 Instance Connect Endpoint. `.State.Value` filters the results to the `State` field.
```
(Get-EC2InstanceConnectEndpoint -InstanceConnectEndpointId "eice-0123456789example").State.Value
```
The following is example output.
```
create-complete
```
------
# Modify an EC2 Instance Connect Endpoint
You can modify existing EC2 Instance Connect Endpoints using the AWS CLI or an SDK. The Amazon EC2 console doesn't support endpoint modification.
Before you begin, you must have the required IAM permissions. For more information, see [Permissions to create, describe, modify, and delete EC2 Instance Connect Endpoints](permissions-for-ec2-instance-connect-endpoint.md#iam-CreateInstanceConnectEndpoint).
## Parameters you can modify
You can modify the following EC2 Instance Connect Endpoint parameters:
**Security groups**
You can specify new security groups for the EC2 Instance Connect Endpoint. The new security groups replace the current security groups.
When modifying the security groups, you must specify:
+ At least one security group, even if it's just the default security group in the VPC.
+ The IDs of the security groups, not the names.
**IP address type**
You can specify a new IP address type for the EC2 Instance Connect Endpoint.
Valid values: `ipv4` \$1 `dualstack` \$1 `ipv6`
**Preserve client IP setting**
You can specify whether to preserve the client IP address as the source.
Preserving the client IP is only supported on IPv4 EC2 Instance Connect Endpoints. When enabling `PreserveClientIp`, either the endpoint's existing IP address type must be `ipv4`, or if modifying the IP address type in the same request, the new value must be `ipv4`.
------
#### [ AWS CLI ]
**To modify an EC2 Instance Connect Endpoint**
Use the [https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-connect-endpoint.html](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-connect-endpoint.html) command and specify the EC2 Instance Connect Endpoint and the parameters to modify. The following example modifies all the parameters in a single request.
```
aws ec2 modify-instance-connect-endpoint \
--instance-connect-endpoint-id eice-0123456789example \
--security-group-ids sg-0123456789example \
--ip-address-type dualstack \
--no-preserve-client-ip
```
The following is example output.
```
{
"Return": true
}
```
**To monitor the update status**
During modification, the EC2 Instance Connect Endpoint status changes to `update-in-progress`. The update process runs asynchronously and completes with either an `update-complete` or `update-failed` status. The endpoint uses its old configuration until the status changes to `update-complete`.
Use the [https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instance-connect-endpoints.html](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instance-connect-endpoints.html) command to monitor the update status. The `--query` parameter filters the results to the `State` field.
```
aws ec2 describe-instance-connect-endpoints \
--instance-connect-endpoint-ids eice-0123456789example \
--query InstanceConnectEndpoints[*].State --output text
```
The following is example output.
```
update-complete
```
------
#### [ PowerShell ]
**To modify an EC2 Instance Connect Endpoint**
Use the [https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2InstanceConnectEndpoint.html](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2InstanceConnectEndpoint.html) cmdlet and specify the EC2 Instance Connect Endpoint and the parameters to modify. The following example modifies all the parameters in a single request.
```
Edit-EC2InstanceConnectEndpoint `
-InstanceConnectEndpointId eice-0123456789example `
-SecurityGroupIds sg-0123456789example `
-IpAddressType dualstack `
-PreserveClientIp $false
```
The following is example output.
```
True
```
**To monitor the update status**
During modification, the EC2 Instance Connect Endpoint status changes to `update-in-progress`. The update process runs asynchronously and completes with either an `update-complete` or `update-failed` status. The endpoint uses its old configuration until the status changes to `update-complete`.
Use the [https://docs.aws.amazon.com/powershell/latest/reference/items/Get-EC2InstanceConnectEndpoint.html](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-EC2InstanceConnectEndpoint.html) command to monitor the update status. `.State.Value` filters the results to the `State` field.
```
(Get-EC2InstanceConnectEndpoint -InstanceConnectEndpointId "eice-0123456789example").State.Value
```
The following is example output.
```
update-complete
```
------
# Delete an EC2 Instance Connect Endpoint
When you are finished with an EC2 Instance Connect Endpoint, you can delete it.
You must have the required IAM permissions to create an EC2 Instance Connect Endpoint. For more information, see [Permissions to create, describe, modify, and delete EC2 Instance Connect Endpoints](permissions-for-ec2-instance-connect-endpoint.md#iam-CreateInstanceConnectEndpoint).
When you delete an EC2 Instance Connect Endpoint using the console, it enters the **Deleting** state. If deletion is successful, the deleted endpoint no longer appears. If deletion fails, the state is **delete-failed** and **Status message** provides the failure reason.
When you delete an EC2 Instance Connect Endpoint using the AWS CLI, it enters the `delete-in-progress` state. If deletion is successful, it enters the `delete-complete` state. If deletion fails, the state is `delete-failed` and `StateMessage` provides the failure reason.
------
#### [ Console ]
**To delete an EC2 Instance Connect Endpoint**
1. Open the Amazon VPC console at [https://console.aws.amazon.com/vpc/](https://console.aws.amazon.com/vpc/).
1. In the left navigation pane, choose **Endpoints**.
1. Select the endpoint.
1. Choose **Actions**, **Delete VPC endpoints**.
1. When prompted for confirmation, enter **delete**.
1. Choose **Delete**.
------
#### [ AWS CLI ]
**To delete an EC2 Instance Connect Endpoint**
Use the [https://docs.aws.amazon.com/cli/latest/reference/ec2/delete-instance-connect-endpoint.html](https://docs.aws.amazon.com/cli/latest/reference/ec2/delete-instance-connect-endpoint.html) command and specify the ID of the EC2 Instance Connect Endpoint to delete.
```
aws ec2 delete-instance-connect-endpoint --instance-connect-endpoint-id eice-03f5e49b83924bbc7
```
The following is example output.
```
{
"InstanceConnectEndpoint": {
"OwnerId": "111111111111",
"InstanceConnectEndpointId": "eice-0123456789example",
"InstanceConnectEndpointArn": "arn:aws:ec2:us-east-1:111111111111:instance-connect-endpoint/eice-0123456789example",
"State": "delete-in-progress",
"StateMessage": "",
"NetworkInterfaceIds": [],
"VpcId": "vpc-0123abcd",
"AvailabilityZone": "us-east-1d",
"AvailabilityZoneId": "use1-az2",
"CreatedAt": "2023-02-07T12:05:37+00:00",
"SubnetId": "subnet-0123abcd"
}
}
```
------
#### [ PowerShell ]
**To delete an EC2 Instance Connect Endpoint**
Use the [https://docs.aws.amazon.com/cli/latest/reference/ec2/delete-instance-connect-endpoint.html](https://docs.aws.amazon.com/cli/latest/reference/ec2/delete-instance-connect-endpoint.html) cmdlet and specify the ID of the EC2 Instance Connect Endpoint to delete.
```
Remove-EC2InstanceConnectEndpoint -InstanceConnectEndpointId eice-03f5e49b83924bbc7
```
The following is example output.
```
@{
InstanceConnectEndpoint = @{
OwnerId = "111111111111"
InstanceConnectEndpointId = "eice-0123456789example"
InstanceConnectEndpointArn = "arn:aws:ec2:us-east-1:111111111111:instance-connect-endpoint/eice-0123456789example"
State = "delete-in-progress"
StateMessage = ""
NetworkInterfaceIds = @()
VpcId = "vpc-0123abcd"
AvailabilityZone = "us-east-1d"
AvailabilityZoneId = "use1-az2"
CreatedAt = "2023-02-07T12:05:37+00:00"
SubnetId = "subnet-0123abcd"
}
}
```
------
# Connect to an Amazon EC2 instance using EC2 Instance Connect Endpoint
Connect to an instance
You can use EC2 Instance Connect Endpoint to connect to an Amazon EC2 instance that supports SSH or RDP.
**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](permissions-for-ec2-instance-connect-endpoint.md#iam-OpenTunnel).
+ The EC2 Instance Connect Endpoint must be in one of the following states:
+ **create-complete** for a new endpoint
+ **update-in-progress**, **update-complete**, or **update-failed** for an existing endpoint being modified. When modifying an endpoint, it continues using its original configuration until the status changes to **update-complete**.
If your VPC doesn't have an EC2 Instance Connect Endpoint, you can create one. For more information, see [Create an EC2 Instance Connect Endpoint](create-ec2-instance-connect-endpoints.md).
+ The EC2 Instance Connect Endpoint IP address type must be compatible with the IP address type of the instance. If your endpoint IP address type is dual-stack, then it can work for both IPv4 and IPv6 addresses.
+ (Linux instances) To use the Amazon 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](ec2-instance-connect-set-up.md).
+ 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](eice-security-groups.md#resource-security-group-rules).
**Topics**
+ [
## Connect to your Linux instance using the Amazon EC2 console
](#connect-using-the-ec2-console)
+ [
## Connect to your Linux instance using SSH
](#eic-connect-using-ssh)
+ [
## Connect to your Linux instance with its instance ID using the AWS CLI
](#eic-connect-using-cli)
+ [
## Connect to your Windows instance using RDP
](#eic-connect-using-rdp)
+ [
## Troubleshoot
](#troubleshoot-eice)
## Connect to your Linux instance using the Amazon EC2 console
(Linux) Connect using the console
You can connect to an instance using the Amazon EC2 console (a browser-based client) as follows.
**To connect to your instance using the Amazon EC2 console**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation pane, choose **Instances**.
1. Select the instance, and then choose **Connect**.
1. Choose the **EC2 Instance Connect** tab.
1. For **Connection type**, choose **Connect using a Private IP**.
1. Choose either **Private IPv4 address** or **IPv6 address**. The options are available based on the IP addresses assigned to your instance. If an option is greyed out, your instance does not have an IP address of that type assigned to it.
1. For **EC2 Instance Connect Endpoint**, choose the ID of the EC2 Instance Connect Endpoint.
**Note**
The EC2 Instance Connect Endpoint must be compatible with the IP address you chose in the previous step. If your endpoint IP address type is dual-stack, then it can work for both IPv4 and IPv6 addresses. For more information, see [Create an EC2 Instance Connect Endpoint](create-ec2-instance-connect-endpoints.md).
1. For **Username**, if the AMI that you used to launch the instance uses a username other than `ec2-user`, enter the correct username.
1. 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.
1. Choose **Connect**. This opens a terminal window for your instance.
## Connect to your Linux instance using SSH
(Linux) Connect 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. You can specify your instance ID, a private IPv4 address, or an IPv6 address.
For information about using the AWS CLI to connect to your instance using SSH, see [Connect using the AWS CLI](ec2-instance-connect-methods.md#connect-linux-inst-eic-cli-ssh).
The following examples use [OpenSSH](https://www.openssh.com/). 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 [https://docs.aws.amazon.com/cli/latest/reference/ec2-instance-connect/open-tunnel.html](https://docs.aws.amazon.com/cli/latest/reference/ec2-instance-connect/open-tunnel.html) 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-1234567890abcdef0 \
-o ProxyCommand='aws ec2-instance-connect open-tunnel --instance-id i-1234567890abcdef0'
```
For:
+ `-i` – Specify the key pair that was used to launch the instance.
+ `ec2-user@i-1234567890abcdef0` – Specify the username of the AMI that was used to launch the instance, and the instance ID. For instances with an IPv6 address, you must specify the IPv6 address instead of 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. For instances with an IPv6 address, replace `--instance-id i-1234567890abcdef0` with `--private-ip-address 2001:db8::1234:5678:1.2.3.4`.
### Multi-connection
To allow multiple connections to an instance, first run the [https://docs.aws.amazon.com/cli/latest/reference/ec2-instance-connect/open-tunnel.html](https://docs.aws.amazon.com/cli/latest/reference/ec2-instance-connect/open-tunnel.html) 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-1234567890abcdef0 \
--local-port 8888
```
Expected output:
```
Listening for connections on port 8888.
```
1. 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 with its instance ID using the AWS CLI
(Linux) Connect with the instance ID using the AWS CLI
If you only know your instance ID, you can use the [ec2-instance-connect ssh](https://docs.aws.amazon.com/cli/latest/reference/ec2-instance-connect/ssh.html) AWS CLI command to connect to your instance using an SSH client. For more information, see [Connect using the AWS CLI](ec2-instance-connect-methods.md#connect-linux-inst-eic-cli-ssh).
**Prerequisites**
+ Install AWS CLI version 2 and configure it using your credentials. For more information, see [Install or update to the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) and [Configure the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html) in the *AWS Command Line Interface User Guide*.
+ Alternatively, open AWS CloudShell and run AWS 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 ssh](https://docs.aws.amazon.com/cli/latest/reference/ec2-instance-connect/ssh.html) CLI command, and specify the `ssh` command, the instance ID, and the `--connection-type` parameter with the `eice` value to use an EC2 Instance Connect Endpoint. If the instance only has an IPv6 address, you must also include the `--instance-ip` parameter with the IPv6 address.
+ If the instance has a private IPv4 address (it can also have an IPv6 address) use the following command and parameters:
```
aws ec2-instance-connect ssh \
--instance-id i-1234567890example \
--os-user ec2-user \
--connection-type eice
```
+ If the instance only has an IPv6 address, include the `--instance-ip` parameter with the IPv6 address:
```
aws ec2-instance-connect ssh \
--instance-id i-1234567890example \
--instance-ip 2001:db8::1234:5678:1.2.3.4 \
--os-user ec2-user \
--connection-type eice
```
**Tip**
If you get an error, 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](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html#welcome-versions-v2) in the *AWS Command Line Interface User Guide*.
## Connect to your Windows instance using RDP
(Windows) Connect using RDP
You can use Remote Desktop Protocol (RDP) over EC2 Instance Connect Endpoint to connect to a Windows instance without a public IPv4 address or public DNS name.
**To connect to your Windows instance using an RDP client**
1. Complete Steps 1 – 8 in [Connect to your Windows instance using RDP](connect-rdp.md). After downloading the RDP desktop file at Step 8, you'll get an **Unable to connect** message, which is to be expected because your instance does not have a public IP address.
1. Run the following command to establish a private tunnel to the VPC in which the instance is located. `--remote-port` must be `3389` because RDP uses port 3389 by default.
```
aws ec2-instance-connect open-tunnel \
--instance-id i-1234567890abcdef0 \
--remote-port 3389 \
--local-port any-port
```
1. In your **Downloads** folder, find the RDP desktop file that you downloaded, and drag it onto the RDP client window.
1. Right-click the RDP desktop file and choose **Edit**.
1. In the **Edit PC** window, for **PC name** (the instance to connect to), enter `localhost:local-port`, where `local-port` uses the same value as you specified in Step 2, and then choose **Save**.
Note that the following screenshot of the **Edit PC** window is from Microsoft Remote Desktop on a Mac. If you are using a Windows client, the window might be different.
![\[The RDP client with the example "localhost:5555" in the PC name field.\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/ec2-instance-connect-endpoint-rdp.png)
1. In the RDP client, right-click the PC (that you just configured) and choose **Connect** to connect to your instance.
1. At the prompt, enter the decrypted password for the administrator account.
## 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](eice-security-groups.md).
+ 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](permissions-for-ec2-instance-connect-endpoint.md).
For more troubleshooting tips for Linux instances, see [Troubleshoot issues connecting to your Amazon EC2 Linux instance](TroubleshootingInstancesConnecting.md). For troubleshooting tips for Windows instances, see [Troubleshoot issues connecting to your Amazon EC2 Windows instance](troubleshoot-connect-windows-instance.md).
### 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 [https://docs.aws.amazon.com/cli/latest/reference/ec2-instance-connect/open-tunnel.html](https://docs.aws.amazon.com/cli/latest/reference/ec2-instance-connect/open-tunnel.html) in the *AWS CLI Command Reference*.
# Log connections established over EC2 Instance Connect Endpoint
Log connections
You can log resource operations and audit connections established over the EC2 Instance Connect Endpoint with AWS CloudTrail logs.
For more information about using AWS CloudTrail with Amazon EC2, see [Log Amazon EC2 API calls using AWS CloudTrail](monitor-with-cloudtrail.md).
## Log EC2 Instance Connect Endpoint API calls with AWS CloudTrail
Log EC2 Instance Connect Endpoint API calls
EC2 Instance Connect Endpoint resource operations are logged to CloudTrail as management events. When the following API calls are made, the activity is recorded as a CloudTrail event in **Event history**:
+ `CreateInstanceConnectEndpoint`
+ `DescribeInstanceConnectEndpoints`
+ `DeleteInstanceConnectEndpoint`
You can view, search, and download recent events in your AWS account. For more information, see [Viewing events with CloudTrail Event history](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/view-cloudtrail-events.html) in the *AWS CloudTrail User Guide*.
## Use AWS CloudTrail to audit users who connect to an instance using EC2 Instance Connect Endpoint
Audit users who connect via EC2 Instance Connect Endpoint
Connection attempts to instances via EC2 Instance Connect Endpoint are logged in CloudTrail in **Event history**. When a connection to an instance is initiated through an EC2 Instance Connect Endpoint, the connection is logged as a CloudTrail management event with the `eventName` of `OpenTunnel`.
You can create Amazon EventBridge rules that route the CloudTrail event to a target. For more information, see the [Amazon EventBridge User Guide](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-what-is.html).
The following is an example of an `OpenTunnel` management event that was logged in CloudTrail.
```
{
"eventVersion": "1.08",
"userIdentity": {
"type": "IAMUser",
"principalId": "ABCDEFGONGNOMOOCB6XYTQEXAMPLE",
"arn": "arn:aws:iam::1234567890120:user/IAM-friendly-name",
"accountId": "123456789012",
"accessKeyId": "ABCDEFGUKZHNAW4OSN2AEXAMPLE",
"userName": "IAM-friendly-name"
},
"eventTime": "2023-04-11T23:50:40Z",
"eventSource": "ec2-instance-connect.amazonaws.com",
"eventName": "OpenTunnel",
"awsRegion": "us-east-1",
"sourceIPAddress": "1.2.3.4",
"userAgent": "aws-cli/1.15.61 Python/2.7.10 Darwin/16.7.0 botocore/1.10.60",
"requestParameters": {
"instanceConnectEndpointId": "eici-0123456789EXAMPLE",
"maxTunnelDuration": "3600",
"remotePort": "22",
"privateIpAddress": "10.0.1.1"
},
"responseElements": null,
"requestID": "98deb2c6-3b3a-437c-a680-03c4207b6650",
"eventID": "bbba272c-8777-43ad-91f6-c4ab1c7f96fd",
"readOnly": false,
"resources": [{
"accountId": "123456789012",
"type": "AWS::EC2::InstanceConnectEndpoint",
"ARN": "arn:aws:ec2:us-east-1:123456789012:instance-connect-endpoint/eici-0123456789EXAMPLE"
}],
"eventType": "AwsApiCall",
"managementEvent": true,
"recipientAccountId": "123456789012",
"eventCategory": "Management"
}
```
# Service-linked role for EC2 Instance Connect Endpoint
Service-linked role
Amazon EC2 uses AWS Identity and Access Management (IAM) [service-linked roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html#iam-term-service-linked-role). A service-linked role is a unique type of IAM role that is linked directly to Amazon EC2. Service-linked roles are predefined by Amazon EC2 and include all the permissions that Amazon EC2 requires to call other AWS services on your behalf. For more information, see [Service-linked roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create-service-linked-role.html) in the *IAM User Guide*.
## Service-linked role permissions for EC2 Instance Connect Endpoint
Service-linked role permissions
Amazon EC2 uses **AWSServiceRoleForEC2InstanceConnect** to create and manage network interfaces in your account that are required by EC2 Instance Connect Endpoint.
The **AWSServiceRoleForEC2InstanceConnect** service-linked role trusts the following service to assume the role:
+ `ec2-instance-connect.amazonaws.com`
The **AWSServiceRoleForEC2InstanceConnect** service-linked role uses the following managed policy:
+ **Ec2InstanceConnectEndpoint**
To view the permissions for the managed policy, see [Ec2InstanceConnectEndpoint](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/Ec2InstanceConnectEndpoint.html) in the *AWS Managed Policy Reference*.
## Create a service-linked role for EC2 Instance Connect Endpoint
Create a service-linked role
You don't need to manually create this service-linked role. When you create an EC2 Instance Connect Endpoint, Amazon EC2 creates the service-linked role for you.
## Edit a service-linked role for EC2 Instance Connect Endpoint
Edit a service-linked role
EC2 Instance Connect Endpoint doesn't allow you to edit the **AWSServiceRoleForEC2InstanceConnect** service-linked role.
## Delete a service-linked role for EC2 Instance Connect Endpoint
Delete a service-linked role
If you no longer need to use EC2 Instance Connect Endpoint, we recommend that you delete the **AWSServiceRoleForEC2InstanceConnect** service-linked role.
You must delete all EC2 Instance Connect Endpoint resources before you can delete the service-linked role.
To delete the service-linked role, see [Delete a service-linked role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_manage_delete.html#id_roles_manage_delete-slr) in the *IAM User Guide*.
You must configure permissions to allow an IAM entity (a user, group, or role) to create, edit, or delete a service-linked role. For more information, see [Service-linked role permissions](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create-service-linked-role.html#service-linked-role-permissions) in the *IAM User Guide*.
# Quotas for EC2 Instance Connect Endpoint
Quotas
Your AWS account has default quotas, formerly referred to as limits, for each AWS service. Unless otherwise noted, each quota is Region-specific.
Your AWS account has the following quotas related to EC2 Instance Connect Endpoint.
| Name | Default | Adjustable |
| --- | --- | --- |
| Maximum number of EC2 Instance Connect Endpoints per AWS account per AWS Region | 5 | No |
| Maximum number of EC2 Instance Connect Endpoints per VPC | 1 | No |
| Maximum number of EC2 Instance Connect Endpoints per subnet | 1 | No |
| Maximum number of concurrent connections per EC2 Instance Connect Endpoint | 20 | No |
# Amazon EC2 instance state changes
Instance state changes
An Amazon EC2 instance transitions through different states from the moment you launch it through to its termination.
The following illustration represents the transitions between instance states.
![\[The instance lifecycle.\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/instance_lifecycle.png)
You can receive notifications when your instances change states. For more information, see [State change events for Amazon EC2 instances](monitoring-instance-state-changes.md).
## Billing by instance state
The following table provides a brief description of each instance state and indicates whether instance usage is billed. Some AWS resources, such as Amazon EBS volumes and Elastic IP addresses, incur charges regardless of the instance's state. For more information, see [Avoiding Unexpected Charges](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/checklistforunwantedcharges.html) in the *AWS Billing User Guide*.
| Instance state | Description | Instance usage billing |
| --- | --- | --- |
| `pending` | The instance is preparing to enter the `running` state. An instance enters the `pending` state when it is launched or when it is started after being in the `stopped` state. | Not billed |
| `running` | The instance is running and ready for use. | Billed |
| `stopping` | The instance is preparing to be stopped. | Not billed If you hibernate an instance, you're billed while the instance is in the `stopping` state. |
| `stopped` | The instance is shut down and cannot be used. The instance can be started at any time. | Not billed |
| `shutting-down` | The instance is preparing to be terminated. | Not billed |
| `terminated` | The instance has been permanently deleted and cannot be started. | Not billed Reserved Instances that applied to terminated instances are billed until the end of their term according to their payment option. For more information, see [Reserved Instances for Amazon EC2 overview](ec2-reserved-instances.md) |
## Pending instances
When you launch an instance, it enters the `pending` state. The instance type that you specified at launch determines the hardware of the host computer for your instance. We use the Amazon Machine Image (AMI) you specified at launch to boot the instance. After the instance is ready for you, it enters the `running` state. You can connect to your running instance and use it the way that you'd use a computer sitting in front of you.
As soon as your instance transitions to the `running` state, you're billed for each second, with a one-minute minimum, that you keep the instance running, even if the instance remains idle and you don't connect to it.
## Stopped instances
If your instance fails a status check or is not running your applications as expected, and if the root volume of your instance is an Amazon EBS volume, you can stop and start your instance to try to fix the problem.
When you stop your instance, it enters the `stopping` state, and then the `stopped` state. You are not charged for usage or data transfer fees for your instance when it is `stopped`. Charges are incurred for the storage of any Amazon EBS volumes. While your instance is in the `stopped` state, you can modify certain attributes of the instance, including the instance type.
When you start your instance, it enters the `pending` state, and the instance is moved to a new host computer (though in some cases, it remains on the current host). When you stop and start your instance, you lose any data on the instance store volumes attached to the previous host computer.
Your instance retains its private IPv4 address, which means that an Elastic IP address associated with the private IPv4 address or network interface remains associated with your instance. If your instance has an IPv6 address, it retains the IPv6 address.
Each time you transition an instance from `stopped` to `running`, you are charged per second when the instance is running, with a minimum of one minute per instance start.
For more details about stopping and starting an instance, see [Stop and start Amazon EC2 instances](Stop_Start.md).
## Hibernated instances
When you hibernate an instance, we signal the operating system to perform hibernation (suspend-to-disk), which saves the contents from the instance memory (RAM) to your Amazon EBS root volume. We persist the instance's Amazon EBS root volume and any attached Amazon EBS data volumes. When you start your instance, the Amazon EBS root volume is restored to its previous state and the RAM contents are reloaded. Previously attached data volumes are reattached and the instance retains its instance ID.
When you hibernate your instance, it enters the `stopping` state, and then the `stopped` state. We don't charge usage for a hibernated instance when it is in the `stopped` state, but we do charge while it is in the `stopping` state, unlike when you [stop an instance](#instance-stop-start) without hibernating it. We don't charge usage for data transfer fees, but we do charge for the storage for any Amazon EBS volumes, including storage for the RAM data.
When you start your hibernated instance, it enters the `pending` state, and we move the instance to a new host computer (though in some cases, it remains on the current host).
Your instance retains its private IPv4 address, which means that an Elastic IP address associated with the private IPv4 address or network interface is still associated with your instance. If your instance has an IPv6 address, it retains its IPv6 address.
For more information, see [Hibernate your Amazon EC2 instance](Hibernate.md).
## Rebooting instances
You can reboot your instance using the Amazon EC2 console, a command line tool, and the Amazon EC2 API. We recommend that you use Amazon EC2 to reboot your instance instead of running the operating system reboot command from your instance.
Rebooting an instance is equivalent to rebooting an operating system. The instance remains on the same host computer and maintains its public DNS name, private IP address, and any data on its instance store volumes. It typically takes a few minutes for the reboot to complete, but the time it takes to reboot depends on the instance configuration.
Rebooting an instance doesn't start a new instance billing period; per second billing continues without a further one-minute minimum charge.
For more information, see [Reboot your Amazon EC2 instance](ec2-instance-reboot.md).
## Terminated instances
When you've decided that you no longer need an instance, you can terminate it. As soon as the status of an instance changes to `shutting-down` or `terminated`, you stop incurring charges for that instance.
If you enable termination protection, you can't terminate the instance using the console, CLI, or API.
After you terminate an instance, it remains visible in the console for a short while, and then the entry is automatically deleted. You can also describe a terminated instance using the CLI and API. Resources (such as tags) are gradually disassociated from the terminated instance, therefore may no longer be visible on the terminated instance after a short while. You can't connect to or recover a terminated instance.
Each Amazon EBS-backed instance supports the `InstanceInitiatedShutdownBehavior` attribute, which controls whether the instance stops or terminates when you initiate shutdown from within the instance itself (for example, by using the **shutdown** command on Linux). The default behavior is to stop the instance. You can modify the setting of this attribute while the instance is running or stopped.
Each Amazon EBS volume supports the `DeleteOnTermination` attribute, which controls whether the volume is deleted or preserved when you terminate the instance it is attached to. The default is to delete the root volume and preserve any other EBS volumes.
For more information, see [Terminate Amazon EC2 instances](terminating-instances.md).
## Differences between instance states
The following table summarizes the key differences between rebooting, stopping, hibernating, and terminating your instance.
| Characteristic | Reboot | Stop/start (Amazon EBS-backed instances only) | Hibernate (Amazon EBS-backed instances only) | Terminate |
| --- | --- | --- | --- | --- |
| Host computer | The instance stays on the same host computer. | We move the instance to a new host computer (though in some cases, it remains on the current host). | We move the instance to a new host computer (though in some cases, it remains on the current host). | None |
| Private IPv4 address | The instance keeps its private IPv4 address. | The instance keeps its private IPv4 address. | The instance keeps its private IPv4 address. | None |
| Public IPv4 address | The instance keeps its public IPv4 address. | The instance gets a new public IPv4 address, unless it has a secondary network interface or a secondary private IPv4 address that is associated with an Elastic IP address. | The instance gets a new public IPv4 address, unless it has a secondary network interface or a secondary private IPv4 address that is associated with an Elastic IP address. | None |
| Elastic IP address (IPv4) | The Elastic IP address remains associated with the instance | The Elastic IP address remains associated with the instance | The Elastic IP address remains associated with the instance | The Elastic IP address is disassociated from the instance |
| IPv6 address | The instance keeps its IPv6 address | The instance keeps its IPv6 address | The instance keeps its IPv6 address | None |
| Instance store volumes | The data is preserved | The data is erased | The data is erased | The data is erased |
| Root volume | The volume is preserved | The volume is preserved | The volume is preserved | The volume is deleted by default |
| RAM (contents of memory) | The RAM is erased | The RAM is erased | The RAM is saved to a file on the root volume | The RAM is erased |
| Billing | The instance billing hour doesn't change | You stop incurring charges for an instance as soon as its state changes to `stopping`. Each time an instance transitions from `stopped` to `running`, we start a new instance billing period, billing a minimum of one minute every time you start your instance. | You incur charges while the instance is in the `stopping` state, but stop incurring charges when the instance is in the `stopped` state. Each time an instance transitions from `stopped` to `running`, we start a new instance billing period, billing a minimum of one minute every time you start your instance. | You stop incurring charges for an instance as soon as its state changes to `shutting-down` |
Operating system shutdown commands always terminate an instance with an instance store root volume. You can control whether operating system shutdown commands stop or terminate an instance with an EBS root volume. For more information, see [Change instance initiated shutdown behavior](Using_ChangingInstanceInitiatedShutdownBehavior.md).
# Stop and start Amazon EC2 instances
Stop and start
You can stop and start your instance if it has an Amazon EBS volume as its root volume. When you stop an instance, it shuts down. When you start an instance, it is typically migrated to a new underlying host computer and assigned a new public IPv4 address.
An instance stop can be user-initiated (where you manually stop the instance) or initiated by AWS (in response to a scheduled stop event when AWS detects irreparable failure of the underlying host for your instance).
For user-initiated stops, we recommend using the Amazon EC2 console, CLI, or API instead of running the operating system stop command from your instance. When using Amazon EC2, if the instance does not cleanly shut down within a few minutes, Amazon EC2 performs a hard shut down. Furthermore, AWS CloudTrail creates an API record of when your instance was stopped.
This topic describes how to perform a user-initiated stop. For information about a stop performed by AWS, see [Manage Amazon EC2 instances scheduled to stop or retire](schedevents_actions_retire.md).
When you stop an instance, it is not deleted. If you decide that you no longer need an instance, you can terminate it. For more information, see [Terminate Amazon EC2 instances](terminating-instances.md). If you want to hibernate an instance to save the contents from the instance memory (RAM), see [Hibernate your Amazon EC2 instance](Hibernate.md). For distinctions between instance lifecycle actions, see [Differences between instance states](ec2-instance-lifecycle.md#lifecycle-differences).
**Topics**
+ [How it works](how-ec2-instance-stop-start-works.md)
+ [
# Methods for stopping an instance
](instance-stop-methods.md)
+ [Manually stop and start](#starting-stopping-instances)
+ [Automatically stop and start](#stop-start-ec2-instances-on-a-schedule)
+ [Find running and stopped instances](#find-running-and-stopped-instances-in-globalview)
+ [
## Find the initial and most recent launch times
](#find-initial-launch-time)
+ [Enable stop protection](ec2-stop-protection.md)
# How EC2 instance stop and start works
How it works
When you stop an Amazon EC2 instance, changes are registered at the operating system (OS) level of the instance, some resources are lost, and some resources persist. When you start an instance, changes are registered at the instance level.
**Topics**
+ [
## What happens when you stop an instance
](#what-happens-stop)
+ [
## What happens when you start an instance
](#what-happens-start)
+ [
## Test application response to stop and start
](#test-stop-start-instance)
+ [
## Costs related to instance stop and start
](#ec2-stop-start-costs)
## What happens when you stop an instance
The following describes what typically happens when you stop an instance using the default stop method. Note that some aspects might vary depending on which [stop method](instance-stop-methods.md) you use.
**Changes registered at the OS level**
+ The API request sends a button press event to the guest.
+ Various system services are stopped as a result of the button press event. Graceful OS shutdown is triggered by the ACPI shutdown button press event from the hypervisor.
+ ACPI shutdown is initiated.
+ The instance shuts down when the graceful OS shutdown process exits. There is no configurable OS shutdown time.
+ If the instance OS does not cleanly shut down within a few minutes, a hard shutdown is performed.
+ The instance stops running.
+ The instance state changes to `stopping` and then `stopped`.
+ [Auto Scaling] If your instance is in an Auto Scaling group, when the instance is in any Amazon EC2 state other than `running`, or if its status for the status checks becomes `impaired`, Amazon EC2 Auto Scaling considers the instance to be unhealthy and replaces it. For more information, see [Health checks for instances in an Auto Scaling group](https://docs.aws.amazon.com/autoscaling/ec2/userguide/ec2-auto-scaling-health-checks.html) in the *Amazon EC2 Auto Scaling User Guide*.
+ [Windows instances] When you stop and start a Windows instance, the launch agent performs tasks on the instance, such as changing the drive letters for any attached Amazon EBS volumes. For more information about these defaults and how you can change them, see [Use the EC2Launch v2 agent to perform tasks during EC2 Windows instance launch](ec2launch-v2.md).
**Resources lost**
+ Data stored on the RAM.
+ Data stored on the instance store volumes.
+ The public IPv4 address that Amazon EC2 automatically assigned to the instance upon launch or start. To retain a public IPv4 address that never changes, you can associate an [Elastic IP address](elastic-ip-addresses-eip.md) with your instance.
**Resources that persist**
+ Any attached Amazon EBS root and data volumes.
+ Data stored on the Amazon EBS volumes.
+ Any attached [network interfaces](using-eni.md).
A network interface includes the following resources, which also persist:
+ Private IPv4 addresses.
+ IPv6 addresses.
+ Elastic IP addresses associated with the instance. Note that when the instance is stopped, you are [charged for the associated Elastic IP addresses](elastic-ip-addresses-eip.md#eip-pricing).
The following diagram illustrates what persists and what is lost when an EC2 instance is stopped. The diagram is divided into three parts: the first part, labeled **Running EC2 instance**, shows the instance in the `running` state with its resources. The second part, labeled **Stopped EC2 instance**, shows the instance in the `stopped` state with the resources that persist. The third part, labeled **Lost**, shows the resources that are lost when the instance is stopped.
![\[The public IPv4 address, RAM, and instance storage data are lost when an instance is stopped.\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/stop-instance.png)
For information about what happens when you stop a Mac instance, see [Stop or terminate your Amazon EC2 Mac instance](mac-instance-stop.md).
## What happens when you start an instance
+ In most cases, the instance is migrated to a new underlying host computer (though in some cases, such as when an instance is allocated to a host in a [Dedicated Host](dedicated-hosts-understanding.md) configuration, it remains on the current host).
+ The associated EBS volumes and network interfaces are reattached to the instance.
+ Amazon EC2 assigns a new public IPv4 address to the instance if the instance is configured to receive a public IPv4 address, unless it has a secondary network interface or a secondary private IPv4 address that is associated with an Elastic IP address.
+ If you stop an instance in a placement group and then start it again, it still runs in the placement group. However, the start fails if there isn't enough capacity for the instance. If you receive a capacity error when starting an instance in a placement group that already has running instances, stop all the instances in the placement group and start them all again. Starting the instances may migrate them to hardware that has capacity for all of the requested instances.
## Test application response to stop and start
Test application response
You can use AWS Fault Injection Service to test how your application responds when your instance is stopped and started. For more information, see the [AWS Fault Injection Service User Guide](https://docs.aws.amazon.com/fis/latest/userguide/what-is.html).
## Costs related to instance stop and start
Related costs
The following costs are associated with stopping and starting an instance.
**Stopping** – As soon as the state of an instance changes to `shutting-down` or `terminated`, charges are no longer incurred for the instance. You are not charged for usage or data transfer fees for a stopped instance. Charges are incurred to store Amazon EBS storage volumes.
**Starting** – Each time you start a stopped instance, you are charged for a minimum of one minute of usage. After one minute, you are charged for only the seconds you use. For example, if you run an instance for 20 seconds and then stop it, you are charged for a minute of usage. If you run an instance for 3 minutes and 40 seconds, you are charged for 3 minutes and 40 seconds of usage.
# Methods for stopping an instance
There are four ways to perform a user-initiated stop: default stop, stop with skip OS shutdown, force stop, and force stop with skip OS shutdown. The following table compares the key differences between the stop methods:
| Stop method | Key purpose | Use case | CLI command |
| --- | --- | --- | --- |
| Default stop | Normal instance shutdown with attempted graceful OS shutdown. | Typical instance stop. | aws ec2 stop-instances \
--instance-id i-1234567890abcdef0
|
| Stop with skip OS shutdown | Bypasses the graceful OS shutdown when stopping an instance. | When bypassing graceful OS shutdown is required. | aws ec2 stop-instances \
--instance-id i-1234567890abcdef0 \
--skip-os-shutdown
|
| Force stop | Handles stuck instances. Attempts a default stop first; if instance fails to stop, then forcibly stops the instance. | When instance is stuck in stopping state. | aws ec2 stop-instances \
--instance-id i-1234567890abcdef0 \
--force
|
| Force stop with skip OS shutdown | Force stops and bypasses the graceful OS shutdown when stopping an instance. | When force stop and bypassing graceful OS shutdown is required. | aws ec2 stop-instances \
--instance-id i-1234567890abcdef0 \
--force \
--skip-os-shutdown
|
For instructions on how to use each method, see the following:
+ [Stop an instance with a graceful OS shutdown](Stop_Start.md#stop-instance-with-graceful-os-shutdown)
+ [Stop an instance and bypass the graceful OS shutdown](Stop_Start.md#stop-instance-bypass-graceful-os-shutdown)
+ [Force stop an instance](TroubleshootingInstancesStopping.md#force-stop-instance)
**Topics**
+ [
## Default stop
](#ec2-instance-default-stop)
+ [
## Stop with skip OS shutdown
](#ec2-instance-stop-with-skip-os-shutdown)
+ [
## Force stop
](#ec2-instance-force-stop)
+ [
## Force stop with skip OS shutdown
](#ec2-instance-force-stop-with-skip-os-shutdown)
The following sections provide more detailed information about the four different user-initiated stop methods.
## Default stop
The default stop method is the standard way to stop an instance. When you issue the StopInstances command, the instance transitions from the `running` state, to `stopping`, and finally to `stopped`, as illustrated by the following diagram:
![\[Default stop flow\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/stop-instance-flow-1.png)
**Purpose:** Normal instance shutdown with attempted graceful OS shutdown.
**Data impact:** Preserves data on the EBS root volume and data volumes. Loses data on the instance store volume.
**When to use:** First stop attempt for typical stops.
**Note**
If you've already attempted a stop with skip OS shutdown, a subsequent default stop attempt during the same state transition session will not perform a graceful OS shutdown. Bypassing the graceful OS shutdown is irreversible for the instance's current session.
## Stop with skip OS shutdown
When bypassing the graceful OS shutdown is required, the stop with skip OS shutdown method can be used to stop an instance and bypass the graceful OS shutdown, as illustrated by the following diagram:
![\[Stop with skip OS shutdown flow\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/stop-instance-flow-3.png)
**Warning**
Bypassing the graceful OS shutdown might result in data loss or corruption (for example, memory contents not flushed to disk or loss of in-flight IOs) or skipped shutdown scripts.
**Purpose:** Bypass the graceful OS shutdown when stopping an instance.
**Data impact:** Might result in data loss or corruption. Contents of memory might not be flushed to disk and in-flight IOs might be lost. Might skip shutdown scripts.
**When to use:** When bypassing the graceful OS shutdown is required. If used while a default stop with graceful OS shutdown is in progress, the graceful OS shutdown will be bypassed.
**Note**
Bypassing the graceful OS shutdown is irreversible for the instance's current state transition session. A subsequent default stop attempt during this session will not attempt a graceful OS shutdown.
## Force stop
The force stop method is used to handle instances that are stuck in the `stopping` state. An instance typically becomes stuck due to an underlying hardware issue (indicated by a failed [system status check](monitoring-system-instance-status-check.md#system-status-checks)).
The force stop method first attempts a default stop. If the instance remains stuck in the `stopping` state, the `force` parameter forcibly shuts down the instance and transitions the instance to the `stopped` state, as indicated by the following diagram:
![\[Force stop flow\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/stop-instance-flow-2.png)
**Purpose:** Handles instances stuck in the `stopping` state. Attempts a default stop first. If the instance fails to stop, then forcibly shuts down the instance.
**Data impact:** Attempts a default stop first, but if force stop goes ahead, then might cause data loss or corruption. In rare cases, results in post-stop writes to EBS volumes or other shared resources.
**When to use:** Second stop attempt when an instance remains stuck after a default stop. For more information, see [Troubleshoot Amazon EC2 instance stop issues](TroubleshootingInstancesStopping.md).
## Force stop with skip OS shutdown
When force stopping and bypassing the graceful OS shutdown is required, the force stop with skip OS shutdown method can be used to bring an instance to the `stopped` state, as illustrated in the following diagram:
![\[Force stop with skip OS shutdown flow\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/stop-instance-flow-4.png)
**Purpose:** Combines force stop with bypassing a graceful OS shutdown when stopping an instance.
**Data impact:** Skip OS shutdown might result in data loss or corruption. Contents of memory might not be flushed to disk and in-flight IOs might be lost. Might skip shutdown scripts. If force stop goes ahead, then might cause additional data loss or corruption. In rare cases, results in post-stop writes to the EBS volumes or other shared resources.
**When to use:** When you want to be sure that your instance will stop and you want to bypass the graceful OS shutdown. If used while a default stop with graceful OS shutdown is in progress, the graceful OS shutdown will be bypassed.
## Manually stop and start your instances
Manually stop and start
You can stop and start your Amazon EBS-backed instances (instances with EBS root volumes). You can't stop and start instances with an instance store root volume.
When using the default method to stop an instance, a graceful operating system (OS) shutdown is attempted. You can bypass the graceful OS shutdown; however, this might risk data integrity.
**Warning**
When you stop an instance, the data on any instance store volumes is erased. Before you stop an instance, verify that you've copied any data that you need from the instance store volumes to persistent storage, such as Amazon EBS or Amazon S3.
[Linux instances] Using the OS **halt** command from an instance does not initiate a shutdown. If you use the **halt** command, the instance does not terminate; instead, it places the CPU into `HLT`, which suspends CPU operation. The instance remains running.
You can initiate a shutdown using the OS **shutdown** or **poweroff** commands. When you use an OS command, the instance stops by default. You can change this behavior. For more information, see [Change instance initiated shutdown behavior](Using_ChangingInstanceInitiatedShutdownBehavior.md).
**Note**
If you stopped an Amazon EBS-backed instance and it appears "stuck" in the `stopping` state, you can forcibly stop it. For more information, see [Troubleshoot Amazon EC2 instance stop issues](TroubleshootingInstancesStopping.md).
**Topics**
+ [
### Stop an instance with a graceful OS shutdown
](#stop-instance-with-graceful-os-shutdown)
+ [
### Stop an instance and bypass the graceful OS shutdown
](#stop-instance-bypass-graceful-os-shutdown)
+ [
### Start an instance
](#start-ec2-instance)
### Stop an instance with a graceful OS shutdown
You can stop an instance using the default stop method, which includes an attempt at a graceful OS shutdown. For more information, see [Default stop](instance-stop-methods.md#ec2-instance-default-stop).
------
#### [ Console ]
**To stop an instance using the default stop method**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the left navigation pane, choose **Instances**, and then select the instance.
1. Choose **Instance state**, **Stop instance**. If this option is disabled, either the instance is already stopped or its root volume is an instance store volume.
1. When prompted for confirmation, choose **Stop**. It can take a few minutes for the instance to stop.
------
#### [ AWS CLI ]
**To stop an instance using the default stop method**
Use the [stop-instances](https://docs.aws.amazon.com/cli/latest/reference/ec2/stop-instances.html) command.
```
aws ec2 stop-instances --instance-ids i-1234567890abcdef0
```
------
#### [ PowerShell ]
**To stop an instance using the default stop method**
Use the [Stop-EC2Instance](https://docs.aws.amazon.com/powershell/latest/reference/items/Stop-EC2Instance.html) cmdlet
```
Stop-EC2Instance -InstanceId i-1234567890abcdef0
```
------
### Stop an instance and bypass the graceful OS shutdown
You can bypass the graceful OS shutdown when stopping an instance. For more information, see [Stop with skip OS shutdown](instance-stop-methods.md#ec2-instance-stop-with-skip-os-shutdown).
**Warning**
Bypassing the graceful OS shutdown might result in data loss or corruption (for example, memory contents not flushed to disk or loss of in-flight IOs) or skipped shutdown scripts.
------
#### [ Console ]
**To stop an instance and bypass the graceful OS shutdown**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation pane, choose **Instances** and select the instance.
1. Choose **Instance state**, **Stop instance**.
1. Under **Skip OS shutdown**, select the **Skip OS shutdown** checkbox. If you don't see this option in the console, it's not yet available in the console in the current Region. You can, however, access this feature using the AWS CLI or SDK, or try another Region in the console.
1. Choose **Stop**.
------
#### [ AWS CLI ]
**To stop an instance and bypass the graceful OS shutdown**
Use the [stop-instances](https://docs.aws.amazon.com/cli/latest/reference/ec2/stop-instances.html) command with `--skip-os-shutdown`.
```
aws ec2 stop-instances \
--instance-ids i-1234567890abcdef0 \
--skip-os-shutdown
```
------
#### [ PowerShell ]
**To stop an instance and bypass the graceful OS shutdown**
Use the [Stop-EC2Instance](https://docs.aws.amazon.com/powershell/latest/reference/items/Stop-EC2Instance.html) cmdlet with `-SkipOsShutdown $true`.
```
Stop-EC2Instance `
-InstanceId i-1234567890abcdef0 `
-SkipOsShutdown $true
```
------
### Start an instance
You can start a stopped instance.
------
#### [ Console ]
**To start an instance**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the left navigation pane, choose **Instances**.
1. Select the instance, and choose **Instance state**, **Start instance**.
It can take a few minutes for the instance to enter the `running` state.
------
#### [ AWS CLI ]
**To start an instance**
Use the [start-instances](https://docs.aws.amazon.com/cli/latest/reference/ec2/start-instances.html) command.
```
aws ec2 start-instances --instance-ids i-1234567890abcdef0
```
------
#### [ PowerShell ]
**To start an instance**
Use the [Start-EC2Instance](https://docs.aws.amazon.com/powershell/latest/reference/items/Start-EC2Instance.html) cmdlet.
```
Start-EC2Instance -InstanceId i-1234567890abcdef0
```
------
## Automatically stop and start your instances
Automatically stop and start
You can automate stopping and starting instances with the following services:
**Instance Scheduler on AWS**
You can use Instance Scheduler on AWS to automate the starting and stopping of EC2 instances. For more information, see [How do I use Instance Scheduler with CloudFormation to schedule EC2 instances?](https://repost.aws/knowledge-center/stop-start-instance-scheduler) Note that [additional charges apply](https://docs.aws.amazon.com/solutions/latest/instance-scheduler-on-aws/cost.html).
**AWS Lambda and an Amazon EventBridge rule**
You can use Lambda and an EventBridge rule to stop and start your instances on a schedule. For more information, see [How do I use Lambda to stop and start Amazon EC2 instances at regular intervals?](https://repost.aws/knowledge-center/start-stop-lambda-eventbridge)
**Amazon EC2 Auto Scaling**
To ensure you have the correct number of Amazon EC2 instances available to handle the load for an application, create Auto Scaling groups. Amazon EC2 Auto Scaling ensures that your application always has the right capacity to handle the traffic demand, and saves costs by launching instances only when they are needed. Note that Amazon EC2 Auto Scaling terminates, rather than stops, unneeded instances. To set up Auto Scaling groups, see [Get started with Amazon EC2 Auto Scaling](https://docs.aws.amazon.com/autoscaling/ec2/userguide/get-started-with-ec2-auto-scaling.html).
## Find all running and stopped instances
Find running and stopped instances
You can find all of your running and stopped instances across all AWS Regions on a single page using [Amazon EC2 Global View](https://console.aws.amazon.com/ec2globalview/home). This capability is especially useful for taking inventory and finding forgotten instances. For information about how to use Global View, see [View resources across Regions using AWS Global View](global-view.md).
Alternatively, you can run a command or cmdlet in each Region where you have instances.
------
#### [ AWS CLI ]
**To get the number of EC2 instances in a Region**
Use the following [describe-instances](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instances.html) command to count the instances in the current Region. You must run this command in each Region where you have instances.
```
aws ec2 describe-instances \
--region us-east-2 \
--query "length(Reservations[].Instances[])"
```
The following is example output.
```
27
```
**To get summary info about your EC2 instances in a Region**
Use the following [describe-instances](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instances.html) command. You must run this command in each Region where you have instances.
```
aws ec2 describe-instances \
--region us-east-2 \
--query "Reservations[].Instances[].[InstanceId,InstanceType,PrivateIpAddress]" \
--output table
```
The following is example output.
```
---------------------------------------------------------
| DescribeInstances |
+---------------------+---------------+-----------------+
| i-0e3e777f4362f1bf7| t2.micro | 10.0.12.9 |
| i-09453945dcf1529e9| t2.micro | 10.0.143.213 |
| i-08fd74f3f1595fdbd| m7i.4xlarge | 10.0.1.103 |
+---------------------+---------------+-----------------+
```
------
#### [ PowerShell ]
**To get the number of EC2 instances in a Region**
Use the [Get-EC2Instance](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-EC2Instance.html) cmdlet.
```
(Get-EC2Instance -Region us-east-2).Instances.Length
```
The following is example output.
```
27
```
**To get summary info about your EC2 instances in a Region**
Use the [Get-EC2Instance](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-EC2Instance.html) cmdlet. You must run this command in each Region where you have instances.
```
(Get-EC2Instance).Instances | Select InstanceId, InstanceType, PrivateIpAddress
```
The following is example output.
```
InstanceId InstanceType PrivateIpAddress
---------- ------------ ----------------
i-0e3e777f4362f1bf7 t2.micro 10.0.12.9
i-09453945dcf1529e9 t2.micro 10.0.143.213
i-08fd74f3f1595fdbd m7i.4xlarge 10.0.1.103
```
------
## Find the initial and most recent launch times
When you describe an instance, the launch time for the instance is its most recent launch time. After you stop and start an instance, the launch time reflects the new instance start time. To find the initial launch time for an instance, even after stopping and starting it, view the time at which the primary network interface was attached to the instance.
------
#### [ Console ]
**To find the most recent launch time**
Select the instance and find **Launch time** under **Instance details** on the **Details** tab.
**To find the initial launch time**
Select the instance and find the primary network interface (device index is 0) under **Network interfaces** on the **Networking** tab.
------
#### [ AWS CLI ]
**To find the initial and most recent launch times**
Use the following [describe-instances](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instances.html) command to display both the initial launch time and the most recent launch time for the specified instance.
```
aws ec2 describe-instances \
--instance-id i-1234567890abcdef0 \
--query 'Reservations[].Instances[].{InstanceID:InstanceId,InitialLaunch:NetworkInterfaces[0].Attachment.AttachTime,LastLaunch:LaunchTime}'
```
The following is example output.
```
[
{
"InstanceID": "i-1234567890abcdef0",
"InitialLaunch": "2024-04-19T00:47:08+00:00",
"LastLaunch": "2024-05-27T06:24:06+00:00"
}
]
```
------
#### [ PowerShell ]
**To find the most recent launch time**
Use the [Get-EC2Instance](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-EC2Instance.html) cmdlet.
```
(Get-EC2Instance -InstanceId i-1234567890abcdef0).Instances.LaunchTime
```
The following is example output.
```
Monday, May 27, 2024 6:24:06 AM
```
**To find the initial launch time**
Use the [Get-EC2Instance](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-EC2Instance.html) cmdlet.
```
(Get-EC2Instance -InstanceId i-1234567890abcdef0).Instances.NetworkInterfaces.Attachment.AttachTime
```
The following is example output.
```
Friday, April 19, 2024 12:47:08 AM
```
------
# Enable stop protection for your EC2 instances
Enable stop protection
To prevent an instance from being accidentally stopped, you can enable stop protection for the instance. Stop protection also protects your instance from accidental termination.
The `DisableApiStop` attribute of the Amazon EC2 [https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyInstanceAttribute.html](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyInstanceAttribute.html) API controls whether the instance can be stopped by using the Amazon EC2 console, the AWS CLI, or the Amazon EC2 API. You can set the value of this attribute when you launch the instance, while the instance is running, or while the instance is stopped.
**Considerations**
+ Enabling stop protection does not prevent you from accidentally stopping an instance by initiating a shutdown from the instance using an operating system command such as **shutdown** or **poweroff**.
+ Enabling stop protection does not prevent AWS from stopping the instance when there is a [scheduled event](monitoring-instances-status-check_sched.md) to stop the instance.
+ Enabling stop protection does not prevent Amazon EC2 Auto Scaling from terminating an instance when the instance is unhealthy or during scale-in events. You can control whether an Auto Scaling group can terminate a particular instance when scaling in by using [instance scale-in protection](https://docs.aws.amazon.com/autoscaling/ec2/userguide/ec2-auto-scaling-instance-protection.html).
+ Stop protection not only prevents your instance from being accidentally stopped, but also from accidental termination when using the console, AWS CLI, or API. However, it does not automatically set the `DisableApiTermination` attribute. Note that when the `DisableApiStop` attribute is set to `false`, the `DisableApiTermination` attribute setting determines whether the instance can be terminated using the console, AWS CLI, or API. For more information see [Terminate Amazon EC2 instances](terminating-instances.md).
+ You can't enable stop protection for an instance with an instance store root volume.
+ You can't enable stop protection for Spot Instances.
+ The Amazon EC2 API follows an eventual consistency model when you enable or disable stop protection. This means that the result of running commands to set the stop protection attribute might not be immediately visible to all subsequent commands you run. For more information, see [Eventual consistency](https://docs.aws.amazon.com/ec2/latest/devguide/eventual-consistency.html) in the *Amazon EC2 Developer Guide*.
**Topics**
+ [
## Enable stop protection for an instance at launch
](#enable-stop-protection-at-launch)
+ [
## Enable stop protection for a running or stopped instance
](#enable-stop-protection-on-running-or-stopped-instance)
+ [
## Disable stop protection for a running or stopped instance
](#disable-stop-protection-on-running-or-stopped-instance)
## Enable stop protection for an instance at launch
You can enable stop protection for an instance when launching the instance.
------
#### [ Console ]
**To enable stop protection for an instance at launch**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. On the dashboard, choose **Launch instance**.
1. Configure your instance in the [new launch instance wizard](ec2-launch-instance-wizard.md).
1. In the wizard, enable stop protection by choosing **Enable** for **Stop protection** under **Advanced details**.
------
#### [ AWS CLI ]
**To enable stop protection for an instance at launch**
Use the [run-instances](https://docs.aws.amazon.com/cli/latest/reference/ec2/run-instances.html) command to launch the instance. Add the following parameter.
```
--disable-api-stop
```
------
#### [ PowerShell ]
**To enable stop protection for an instance at launch**
Use the [New-EC2Instance](https://docs.aws.amazon.com/powershell/latest/reference/items/New-EC2Instance.html) cmdlet to launch the instance. Add the following parameter.
```
-DisableApiStop $true
```
------
## Enable stop protection for a running or stopped instance
You can enable stop protection for an instance while the instance is running or stopped.
------
#### [ Console ]
**To enable stop protection for an instance**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the left navigation pane, choose **Instances**.
1. Select the instance, and then choose **Actions**>**Instance settings**>**Change stop protection**.
1. Select the **Enable** checkbox, and then choose **Save**.
------
#### [ AWS CLI ]
**To enable stop protection for an instance**
Use the [modify-instance-attribute](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-attribute.html) command.
```
aws ec2 modify-instance-attribute \
--instance-id i-1234567890abcdef0 \
--disable-api-stop
```
------
#### [ PowerShell ]
**To enable stop protection for an instance**
Use the [Edit-EC2InstanceAttribute](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2InstanceAttribute.html) cmdlet.
```
Edit-EC2InstanceAttribute `
-InstanceId i-1234567890abcdef0 `
-DisableApiStop $true
```
------
## Disable stop protection for a running or stopped instance
You can disable stop protection for a running or stopped instance using one of the following methods.
------
#### [ Console ]
**To disable stop protection for a running or stopped instance**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the left navigation pane, choose **Instances**.
1. Select the instance, and then choose **Actions**, **Instance settings**, **Change stop protection**.
1. Clear the **Enable** checkbox, and then choose **Save**.
------
#### [ AWS CLI ]
**To disable stop protection for a running or stopped instance**
Use the [modify-instance-attribute](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-attribute.html) command.
```
aws ec2 modify-instance-attribute \
--instance-id i-1234567890abcdef0 \
--no-disable-api-stop
```
------
#### [ PowerShell ]
**To disable stop protection for an instance**
Use the [Edit-EC2InstanceAttribute](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2InstanceAttribute.html) cmdlet.
```
Edit-EC2InstanceAttribute `
-InstanceId i-1234567890abcdef0 `
-DisableApiStop $false
```
------
# Hibernate your Amazon EC2 instance
Hibernate
When you hibernate an instance, Amazon EC2 signals the operating system to perform hibernation (suspend-to-disk). Hibernation saves the contents from the instance memory (RAM) to your Amazon Elastic Block Store (Amazon EBS) root volume. Amazon EC2 persists the instance's EBS root volume and any attached EBS data volumes. When your instance is started:
+ The EBS root volume is restored to its previous state
+ The RAM contents are reloaded
+ The processes that were previously running on the instance are resumed
+ Previously attached data volumes are reattached and the instance retains its instance ID
You can hibernate an instance only if it's [enabled for hibernation](enabling-hibernation.md) and it meets the [hibernation prerequisites](hibernating-prerequisites.md).
If an instance or application takes a long time to bootstrap and build a memory footprint in order to become fully productive, you can use hibernation to pre-warm the instance. To pre-warm the instance, you:
1. Launch it with hibernation enabled.
1. Bring it to a desired state.
1. Hibernate it so that it's ready to be resumed to the desired state whenever needed.
You're not charged for instance usage for a hibernated instance when it is in the `stopped` state or for data transfer when the contents of the RAM are transferred to the EBS root volume. You are charged for storage of any EBS volumes, including storage for the RAM contents.
If you no longer need an instance, you can terminate it at any time, including when it is in a `stopped` (hibernated) state. For more information, see [Terminate Amazon EC2 instances](terminating-instances.md).
**Topics**
+ [How it works](instance-hibernate-overview.md)
+ [Prerequisites](hibernating-prerequisites.md)
+ [
# Configure a Linux AMI to support hibernation
](hibernation-enabled-AMI.md)
+ [Enable instance hibernation](enabling-hibernation.md)
+ [
# Disable KASLR on an instance (Ubuntu only)
](hibernation-disable-kaslr.md)
+ [Hibernate an instance](hibernating-instances.md)
+ [Start a hibernated instance](hibernating-resuming.md)
+ [Troubleshoot](troubleshoot-instance-hibernate.md)
# How Amazon EC2 instance hibernation works
How it works
The following diagram shows a basic overview of the hibernation process for EC2 instances.
![\[Overview of the hibernation flow.\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/hibernation-flow.png)
## What happens when you hibernate an instance
When you hibernate an instance, the following happens:
+ The instance moves to the `stopping` state. Amazon EC2 signals the operating system to perform hibernation (suspend-to-disk). The hibernation freezes all of the processes, saves the contents of the RAM to the EBS root volume, and then performs a regular shutdown.
+ After the shutdown is complete, the instance moves to the `stopped` state.
+ Any EBS volumes remain attached to the instance, and their data persists, including the saved contents of the RAM.
+ Any Amazon EC2 instance store volumes remain attached to the instance, but the data on the instance store volumes is lost.
+ In most cases, the instance is migrated to a new underlying host computer when it's started. This is also what happens when you stop and start an instance.
+ When the instance is started, the instance boots up and the operating system reads in the contents of the RAM from the EBS root volume, before unfreezing processes to resume its state.
+ The instance retains its private IPv4 addresses and any IPv6 addresses. When the instance is started, the instance continues to retain its private IPv4 addresses and any IPv6 addresses.
+ Amazon EC2 releases the public IPv4 address. When the instance is started, Amazon EC2 assigns a new public IPv4 address to the instance.
+ The instance retains its associated Elastic IP addresses. You're charged for any Elastic IP addresses that are associated with a hibernated instance.
For information about how hibernation differs from reboot, stop, and terminate, see [Differences between instance states](ec2-instance-lifecycle.md#lifecycle-differences).
## Limitations
+ When you hibernate an instance, the data on any instance store volumes is lost.
+ (Linux instances) You can't hibernate a Linux instance that has more than 150 GiB of RAM.
+ (Windows instances) You can't hibernate a Windows instance that has more than 16 GiB of RAM.
+ While your instance is hibernated, you can't modify it. This is different to a stopped instance that isn't hibernated, where you can modify certain attributes, such as the instance type or size.
+ If you create a snapshot or AMI from an instance that is hibernated or has hibernation enabled, you might not be able to connect to a new instance that is launched from the AMI or from an AMI that was created from the snapshot.
+ (Spot Instances only) If Amazon EC2 hibernates your Spot Instance, only Amazon EC2 can resume your instance. If you hibernate your Spot Instance ([user-initiated hibernation](hibernating-instances.md)), you can resume your instance. A hibernated Spot Instance can only be resumed if capacity is available and the Spot price is less than or equal to your specified maximum price.
+ You can't hibernate an instance that is in an Auto Scaling group or used by Amazon ECS. If your instance is in an Auto Scaling group and you try to hibernate it, the Amazon EC2 Auto Scaling service marks the stopped instance as unhealthy, and might terminate it and launch a replacement instance. For more information, see [Health checks for instances in an Auto Scaling group](https://docs.aws.amazon.com/autoscaling/ec2/userguide/ec2-auto-scaling-health-checks.html) in the *Amazon EC2 Auto Scaling User Guide*.
+ You can't hibernate an instance that is configured to boot in UEFI mode with [UEFI Secure Boot](uefi-secure-boot.md) enabled.
+ If you hibernate an instance that was launched into a Capacity Reservation, the Capacity Reservation does not ensure that the hibernated instance can resume after you try to start it.
+ You can’t hibernate an instance that uses a kernel below 5.10 if Federal Information Processing Standard (FIPS) mode is enabled.
+ We do not support keeping an instance hibernated for more than 60 days. To keep the instance for longer than 60 days, you must start the hibernated instance, stop the instance, and start it.
+ We constantly update our platform with upgrades and security patches, which can conflict with existing hibernated instances. We notify you about critical updates that require a start for hibernated instances so that we can perform a shutdown or a reboot to apply the necessary upgrades and security patches.
## Considerations for hibernating a Spot Instance
+ If *you* hibernate your Spot Instance, you can restart it provided capacity is available and the Spot price is less than or equal to your specified maximum price.
+ If *Amazon EC2* hibernates your Spot Instance:
+ Only Amazon EC2 can resume your instance.
+ Amazon EC2 resumes the hibernated Spot Instance when capacity becomes available with a Spot price that is less than or equal to your specified maximum price.
+ Before Amazon EC2 hibernates your Spot Instance, you'll receive an interruption notice two minutes before hibernation starts.
For more information, see [Spot Instance interruptions](spot-interruptions.md).
# Prerequisites for EC2 instance hibernation
Prerequisites
You can enable hibernation support for an On-Demand Instance or a Spot Instance when you launch it. You can't enable hibernation on an existing instance, whether it is running or stopped. For more information, see [Enable instance hibernation](enabling-hibernation.md).
**Topics**
+ [
## AWS Regions
](#hibernation-prereqs-regions)
+ [
## AMIs
](#hibernation-prereqs-supported-amis)
+ [
## Instance families
](#hibernation-prereqs-supported-instance-families)
+ [
## Instance RAM size
](#instance-ram-size)
+ [
## Root volume type
](#hibernation-prereqs-root-volume-type)
+ [
## Root volume size
](#hibernation-prereqs-ebs-root-volume-size)
+ [
## Root volume encryption
](#hibernation-prereqs-ebs-root-volume-encryption)
+ [
## EBS volume type
](#hibernation-prereqs-ebs-volume-types)
+ [
## Spot Instance requests
](#hibernation-prereqs-spot-request)
## AWS Regions
You can use hibernation with instances in all AWS Regions.
## AMIs
You must use an HVM AMI that supports hibernation. The following AMIs support hibernation:
### Linux AMIs
**AMIs for Intel and AMD instance types**
+ AL2023 AMI released 2023.09.20 or later ¹
+ Amazon Linux 2 AMI released 2019.08.29 or later
+ Amazon Linux AMI 2018.03 released 2018.11.16 or later
+ CentOS version 8 AMI ² ([Additional configuration](hibernation-enabled-AMI.md#configure-centos-for-hibernation) is required)
+ Fedora version 34 or later AMI ² ([Additional configuration](hibernation-enabled-AMI.md#configure-fedora-for-hibernation) is required)
+ Red Hat Enterprise Linux (RHEL) 9 AMI ² ([Additional configuration](hibernation-enabled-AMI.md#configure-RHEL-for-hibernation) is required)
+ Red Hat Enterprise Linux (RHEL) 8 AMI ² ([Additional configuration](hibernation-enabled-AMI.md#configure-RHEL-for-hibernation) is required)
+ Ubuntu 22.04.2 LTS (Jammy Jellyfish) AMI released with serial number 20230303 or later ³
+ Ubuntu 20.04 LTS (Focal Fossa) AMI released with serial number 20210820 or later ³
+ Ubuntu 18.04 LTS (Bionic Beaver) AMI released with serial number 20190722.1 or later ³ ⁵
+ Ubuntu 16.04 LTS (Xenial Xerus) AMI ³ ⁴ ⁵ ([Additional configuration](hibernation-enabled-AMI.md#configure-ubuntu1604-for-hibernation) is required)
**AMIs for Graviton instance types**
+ AL2023 AMI (64-bit Arm) released 2024.07.01 or later ¹
+ Amazon Linux 2 AMI (64-bit Arm) released 2024.06.20 or later
+ Ubuntu 22.04.2 LTS (64-bit Arm) (Jammy Jellyfish) AMI released with serial number 20240701 or later ³
+ Ubuntu 20.04 LTS (64-bit Arm) (Focal Fossa) AMI released with serial number 20240701 or later ³
¹ For AL2023 minimal AMI, [additional configuration is required](hibernation-enabled-AMI.md#configure-AL2023-minimal-for-hibernation).
² For CentOS, Fedora, and Red Hat Enterprise Linux, hibernation is supported on Nitro-based instances only.
³ We recommend disabling KASLR on instances with Ubuntu 22.04.2 LTS (Jammy Jellyfish), Ubuntu 20.04 LTS (Focal Fossa), Ubuntu 18.04 LTS (Bionic Beaver), and Ubuntu 16.04 LTS (Xenial Xerus). For more information, see [Disable KASLR on an instance (Ubuntu only)](hibernation-disable-kaslr.md).
⁴ For the Ubuntu 16.04 LTS (Xenial Xerus) AMI, hibernation is not supported on `t3.nano` instance types. No patch will be made available because Ubuntu (Xenial Xerus) ended support in April 2021. If you want to use `t3.nano` instance types, we recommend that you upgrade to the Ubuntu 22.04.2 LTS (Jammy Jellyfish), Ubuntu 20.04 LTS (Focal Fossa) AMI, or the Ubuntu 18.04 LTS (Bionic Beaver) AMI.
⁵ Support for Ubuntu 18.04 LTS (Bionic Beaver) and Ubuntu 16.04 LTS (Xenial Xerus) has reached end of life.
To configure your own AMI to support hibernation, see [Configure a Linux AMI to support hibernation](hibernation-enabled-AMI.md).
Support for other versions of Ubuntu and other operating systems is coming soon.
### Windows AMIs
+ Windows Server 2022 AMI released 2023.09.13 or later
+ Windows Server 2019 AMI released 2019.09.11 or later
+ Windows Server 2016 AMI released 2019.09.11 or later
+ Windows Server 2012 R2 AMI released 2019.09.11 or later
+ Windows Server 2012 AMI released 2019.09.11 or later
## Instance families
You must use an instance family that supports hibernation. However, bare metal instances are not supported.
+ General purpose: M3, M4, M5, M5a, M5ad, M5d, M6a, M6g, M6gd, M6i, M6id, M6idn, M6in, M7a, M7g, M7gd, M7i, M7i-flex, M8a, M8azn, M8g, M8gb, M8gd, M8gn, M8i, M8i-flex, T2, T3, T3a, T4g
+ Compute optimized: C3, C4, C5, C5d, C6a, C6g, C6gd, C6gn, C6i, C6id, C6in, C7a, C7g, C7gd, C7gn, C7i, C7i-flex, C8a, C8g, C8gb, C8gd, C8gn, C8i, C8i-flex
+ Memory optimized: R3, R4, R5, R5a, R5ad, R5d, R6a, R6g, R6gd, R6idn, R6in, R7a, R7g, R7gd, R7i, R7iz, R8a, R8g, R8gb, R8gd, R8gn, R8i, R8i-flex, X2gd, X8aedz, X8i
+ Storage optimized: I3, I3en, I4g, I7i, I7ie, I8g, I8ge, Im4gn, Is4gen
------
#### [ Console ]
**To get the instance types that support hibernation**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation pane, choose **Instance Types**.
1. Add the filter **On-Demand Hibernation support = true**.
1. (Optional) Add filters to further scope to specific instance types of interest.
------
#### [ AWS CLI ]
**To get the instance types that support hibernation**
Use the [describe-instance-types](https://docs.aws.amazon.com/cli/latest/reference/describe-instance-types/.html) command. Note that the available instance types vary by Region.
```
aws ec2 describe-instance-types \
--filters Name=hibernation-supported,Values=true \
--query "InstanceTypes[*].[InstanceType]" \
--output text | sort
```
------
#### [ PowerShell ]
**To get the instance types that support hibernation**
Use the [Get-EC2InstanceType](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-EC2InstanceType.html) cmdlet. Note that the available instance types vary by Region.
```
(Get-EC2InstanceType `
-Filter @{Name="hibernation-supported"; Values="true"}).InstanceType | Sort-Object
```
------
## Instance RAM size
**Linux instances** – Must be less than 150 GiB.
**Windows instances** – Must be less than or equal to 16 GiB. For hibernating a T3 or T3a Windows instance, we recommend at least 1 GiB of RAM.
## Root volume type
The root volume must be an EBS volume, not an instance store volume.
## Root volume size
The root volume must be large enough to store the RAM contents and accommodate your expected usage, for example, OS or applications. If you enable hibernation, space is allocated on the root volume at launch to store the RAM.
## Root volume encryption
The root volume must be encrypted to ensure the protection of sensitive content that is in memory at the time of hibernation. When RAM data is moved to the EBS root volume, it is always encrypted. Encryption of the root volume is enforced at instance launch.
Use one of the following three options to ensure that the root volume is an encrypted EBS volume:
+ **EBS encryption by default** – You can enable EBS encryption by default to ensure that all new EBS volumes created in your AWS account are encrypted. This way, you can enable hibernation for your instances without specifying encryption intent at instance launch. For more information, see [Enable encryption by default](https://docs.aws.amazon.com/ebs/latest/userguide/encryption-by-default.html).
+ **EBS "single-step" encryption** – You can launch encrypted EBS-backed EC2 instances from an unencrypted AMI and also enable hibernation at the same time. For more information, see [Use encryption with EBS-backed AMIs](AMIEncryption.md).
+ **Encrypted AMI** – You can enable EBS encryption by using an encrypted AMI to launch your instance. If your AMI does not have an encrypted root snapshot, you can copy it to a new AMI and request encryption. For more information, see [Encrypt an unencrypted image during copy](AMIEncryption.md#copy-unencrypted-to-encrypted) and [Copy an AMI](CopyingAMIs.md#ami-copy-steps).
## EBS volume type
The EBS volumes must use one of the following EBS volume types:
+ General Purpose SSD (`gp2` and `gp3`)
+ Provisioned IOPS SSD (`io1` and `io2`)
If you choose a Provisioned IOPS SSD volume type, you must provision the EBS volume with the appropriate IOPS to achieve optimum performance for hibernation. For more information, see [Amazon EBS volume types](https://docs.aws.amazon.com/ebs/latest/userguide/ebs-volume-types.html) in the *Amazon EBS User Guide*.
## Spot Instance requests
For Spot Instances, the following requirements apply:
+ The Spot Instance request type must be `persistent`.
+ You can't specify a launch group in the Spot Instance request.
# Configure a Linux AMI to support hibernation
The following Linux AMIs can support hibernating an Amazon EC2 instance, provided you complete the additional configuration steps described in this section.
**Topics**
+ [
## AL2023 minimal AMI released 2023.09.20 or later
](#configure-AL2023-minimal-for-hibernation)
+ [
## Amazon Linux 2 minimal AMI released 2019.08.29 or later
](#configure-AL2-minimal-for-hibernation)
+ [
## Amazon Linux 2 released before 2019.08.29
](#configure-AL2-for-hibernation)
+ [
## Amazon Linux released before 2018.11.16
](#configure-AL-for-hibernation)
+ [
## CentOS version 8 or later
](#configure-centos-for-hibernation)
+ [
## Fedora version 34 or later
](#configure-fedora-for-hibernation)
+ [
## Red Hat Enterprise Linux version 8 or 9
](#configure-RHEL-for-hibernation)
+ [
## Ubuntu 20.04 LTS (Focal Fossa) released before serial number 20210820
](#configure-ubuntu2004-for-hibernation)
+ [
## Ubuntu 18.04 (Bionic Beaver) released before serial number 20190722.1
](#configure-ubuntu1804-for-hibernation)
+ [
## Ubuntu 16.04 (Xenial Xerus)
](#configure-ubuntu1604-for-hibernation)
For the Linux and Windows AMIs that support hibernation and for which *no additional* configuration is required, see [AMIs](hibernating-prerequisites.md#hibernation-prereqs-supported-amis).
For more information, see [Update instance software on your Amazon Linux 2 instance](https://docs.aws.amazon.com/linux/al2/ug/install-updates.html).
## AL2023 minimal AMI released 2023.09.20 or later
**To configure an AL2023 minimal AMI released 2023.09.20 or later to support hibernation**
1. Install the `ec2-hibinit-agent` package from the repositories.
```
[ec2-user ~]$ sudo dnf install ec2-hibinit-agent
```
1. Restart the service.
```
[ec2-user ~]$ sudo systemctl start hibinit-agent
```
## Amazon Linux 2 minimal AMI released 2019.08.29 or later
**To configure an Amazon Linux 2 minimal AMI released 2019.08.29 or later to support hibernation**
1. Install the `ec2-hibinit-agent` package from the repositories.
```
[ec2-user ~]$ sudo yum install ec2-hibinit-agent
```
1. Restart the service.
```
[ec2-user ~]$ sudo systemctl start hibinit-agent
```
## Amazon Linux 2 released before 2019.08.29
**To configure an Amazon Linux 2 AMI released before 2019.08.29 to support hibernation**
1. Update the kernel to `4.14.138-114.102` or later.
```
[ec2-user ~]$ sudo yum update kernel
```
1. Install the `ec2-hibinit-agent` package from the repositories.
```
[ec2-user ~]$ sudo yum install ec2-hibinit-agent
```
1. Reboot the instance.
```
[ec2-user ~]$ sudo reboot
```
1. Confirm that the kernel version is updated to `4.14.138-114.102` or later.
```
[ec2-user ~]$ uname -a
```
1. Stop the instance and create an AMI. For more information, see [Create an Amazon EBS-backed AMI](creating-an-ami-ebs.md).
## Amazon Linux released before 2018.11.16
**To configure an Amazon Linux AMI released before 2018.11.16 to support hibernation**
1. Update the kernel to `4.14.77-70.59` or later.
```
[ec2-user ~]$ sudo yum update kernel
```
1. Install the `ec2-hibinit-agent` package from the repositories.
```
[ec2-user ~]$ sudo yum install ec2-hibinit-agent
```
1. Reboot the instance.
```
[ec2-user ~]$ sudo reboot
```
1. Confirm that the kernel version is updated to `4.14.77-70.59` or greater.
```
[ec2-user ~]$ uname -a
```
1. Stop the instance and create an AMI. For more information, see [Create an Amazon EBS-backed AMI](creating-an-ami-ebs.md).
## CentOS version 8 or later
**To configure a CentOS version 8 or later AMI to support hibernation**
1. Update the kernel to `4.18.0-305.7.1.el8_4.x86_64` or later.
```
[ec2-user ~]$ sudo yum update kernel
```
1. Install the Fedora Extra Packages for Enterprise Linux (EPEL) repository.
```
[ec2-user ~]$ sudo yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
```
1. Install the `ec2-hibinit-agent` package from the repositories.
```
[ec2-user ~]$ sudo yum install ec2-hibinit-agent
```
1. Enable the hibernate agent to start on boot.
```
[ec2-user ~]$ sudo systemctl enable hibinit-agent.service
```
1. Reboot the instance.
```
[ec2-user ~]$ sudo reboot
```
1. Confirm that the kernel version is updated to `4.18.0-305.7.1.el8_4.x86_64` or later.
```
[ec2-user ~]$ uname -a
```
## Fedora version 34 or later
**To configure a Fedora version 34 or later AMI to support hibernation**
1. Update the kernel to `5.12.10-300.fc34.x86_64` or later.
```
[ec2-user ~]$ sudo yum update kernel
```
1. Install the `ec2-hibinit-agent` package from the repositories.
```
[ec2-user ~]$ sudo dnf install ec2-hibinit-agent
```
1. Enable the hibernate agent to start on boot.
```
[ec2-user ~]$ sudo systemctl enable hibinit-agent.service
```
1. Reboot the instance.
```
[ec2-user ~]$ sudo reboot
```
1. Confirm that the kernel version is updated to `5.12.10-300.fc34.x86_64` or later.
```
[ec2-user ~]$ uname -a
```
## Red Hat Enterprise Linux version 8 or 9
**To configure a Red Hat Enterprise Linux 8 or 9 AMI to support hibernation**
1. Update the kernel to `4.18.0-305.7.1.el8_4.x86_64` or later.
```
[ec2-user ~]$ sudo yum update kernel
```
1. Install the Fedora Extra Packages for Enterprise Linux (EPEL) repository.
RHEL version 8:
```
[ec2-user ~]$ sudo yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
```
RHEL version 9:
```
[ec2-user ~]$ sudo yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm
```
1. Install the `ec2-hibinit-agent` package from the repositories.
```
[ec2-user ~]$ sudo yum install ec2-hibinit-agent
```
1. Enable the hibernate agent to start on boot.
```
[ec2-user ~]$ sudo systemctl enable hibinit-agent.service
```
1. Reboot the instance.
```
[ec2-user ~]$ sudo reboot
```
1. Confirm that the kernel version is updated to `4.18.0-305.7.1.el8_4.x86_64` or later.
```
[ec2-user ~]$ uname -a
```
## Ubuntu 20.04 LTS (Focal Fossa) released before serial number 20210820
**To configure an Ubuntu 20.04 LTS (Focal Fossa) AMI released before serial number 20210820 to support hibernation**
1. Update the linux-aws-kernel to `5.8.0-1038.40` or later, and grub2 to `2.04-1ubuntu26.13` or later.
```
[ec2-user ~]$ sudo apt update
[ec2-user ~]$ sudo apt dist-upgrade
```
1. Reboot the instance.
```
[ec2-user ~]$ sudo reboot
```
1. Confirm that the kernel version is updated to `5.8.0-1038.40` or later.
```
[ec2-user ~]$ uname -a
```
1. Confirm that the grub2 version is updated to `2.04-1ubuntu26.13` or later.
```
[ec2-user ~]$ dpkg --list | grep grub2-common
```
## Ubuntu 18.04 (Bionic Beaver) released before serial number 20190722.1
**To configure an Ubuntu 18.04 LTS AMI released before serial number 20190722.1 to support hibernation**
1. Update the kernel to `4.15.0-1044` or later.
```
[ec2-user ~]$ sudo apt update
[ec2-user ~]$ sudo apt dist-upgrade
```
1. Install the `ec2-hibinit-agent` package from the repositories.
```
[ec2-user ~]$ sudo apt install ec2-hibinit-agent
```
1. Reboot the instance.
```
[ec2-user ~]$ sudo reboot
```
1. Confirm that the kernel version is updated to `4.15.0-1044` or later.
```
[ec2-user ~]$ uname -a
```
## Ubuntu 16.04 (Xenial Xerus)
To configure Ubuntu 16.04 LTS to support hibernation, you need to install the linux-aws-hwe kernel package version 4.15.0-1058-aws or later and the ec2-hibinit-agent.
**Important**
The `linux-aws-hwe` kernel package is supported by Canonical. The standard support for Ubuntu 16.04 LTS ended in April 2021, and the package no longer receives regular updates. However, it will receive additional security updates until the Extended Security Maintenance support ends in 2024. For more information, see [Amazon EC2 Hibernation for Ubuntu 16.04 LTS now available](https://ubuntu.com/blog/amazon-ec2-hibernation-for-ubuntu-16-04-lts-now-available) on the Canonical Ubuntu Blog.
We recommend that you upgrade to the Ubuntu 20.04 LTS (Focal Fossa) AMI or the Ubuntu 18.04 LTS (Bionic Beaver) AMI.
**To configure an Ubuntu 16.04 LTS AMI to support hibernation**
1. Update the kernel to `4.15.0-1058-aws` or later.
```
[ec2-user ~]$ sudo apt update
[ec2-user ~]$ sudo apt install linux-aws-hwe
```
1. Install the `ec2-hibinit-agent` package from the repositories.
```
[ec2-user ~]$ sudo apt install ec2-hibinit-agent
```
1. Reboot the instance.
```
[ec2-user ~]$ sudo reboot
```
1. Confirm that the kernel version is updated to `4.15.0-1058-aws` or later.
```
[ec2-user ~]$ uname -a
```
# Enable hibernation for an Amazon EC2 instance
Enable instance hibernation
To hibernate an instance, you must first enable it for hibernation while launching the instance.
**Important**
You can't enable or disable hibernation for an instance after you launch it.
**Topics**
+ [
## Enable hibernation for On-Demand Instances
](#enable-hibernation-for-on-demand-instances)
+ [
## Enable hibernation for Spot Instances
](#enable-hibernation-for-spot-instances)
+ [
## View if an instance is enabled for hibernation
](#view-if-instance-is-enabled-for-hibernation)
## Enable hibernation for On-Demand Instances
You can enable hibernation for your On-Demand Instances.
------
#### [ Console ]
**To enable hibernation for an On-Demand Instance**
1. Follow the procedure to [launch an instance](ec2-launch-instance-wizard.md), but don't launch the instance until you've completed the following steps to enable hibernation.
1. To enable hibernation, configure the following fields in the launch instance wizard:
1. Under **Application and OS Images (Amazon Machine Image)**, select an AMI that supports hibernation. For more information, see [AMIs](hibernating-prerequisites.md#hibernation-prereqs-supported-amis).
1. Under **Instance type**, select a supported instance type. For more information, see [Instance families](hibernating-prerequisites.md#hibernation-prereqs-supported-instance-families).
1. Under **Configure storage**, choose **Advanced** (at the right), and specify the following information for the root volume:
+ For **Size (GiB)**, enter the EBS root volume size. The volume must be large enough to store the RAM contents and accommodate your expected usage.
+ For **Volume type**, select a supported EBS volume type: General Purpose SSD (`gp2` and `gp3`) or Provisioned IOPS SSD (`io1` and `io2`).
+ For **Encrypted**, choose **Yes**. If you enabled encryption by default in this AWS Region, **Yes** is selected.
+ For **KMS key**, select the encryption key for the volume. If you enabled encryption by default in this AWS Region, the default encryption key is selected.
For more information about the prerequisites for the root volume, see [Prerequisites for EC2 instance hibernation](hibernating-prerequisites.md).
1. Expand **Advanced details**, and for **Stop - Hibernate behavior**, choose **Enable**.
1. In the **Summary** panel, review your instance configuration, and then choose **Launch instance**. For more information, see [Launch an EC2 instance using the launch instance wizard in the console](ec2-launch-instance-wizard.md).
------
#### [ AWS CLI ]
**To enable hibernation for an On-Demand Instance**
Use the [run-instances](https://docs.aws.amazon.com/cli/latest/reference/ec2/run-instances.html) command to launch an instance. Specify the EBS root volume parameters using the `--block-device-mappings file://mapping.json` parameter, and enable hibernation using the `--hibernation-options Configured=true` parameter.
```
aws ec2 run-instances \
--image-id ami-0abcdef1234567890 \
--instance-type m5.large \
--block-device-mappings file://mapping.json \
--hibernation-options Configured=true \
--count 1 \
--key-name MyKeyPair
```
Specify the following in `mapping.json`.
```
[
{
"DeviceName": "/dev/xvda",
"Ebs": {
"VolumeSize": 30,
"VolumeType": "gp2",
"Encrypted": true
}
}
]
```
The value for `DeviceName` must match the root device name that's associated with the AMI. To find the root device name, use the [describe-images](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-images.html) command.
```
aws ec2 describe-images --image-id ami-0abcdef1234567890
```
If you enabled encryption by default in this AWS Region, you can omit `"Encrypted": true`.
------
#### [ PowerShell ]
**To enable hibernation for an On-Demand Instance**
Use the [New-EC2Instance](https://docs.aws.amazon.com/powershell/latest/reference/items/New-EC2Instance.html) command to launch an instance. Specify the EBS root volume by first defining the block device mapping, and then adding it to the command using the `-BlockDeviceMappings` parameter. Enable hibernation using the `-HibernationOptions_Configured $true` parameter.
```
$ebs_encrypt = New-Object Amazon.EC2.Model.BlockDeviceMapping
$ebs_encrypt.DeviceName = "/dev/xvda"
$ebs_encrypt.Ebs = New-Object Amazon.EC2.Model.EbsBlockDevice
$ebs_encrypt.Ebs.VolumeSize = 30
$ebs_encrypt.Ebs.VolumeType = "gp2"
$ebs_encrypt.Ebs.Encrypted = $true
New-EC2Instance `
-ImageId ami-0abcdef1234567890 `
-InstanceType m5.large `
-BlockDeviceMappings $ebs_encrypt `
-HibernationOptions_Configured $true `
-MinCount 1 `
-MaxCount 1 `
-KeyName MyKeyPair
```
The value for `DeviceName` must match the root device name associated with the AMI. To find the root device name, use the [Get-EC2Image](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-EC2Image.html) command.
```
Get-EC2Image -ImageId ami-0abcdef1234567890
```
If you enabled encryption by default in this AWS Region, you can omit `Encrypted = $true` from the block device mapping.
------
## Enable hibernation for Spot Instances
You can enable hibernation for your Spot Instances. For more information about hibernating a Spot Instance on interruption, see [Spot Instance interruptions](spot-interruptions.md).
------
#### [ Console ]
**To enable hibernation for a Spot Instance**
1. Follow the procedure to [request a Spot Instance using the launch instance wizard](using-spot-instances-request.md), but don't launch the instance until you've completed the following steps to enable hibernation.
1. To enable hibernation, configure the following fields in the launch instance wizard:
1. Under **Application and OS Images (Amazon Machine Image)**, select an AMI that supports hibernation. For more information, see [AMIs](hibernating-prerequisites.md#hibernation-prereqs-supported-amis).
1. Under **Instance type**, select a supported instance type. For more information, see [Instance families](hibernating-prerequisites.md#hibernation-prereqs-supported-instance-families).
1. Under **Configure storage**, choose **Advanced** (at the right), and specify the following information for the root volume:
+ For **Size (GiB)**, enter the EBS root volume size. The volume must be large enough to store the RAM contents and accommodate your expected usage.
+ For **Volume type**, select a supported EBS volume type: General Purpose SSD (`gp2` and `gp3`) or Provisioned IOPS SSD (`io1` and `io2`).
+ For **Encrypted**, choose **Yes**. If you enabled encryption by default in this AWS Region, **Yes** is selected.
+ For **KMS key**, select the encryption key for the volume. If you enabled encryption by default in this AWS Region, the default encryption key is selected.
For more information about the prerequisites for the root volume, see [Prerequisites for EC2 instance hibernation](hibernating-prerequisites.md).
1. Expand **Advanced details**, and, in addition to the fields for configuring a Spot Instance, do the following:
1. For **Request type**, choose **Persistent**.
1. For **Interruption behavior**, choose **Hibernate**. Alternatively, for **Stop - Hibernate behavior**, choose **Enable**. Both fields enable hibernation on your Spot Instance. You need only configure one of them.
1. In the **Summary** panel, review your instance configuration, and then choose **Launch instance**. For more information, see [Launch an EC2 instance using the launch instance wizard in the console](ec2-launch-instance-wizard.md).
------
#### [ AWS CLI ]
**To enable hibernation for a Spot Instance**
Use the [run-instances](https://docs.aws.amazon.com/cli/latest/reference/ec2/run-instances.html) command to request a Spot Instance. Specify the EBS root volume parameters using the `--block-device-mappings file://mapping.json` parameter, and enable hibernation using the `--hibernation-options Configured=true` parameter. The Spot request type (`SpotInstanceType`) must be `persistent`.
```
aws ec2 run-instances \
--image-id ami-0abcdef1234567890 \
--instance-type c4.xlarge \
--block-device-mappings file://mapping.json \
--hibernation-options Configured=true \
--count 1 \
--key-name MyKeyPair
--instance-market-options
{
"MarketType":"spot",
"SpotOptions":{
"MaxPrice":"1",
"SpotInstanceType":"persistent"
}
}
```
Specify the EBS root volume parameters in `mapping.json` as follows.
```
[
{
"DeviceName": "/dev/xvda",
"Ebs": {
"VolumeSize": 30,
"VolumeType": "gp2",
"Encrypted": true
}
}
]
```
The value for `DeviceName` must match the root device name that's associated with the AMI. To find the root device name, use the [describe-images](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-images.html) command.
```
aws ec2 describe-images --image-id ami-0abcdef1234567890
```
If you enabled encryption by default in this AWS Region, you can omit `"Encrypted": true`.
------
#### [ PowerShell ]
**To enable hibernation for a Spot Instance**
Use the [New-EC2Instance](https://docs.aws.amazon.com/powershell/latest/reference/items/New-EC2Instance.html) command to request a Spot Instance. Specify the EBS root volume by first defining the block device mapping, and then adding it to the command using the `-BlockDeviceMappings` parameter. Enable hibernation using the `-HibernationOptions_Configured $true` parameter.
```
$ebs_encrypt = New-Object Amazon.EC2.Model.BlockDeviceMapping
$ebs_encrypt.DeviceName = "/dev/xvda"
$ebs_encrypt.Ebs = New-Object Amazon.EC2.Model.EbsBlockDevice
$ebs_encrypt.Ebs.VolumeSize = 30
$ebs_encrypt.Ebs.VolumeType = "gp2"
$ebs_encrypt.Ebs.Encrypted = $true
New-EC2Instance `
-ImageId ami-0abcdef1234567890 `
-InstanceType m5.large `
-BlockDeviceMappings $ebs_encrypt `
-HibernationOptions_Configured $true `
-MinCount 1 `
-MaxCount 1 `
-KeyName MyKeyPair `
-InstanceMarketOption @(
MarketType = spot;
SpotOptions @{
MaxPrice = 1;
SpotInstanceType = persistent}
)
```
The value for `DeviceName` must match the root device name associated with the AMI. To find the root device name, use the [Get-EC2Image](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-EC2Image.html) command.
```
Get-EC2Image -ImageId ami-0abcdef1234567890
```
If you enabled encryption by default in this AWS Region, you can omit `Encrypted = $true` from the block device mapping.
------
## View if an instance is enabled for hibernation
You can check whether an instance is enabled for hibernation.
------
#### [ Console ]
**To view if an instance is enabled for hibernation**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation pane, choose **Instances**.
1. Select the instance and, on the **Details** tab, in the **Instance details** section, inspect **Stop-hibernate behavior**. **Enabled** indicates that the instance is enabled for hibernation.
------
#### [ AWS CLI ]
**To view if an instance is enabled for hibernation**
Use the [describe-instances](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instances.html) command and specify the `--filters "Name=hibernation-options.configured,Values=true"` parameter to filter instances that are enabled for hibernation.
```
aws ec2 describe-instances \
--filters "Name=hibernation-options.configured,Values=true"
```
The following field in the output indicates that the instance is enabled for hibernation.
```
"HibernationOptions": {
"Configured": true
}
```
------
#### [ PowerShell ]
**To view if an instance is enabled for hibernation**
Use the [Get-EC2Instance](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-EC2Instance.html) cmdlet and filter instances that are enabled for hibernation.
```
(Get-EC2Instance `
-Filter @{Name="hibernation-options.configured"; Values="true"}).Instances
```
------
# Disable KASLR on an instance (Ubuntu only)
To run hibernation on a newly launched instance with Ubuntu 16.04 LTS (Xenial Xerus), Ubuntu 18.04 LTS (Bionic Beaver) released with serial number 20190722.1 or later, or Ubuntu 20.04 LTS (Focal Fossa) released with serial number 20210820 or later, we recommend disabling KASLR (Kernel Address Space Layout Randomization). On Ubuntu 16.04 LTS, Ubuntu 18.04 LTS, or Ubuntu 20.04 LTS, KASLR is enabled by default.
KASLR is a standard Linux kernel security feature that helps to mitigate exposure to and ramifications of yet-undiscovered memory access vulnerabilities by randomizing the base address value of the kernel. With KASLR enabled, there is a possibility that the instance might not resume after it has been hibernated.
To learn more about KASLR, see [Ubuntu Features](https://wiki.ubuntu.com/Security/Features).
**To disable KASLR on an instance launched with Ubuntu**
1. Connect to your instance using SSH. For more information, see [Connect to your Linux instance using SSH](connect-to-linux-instance.md).
1. Open the `/etc/default/grub.d/50-cloudimg-settings.cfg` file in your editor of choice. Edit the `GRUB_CMDLINE_LINUX_DEFAULT` line to append the `nokaslr` option to its end, as shown in the following example.
```
GRUB_CMDLINE_LINUX_DEFAULT="console=tty1 console=ttyS0 nvme_core.io_timeout=4294967295 nokaslr"
```
1. Save the file and exit your editor.
1. Run the following command to rebuild the grub configuration.
```
sudo update-grub
```
1. Reboot the instance.
```
sudo reboot
```
1. Run the following command to confirm that `nokaslr` has been added.
```
cat /proc/cmdline
```
The output of the command should include the `nokaslr` option.
# Hibernate an Amazon EC2 instance
Hibernate an instance
You can initiate hibernation on an On-Demand Instance or Spot Instance if the instance is an EBS-backed instance, is [enabled for hibernation](enabling-hibernation.md), and meets the [hibernation prerequisites](hibernating-prerequisites.md). If an instance cannot hibernate successfully, a normal shutdown occurs.
------
#### [ Console ]
**To hibernate an instance**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation pane, choose **Instances**.
1. Select an instance, and choose **Instance state**, **Hibernate instance**. If **Hibernate instance** is disabled, the instance is already hibernated or stopped, or it can't be hibernated. For more information, see [Prerequisites for EC2 instance hibernation](hibernating-prerequisites.md).
1. When prompted for confirmation, choose **Hibernate**. It can take a few minutes for the instance to hibernate. The instance state first changes to **Stopping**, and then changes to **Stopped** when the instance has hibernated.
------
#### [ AWS CLI ]
**To hibernate an instance**
Use the [stop-instances](https://docs.aws.amazon.com/cli/latest/reference/ec2/stop-instances.html) command and specify the `--hibernate` parameter.
```
aws ec2 stop-instances \
--instance-ids i-1234567890abcdef0 \
--hibernate
```
------
#### [ PowerShell ]
**To hibernate an instance**
Use the [Stop-EC2Instance](https://docs.aws.amazon.com/powershell/latest/reference/items/Stop-EC2Instance.html) cmdlet.
```
Stop-EC2Instance `
-InstanceId i-1234567890abcdef0 `
-Hibernate $true
```
------
You can check whether hibernation was initiated on an instance.
------
#### [ Console ]
**To view if hibernation was initiated on an instance**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation pane, choose **Instances**.
1. Select the instance and, on the **Details** tab, in the **Instance details** section, check the value for **State transition message**.
**Client.UserInitiatedHibernate: User initiated hibernate** indicates that you initiated hibernation on the On-Demand Instance or Spot Instance.
------
#### [ AWS CLI ]
**To view if hibernation was initiated on an instance**
Use the [describe-instances](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instances.html) command and specify the `state-reason-code` filter to see the instances on which hibernation was initiated.
```
aws ec2 describe-instances \
--filters "Name=state-reason-code,Values=Client.UserInitiatedHibernate"
```
The following field in the output indicates that hibernation was initiated on the On-Demand Instance or Spot Instance.
```
"StateReason": {
"Code": "Client.UserInitiatedHibernate"
}
```
------
#### [ PowerShell ]
**To view if hibernation was initiated on an instance**
Use the [Get-EC2Instance](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-EC2Instance.html) cmdlet and specify the `state-reason-code` filter to see the instances on which hibernation was initiated.
```
Get-EC2Instance `
-Filter @{Name="state-reason-code";Value="Client.UserInitiatedHibernate"}
```
------
# Start a hibernated Amazon EC2 instance
Start a hibernated instance
Start a hibernated instance by starting it in the same way that you would start a stopped instance.
For Spot Instances, if Amazon EC2 hibernated the instance, then only Amazon EC2 can resume it. You can only resume a hibernated Spot Instance if *you* hibernated it. Spot Instances can only be resumed if capacity is available and the Spot price is less than or equal to your specified maximum price.
------
#### [ Console ]
**To start a hibernated instance**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation pane, choose **Instances**.
1. Select a hibernated instance, and choose **Instance state**, **Start instance**. It can take a few minutes for the instance to enter the `running` state. During this time, the instance [status checks](monitoring-system-instance-status-check.md#types-of-instance-status-checks) show the instance in a failed state until the instance has started.
------
#### [ AWS CLI ]
**To start a hibernated instance**
Use the [start-instances](https://docs.aws.amazon.com/cli/latest/reference/ec2/start-instances.html) command.
```
aws ec2 start-instances --instance-ids i-1234567890abcdef0
```
------
#### [ PowerShell ]
**To start a hibernated instance**
Use the [Start-EC2Instance](https://docs.aws.amazon.com/powershell/latest/reference/items/Start-EC2Instance.html) cmdlet.
```
Start-EC2Instance -InstanceId i-1234567890abcdef0
```
------
# Troubleshoot Amazon EC2 instance hibernation
Troubleshoot
Use this information to help diagnose and fix issues that you might encounter when hibernating an instance.
**Topics**
+ [
## Can't hibernate immediately after launch
](#hibernate-troubleshooting-1)
+ [
## Takes too long to transition from stopping to stopped, and memory state not restored after start
](#hibernate-troubleshooting-2)
+ [
## Instance "stuck" in the stopping state
](#hibernate-troubleshooting-3)
+ [
## Can’t start Spot Instance immediately after hibernate
](#hibernate-troubleshooting-4)
+ [
## Resume Spot Instances failed
](#hibernate-troubleshooting-5)
## Can't hibernate immediately after launch
If you try to hibernate an instance too quickly after you've launched it, you get an error.
You must wait for about two minutes for Linux instances and about five minutes for Windows instances after launch before hibernating.
## Takes too long to transition from stopping to stopped, and memory state not restored after start
If it takes a long time for your hibernating instance to transition from the `stopping` state to `stopped`, and if the memory state is not restored after you start, this could indicate that hibernation was not properly configured.
**Linux instances**
Check the instance system log and look for messages that are related to hibernation. To access the system log, [connect](connect-to-linux-instance.md) to the instance or use the [get-console-output](https://docs.aws.amazon.com/cli/latest/reference/ec2/get-console-output.html) command. Find the log lines from the `hibinit-agent`. If the log lines indicate a failure or the log lines are missing, there was most likely a failure configuring hibernation at launch.
For example, the following message indicates that the instance root volume is not large enough: `hibinit-agent: Insufficient disk space. Cannot create setup for hibernation. Please allocate a larger root device.`
If the last log line from the `hibinit-agent` is `hibinit-agent: Running: swapoff /swap`, hibernation was successfully configured.
If you do not see any logs from these processes, your AMI might not support hibernation. For information about supported AMIs, see [Prerequisites for EC2 instance hibernation](hibernating-prerequisites.md). If you used your own Linux AMI, make sure that you followed the instructions for [Configure a Linux AMI to support hibernation](hibernation-enabled-AMI.md).
**Windows Server 2016 and later**
Check the EC2 launch log and look for messages that are related to hibernation. To access the EC2 launch log, [connect](connecting_to_windows_instance.md) to the instance and open the `C:\ProgramData\Amazon\EC2-Windows\Launch\Log\Ec2Launch.log` file in a text editor. If you're using EC2Launch v2, open `C:\ProgramData\Amazon\EC2Launch\log\agent.log`.
**Note**
By default, Windows hides files and folders under `C:\ProgramData`. To view EC2 Launch directories and files, enter the path in Windows Explorer or change the folder properties to show hidden files and folders.
Find the log lines for hibernation. If the log lines indicate a failure or the log lines are missing, there was most likely a failure configuring hibernation at launch.
For example, the following message indicates that hibernation failed to configure: `Message: Failed to enable hibernation.` If the error message includes decimal ASCII values, you can convert the ASCII values to plain text in order to read the full error message.
If the log line contains `HibernationEnabled: true`, hibernation was successfully configured.
**Windows Server 2012 R2 and earlier**
Check the EC2 config log and look for messages that are related to hibernation. To access the EC2 config log, [connect](connecting_to_windows_instance.md) to the instance and open the `C:\Program Files\Amazon\Ec2ConfigService\Logs\Ec2ConfigLog.txt` file in a text editor. Find the log lines for `SetHibernateOnSleep`. If the log lines indicate a failure or the log lines are missing, there was most likely a failure configuring hibernation at launch.
For example, the following message indicates that the instance root volume is not large enough: `SetHibernateOnSleep: Failed to enable hibernation: Hibernation failed with the following error: There is not enough space on the disk.`
If the log line is `SetHibernateOnSleep: HibernationEnabled: true`, hibernation was successfully configured.
**Windows instance size**
If you’re using a T3 or T3a Windows instance with less than 1 GiB of RAM, try increasing the size of the instance to one that has at least 1 GiB of RAM.
## Instance "stuck" in the stopping state
If you hibernated your instance and it appears "stuck" in the `stopping` state, you can forcibly stop it. For more information, see [Troubleshoot Amazon EC2 instance stop issues](TroubleshootingInstancesStopping.md).
## Can’t start Spot Instance immediately after hibernate
If you try to start a Spot Instance within two minutes of hibernating it, you might get the following error:
`You failed to start the Spot Instance because the associated Spot Instance request is not in an appropriate state to support start.`
Wait for about two minutes for Linux instances and about five minutes for Windows instances and then retry starting the instance.
## Resume Spot Instances failed
If your Spot Instance was hibernated successfully but failed to resume, and instead rebooted (a fresh restart where the hibernated state is not retained), it might be because the user data contained the following script:
```
/usr/bin/enable-ec2-spot-hibernation
```
Remove this script from the **User data** field in the launch template, and then request a new Spot Instance.
Note that even if the instance failed to resume, without the hibernated state preserved, the instance can still be started in the same way as starting from the `stopped` state.
# Reboot your Amazon EC2 instance
Reboot
An instance reboot is equivalent to an operating system reboot. In most cases, it takes only a few minutes to reboot your instance.
When you reboot an instance, it keeps the following:
+ Public DNS name (IPv4)
+ Private IPv4 address
+ Public IPv4 address
+ IPv6 address (if applicable)
+ Any data on its instance store volumes
Rebooting an instance doesn't start a new instance billing period, unlike [stopping and starting](Stop_Start.md) an instance (which starts a new billing period with a one-minute minimum charge).
An instance reboot can be user-initiated (where you manually reboot the instance) or initiated by AWS (for automatic instance recovery, or in response to a scheduled reboot event for necessary maintenance, such as to apply updates that require a reboot).
For user-initiated reboots, we recommend using the Amazon EC2 console, CLI, or API instead of running the operating system reboot command from your instance. When using Amazon EC2, if the instance does not cleanly shut down within a few minutes, Amazon EC2 performs a hard reboot. Furthermore, AWS CloudTrail creates an API record of when your instance was rebooted.
This topic describes how to perform a user-initiated reboot. For information about reboots performed by AWS, see [Automatic instance recovery](ec2-instance-recover.md) and [Manage Amazon EC2 instances scheduled for reboot](schedevents_actions_reboot.md).
**Important**
If updates are installing on your instance, we recommend that you do not reboot or shut down your instance using the Amazon EC2 console or the command line until all the updates are installed. When you use the Amazon EC2 console or the command line to reboot or shut down your instance, there is a risk that your instance will be hard rebooted. A hard reboot while updates are being installed could throw your instance into an unstable state.
------
#### [ Console ]
**To reboot an instance**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation pane, choose **Instances**.
1. Select the instance and choose **Instance state**, **Reboot instance**.
1. Choose **Reboot** when prompted for confirmation.
The instance remains in the `running` state.
------
#### [ AWS CLI ]
**To reboot an instance**
Use the [reboot-instances](https://docs.aws.amazon.com/cli/latest/reference/ec2/reboot-instances.html) command.
```
aws ec2 reboot-instances --instance-ids i-1234567890abcdef0
```
------
#### [ PowerShell ]
**To reboot an instance**
Use the [Restart-EC2Instance](https://docs.aws.amazon.com/powershell/latest/reference/items/Restart-EC2Instance.html) cmdlet.
```
Restart-EC2Instance -InstanceId i-1234567890abcdef0
```
------
**To run a controlled fault injection experiment**
You can use AWS Fault Injection Service to test how your application responds when your instance is rebooted. For more information, see the [AWS Fault Injection Service User Guide](https://docs.aws.amazon.com/fis/latest/userguide/what-is.html).
# Terminate Amazon EC2 instances
Terminate
**Warning**
**Terminating an instance is permanent and irreversible.**
After you terminate an instance, you can no longer connect to it, and it can't be recovered. All attached Amazon EBS volumes that are configured to be deleted on termination are also permanently deleted and can't be recovered. All data stored on instance store volumes is permanently lost. For more information, see [How instance termination works](how-ec2-instance-termination-works.md).
Before you terminate an instance, ensure that you have backed up all data that you need to retain after the termination to persistent storage.
You can delete your instance when you no longer need it. This is referred to as *terminating* your instance. As soon as the state of an instance changes to `shutting-down` or `terminated`, you stop incurring charges for that instance.
You can't connect to or start an instance after you've terminated it. However, you can launch new instances using the same AMI.
If you'd rather stop or hibernate your instance, see [Stop and start Amazon EC2 instances](Stop_Start.md) or [Hibernate your Amazon EC2 instance](Hibernate.md). For more information, see [Differences between instance states](ec2-instance-lifecycle.md#lifecycle-differences).
**Topics**
+ [
# How instance termination works
](how-ec2-instance-termination-works.md)
+ [
# Methods for terminating an instance
](instance-terminate-methods.md)
+ [
## Terminate an instance with a graceful OS shutdown
](#terminating-instances-console)
+ [
## Terminate an instance and bypass the graceful OS shutdown
](#terminating-instances-bypass-graceful-os-shutdown)
+ [
## Troubleshoot instance termination
](#troubleshoot-instance-terminate)
+ [
# Change instance termination protection
](Using_ChangingDisableAPITermination.md)
+ [
# Change instance initiated shutdown behavior
](Using_ChangingInstanceInitiatedShutdownBehavior.md)
+ [
# Preserve data when an instance is terminated
](preserving-volumes-on-termination.md)
# How instance termination works
How it works
When you terminate an instance, changes are registered at the operating system (OS) level of the instance, some resources are lost, and some resources persist.
The following diagram shows what is lost and what persists when an Amazon EC2 instance is terminated. When an instance terminates, the data on any instance store volumes and the data stored in the instance RAM is erased. Any Elastic IP addresses associated with the instance are detached. For Amazon EBS root volumes and data volumes, the outcome depends on the **Delete on termination** setting of each volume.
![\[The IP addresses, RAM, instance store volumes, and EBS root volume are lost when an instance is terminated.\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/terminate-instance.png)
## Considerations
+ **Data persistence**
+ Instance store volumes: All data is permanently deleted when the instance terminates.
+ EBS root volume:
+ When attached at launch, deleted by default when the instance terminates.
+ When attached after launch, persists by default when the instance terminates.
+ EBS data volumes:
+ When attached at launch using the console: Persists by default when the instance terminates.
+ When attached at launch using the CLI: Deleted by default when the instance terminates.
+ When attached after launch using the console or CLI: Persists by default when the instance terminates.
**Note**
Any volumes that are not deleted on instance termination continue to incur charges. You can change the setting so that a volume is deleted or persists on instance termination. For more information, see [Preserve data when an instance is terminated](preserving-volumes-on-termination.md).
+ **Protection against accidental termination**
+ To prevent an instance from being accidentally terminated by someone, [enable termination protection](Using_ChangingDisableAPITermination.md).
+ To control whether an instance stops or terminates when shutdown is initiated from the instance, change the [instance initiated shutdown behavior](Using_ChangingInstanceInitiatedShutdownBehavior.md).
+ **Shutdown scripts** – If you run a script on instance termination, your instance might have an abnormal termination because we have no way of ensuring that shutdown scripts run. Amazon EC2 attempts to cleanly shut down an instance and run any system shutdown scripts; however, certain events (such as hardware failure) may prevent these system shutdown scripts from running.
+ **Bare metal instances** – x86 bare metal instances don't support cooperative shutdown.
## What happens when you terminate an instance
**Changes registered at the OS level**
+ The API request sends a button press event to the guest.
+ Various system services are stopped as a result of the button press event. Graceful shutdown of the system is provided by **systemd** (Linux) or the System process (Windows). Graceful shutdown is triggered by the ACPI shutdown button press event from the hypervisor.
+ ACPI shutdown is initiated.
+ The instance shuts down after the graceful shutdown process exits. There is no configurable OS shutdown time. The instance remains visible in the console for a short time, then the entry is automatically deleted.
**Resources lost**
+ Data stored on the instance store volumes.
+ EBS root volume if the `DeleteOnTermination` attribute is set to `true`.
+ EBS data volumes (attached at launch or after) if the `DeleteOnTermination` attribute is set to `true`.
**Resources that persist**
+ EBS root volume if the `DeleteOnTermination` attribute is set to `false`.
+ EBS data volumes (attached at launch or after) if the `DeleteOnTermination` attribute is set to `false`.
## Test application response to instance termination
Test application response
You can use AWS Fault Injection Service to test how your application responds when your instance is terminated. For more information, see the [AWS Fault Injection Service User Guide](https://docs.aws.amazon.com/fis/latest/userguide/what-is.html).
# Methods for terminating an instance
**Warning**
**Terminating an instance is permanent and irreversible.**
After you terminate an instance, you can no longer connect to it, and it can't be recovered. All attached Amazon EBS volumes that are configured to be deleted on termination are also permanently deleted and can't be recovered. All data stored on instance store volumes is permanently lost. For more information, see [How instance termination works](how-ec2-instance-termination-works.md).
Before you terminate an instance, ensure that you have backed up all data that you need to retain after the termination to persistent storage.
There are four ways to perform a user-initiated instance termination: default terminate, terminate with skip OS shutdown, force terminate, and force terminate with skip OS shutdown. The following table compares the key differences between the termination methods:
**Note**
You can't terminate an instance if termination protection is turned on. For more information, see [Change instance termination protection](Using_ChangingDisableAPITermination.md).
| Termination method | Key purpose | Use case | CLI command |
| --- | --- | --- | --- |
| Default terminate | Normal instance shutdown with attempted graceful OS shutdown. | Typical instance termination. | aws ec2 terminate-instances \
--instance-id i-1234567890abcdef0
|
| Terminate with skip OS shutdown | Bypasses the graceful OS shutdown when terminating an instance. | When bypassing graceful OS shutdown is required. | aws ec2 terminate-instances \
--instance-id i-1234567890abcdef0 \
--skip-os-shutdown
|
| Force terminate | Handles stuck instances. Attempts a default termination first; if instance fails to terminate, then forcibly terminates the instance. | When instance is stuck in shutting-down state. | aws ec2 terminate-instances \
--instance-id i-1234567890abcdef0 \
--force
|
| Force terminate with skip OS shutdown | Force terminates and bypasses the graceful OS shutdown when terminating an instance. | When force termination and bypassing graceful OS shutdown is required. | aws ec2 terminate-instances \
--instance-id i-1234567890abcdef0 \
--force \
--skip-os-shutdown
|
For instructions on how to use each method, see the following:
+ [Terminate an instance with a graceful OS shutdown](terminating-instances.md#terminating-instances-console)
+ [Terminate an instance and bypass the graceful OS shutdown](terminating-instances.md#terminating-instances-bypass-graceful-os-shutdown)
+ [Force terminate an instance](TroubleshootingInstancesShuttingDown.md#force-terminate-ec2-instance)
## Terminate an instance with a graceful OS shutdown
You can terminate an instance using the default terminate method, which includes an attempt at a graceful OS shutdown. For more information, see [Methods for terminating an instance](instance-terminate-methods.md).
------
#### [ Console ]
**To terminate an instance using the default terminate method**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation pane, choose **Instances**.
1. Select the instance, and choose **Instance state**, **Terminate (delete) instance**.
1. Choose **Terminate (delete)** when prompted for confirmation.
1. After you terminate an instance, it remains visible for a short while, with a state of `terminated`.
If termination fails or if a terminated instance is visible for more than a few hours, see [Terminated instance still displayed](TroubleshootingInstancesShuttingDown.md#terminated-instance-still-displaying).
------
#### [ AWS CLI ]
**To terminate an instance using the default terminate method**
Use the [terminate-instances](https://docs.aws.amazon.com/cli/latest/reference/ec2/terminate-instances.html) command.
```
aws ec2 terminate-instances --instance-ids i-1234567890abcdef0
```
------
#### [ PowerShell ]
**To terminate an instance using the default terminate method**
Use the [Remove-EC2Instance](https://docs.aws.amazon.com/powershell/latest/reference/items/Remove-EC2Instance.html) cmdlet.
```
Remove-EC2Instance -InstanceId i-1234567890abcdef0
```
------
## Terminate an instance and bypass the graceful OS shutdown
You can bypass the graceful OS shutdown when terminating an instance. For more information, see [Methods for terminating an instance](instance-terminate-methods.md).
------
#### [ Console ]
**To terminate an instance and bypass the graceful OS shutdown**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation pane, choose **Instances**.
1. Select the instance, and choose **Instance state**, **Terminate (delete) instance**.
1. Under **Skip OS shutdown**, select the **Skip OS shutdown** checkbox. If you don't see this option in the console, it's not yet available in the console in the current Region. You can, however, access this feature using the AWS CLI or SDK, or try another Region in the console.
1. Choose **Terminate (delete)**.
1. After you terminate an instance, it remains visible for a short while, with a state of `terminated`.
If termination fails or if a terminated instance is visible for more than a few hours, see [Terminated instance still displayed](TroubleshootingInstancesShuttingDown.md#terminated-instance-still-displaying).
------
#### [ AWS CLI ]
**To terminate an instance and bypass the graceful OS shutdown**
Use the [terminate-instances](https://docs.aws.amazon.com/cli/latest/reference/ec2/terminate-instances.html) command with `--skip-os-shutdown`..
```
aws ec2 terminate-instances \
--instance-ids i-1234567890abcdef0 \
--skip-os-shutdown
```
------
#### [ PowerShell ]
**To terminate an instance and bypass the graceful OS shutdown**
Use the [Remove-EC2Instance](https://docs.aws.amazon.com/powershell/latest/reference/items/Remove-EC2Instance.html) cmdlet with `-SkipOsShutdown $true`..
```
Remove-EC2Instance `
-InstanceId i-1234567890abcdef0 `
-SkipOsShutdown $true
```
------
## Troubleshoot instance termination
The requester must have permission to call `ec2:TerminateInstances`. For more information, see [Example policies to work with instances](ExamplePolicies_EC2.md#iam-example-instances).
If you terminate your instance and another instance starts, most likely you have configured automatic scaling through a feature like EC2 Fleet or Amazon EC2 Auto Scaling. For more information, see [Instances automatically launched or terminated](TroubleshootingInstancesShuttingDown.md#automatic-instance-create-or-delete).
**Note**
You can't terminate an instance if termination protection is turned on. For more information, see [Change instance termination protection](Using_ChangingDisableAPITermination.md).
If your instance is in the `shutting-down` state for longer than usual, you can attempt to force terminate it. If it remains in the `shutting-down` state, it should be cleaned up (terminated) by automated processes within the Amazon EC2 service. For more information, see [Delayed instance termination](TroubleshootingInstancesShuttingDown.md#instance-stuck-terminating).
# Change instance termination protection
Change termination protection
To prevent your instance from being accidentally terminated using the Amazon EC2 API, whether you call `TerminateInstances` directly or using another interface such as the Amazon EC2 console, enable *termination protection* for the instance. The `DisableApiTermination` attribute controls whether the instance can be terminated. By default, termination protection is disabled for your instance. You can set the value of this attribute when you launch an instance, or while the instance is running or stopped.
The `DisableApiTermination` attribute doesn't prevent you from terminating an instance by initiating shutdown from the instance (for example, by using an operating system command for system shutdown) when the `InstanceInitiatedShutdownBehavior` attribute is set to `terminate`. For more information, see [Change instance initiated shutdown behavior](Using_ChangingInstanceInitiatedShutdownBehavior.md).
**Considerations**
+ Enabling termination protection does not prevent AWS from terminating the instance when there is a [scheduled event](monitoring-instances-status-check_sched.md) to terminate the instance.
+ Enabling termination protection does not prevent Amazon EC2 Auto Scaling from terminating an instance when the instance is unhealthy or during scale-in events. You can control whether an Auto Scaling group can terminate a particular instance when scaling using [instance scale-in protection](https://docs.aws.amazon.com/autoscaling/ec2/userguide/ec2-auto-scaling-instance-protection.html). You can control whether an Auto Scaling group can terminate unhealthy instances by [suspending the ReplaceUnhealthy scaling process](https://docs.aws.amazon.com/autoscaling/ec2/userguide/as-suspend-resume-processes.html).
+ You can't enable termination protection for Spot Instances.
------
#### [ Console ]
**To enable termination protection for an instance at launch**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. On the dashboard, choose **Launch instance**.
1. Expand **Advanced details**. For **Termination protection**, select **Enable**.
1. When you are finishing specifying the details for your instance, choose **Launch instance**.
**To change termination protection for an instance**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation pane, select **Instances**.
1. Select the instance.
1. Choose **Actions**, **Instance settings**, **Change termination protection**.
1. For **Termination protection** select or clear **Enable**.
1. Choose **Save**.
------
#### [ AWS CLI ]
**To enable termination protection for an instance**
Use the [modify-instance-attribute](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-attribute.html) command.
```
aws ec2 modify-instance-attribute \
--instance-id i-1234567890abcdef0 \
--disable-api-termination
```
**To disable termination protection for an instance**
Use the [modify-instance-attribute](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-attribute.html) command.
```
aws ec2 modify-instance-attribute \
--instance-id i-1234567890abcdef0 \
--no-disable-api-termination
```
------
#### [ PowerShell ]
**To enable termination protection for an instance**
Use the [Edit-EC2InstanceAttribute](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2InstanceAttribute.html) cmdlet.
```
Edit-EC2InstanceAttribute `
-InstanceId i-1234567890abcdef0 `
-DisableApiTermination $true
```
**To disable termination protection for an instance**
Use the [Edit-EC2InstanceAttribute](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2InstanceAttribute.html) cmdlet.
```
Edit-EC2InstanceAttribute `
-InstanceId i-1234567890abcdef0 `
-DisableApiTermination $false
```
------
## Terminate multiple instances with termination protection
If you terminate multiple instances across multiple Availability Zones in the same request, and one or more of the specified instances are enabled for termination protection, the request fails with the following results:
+ The specified instances that are in the same Availability Zone as the protected instance are not terminated.
+ The specified instances that are in different Availability Zones, where no other specified instances are protected, are successfully terminated.
**Example**
Suppose that you have the following four instances across two Availability Zones.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_ChangingDisableAPITermination.html)
If you attempt to terminate all of these instances in the same request, the request reports failure with the following results:
+ **Instance 1** and **Instance 2** are successfully terminated because neither instance is enabled for termination protection.
+ **Instance 3** and **Instance 4** fail to terminate because **Instance 3** is enabled for termination protection.
# Change instance initiated shutdown behavior
Change initiated shutdown behavior
**Warning**
**Terminating an instance is permanent and irreversible.**
After you terminate an instance, you can no longer connect to it, and it can't be recovered. All attached Amazon EBS volumes that are configured to be deleted on termination are also permanently deleted and can't be recovered. All data stored on instance store volumes is permanently lost. For more information, see [How instance termination works](how-ec2-instance-termination-works.md).
Before you terminate an instance, ensure that you have backed up all data that you need to retain after the termination to persistent storage.
By default, when you initiate a shutdown from an Amazon EBS backed instance (using a command such as **shutdown** or **poweroff**), the instance stops. You can change this behavior so that the instance terminates instead by changing the `InstanceInitiatedShutdownBehavior` attribute for the instance. You can change this attribute while the instance is running or stopped.
The **halt** command doesn't initiate a shutdown. If used, the instance doesn't terminate; instead, it places the CPU into `HLT` and the instance continues to run.
**Note**
The `InstanceInitiatedShutdownBehavior` attribute only applies when you perform a shutdown from the operating system of the instance itself. It doesn't apply when you stop an instance using the `StopInstances` API or the Amazon EC2 console.
------
#### [ Console ]
**To change the instance initiated shutdown behavior**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation pane, choose **Instances**.
1. Select the instance.
1. Choose **Actions**, **Instance settings**, **Change shutdown behavior**.
**Shutdown behavior** displays the current behavior.
1. To change the behavior, for **Shutdown behavior**, choose **Stop** or **Terminate**.
1. Choose **Save**.
------
#### [ AWS CLI ]
**To change the instance initiated shutdown behavior**
Use the [modify-instance-attribute](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-attribute.html) command.
```
aws ec2 modify-instance-attribute \
--instance-id i-1234567890abcdef0 \
--instance-initiated-shutdown-behavior terminate
```
------
#### [ PowerShell ]
**To change the instance initiated shutdown behavior**
Use the [Edit-EC2InstanceAttribute](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2InstanceAttribute.html) cmdlet.
```
Edit-EC2InstanceAttribute `
-InstanceId i-1234567890abcdef0 `
-InstanceInitiatedShutdownBehavior terminate
```
------
# Preserve data when an instance is terminated
When an Amazon EC2 instance is terminated, you can preserve the data on your instance store volumes or Amazon EBS volumes. This topic explains how to ensure your data persists beyond instance termination.
## How instance termination affects root and data volumes
**Instance store volumes**
When an instance is terminated, the instance store volumes are automatically deleted and the data is lost. To preserve this data beyond the lifetime of the instance, before terminating the instance, manually copy the data to persistent storage, such as an Amazon EBS volume, an Amazon S3 bucket, or an Amazon EFS file system. For more information, see [Storage options for your Amazon EC2 instances](Storage.md).
**Amazon EBS volumes**
When an instance is terminated, the EBS volumes are either deleted or preserved, depending on the value of the `DeleteOnTermination` attribute for each volume:
+ **Yes** (console) / `true` (CLI) – The volume is deleted when the instance is terminated.
+ **No** (console) / `false` (CLI) – The volume is preserved when the instance is terminated. Preserved volumes continue to incur charges.
**Note**
After an instance terminates, you can take a snapshot of the preserved volume or attach it to another instance. To avoid incurring charges, you must delete the volume.
## Default deletion behavior for EBS volumes
The default `DeleteOnTermination` value differs depending on the volume type, whether the volume was attached at launch or after, and the method (console or CLI) used to attach the volume:
| Volume type | Attached when | Method for attaching | Default behavior on instance termination |
| --- | --- | --- | --- |
| Root volume | At launch | Console or CLI | Delete |
| Root volume | After launch | Console or CLI | Preserve |
| Data volume | At launch | Console | Preserve |
| Data volume | At launch | CLI | Delete |
| Data volume | After launch | Console and CLI | Preserve |
## Check volume persistence settings
The default value at launch for an EBS volume is determined by the `DeleteOnTermination` attribute set on the AMI. You can change the value at instance launch, overriding the AMI setting. We recommend that you verify the default setting for the `DeleteOnTermination` attribute after you launch an instance.
**To check if an Amazon EBS volume will be deleted on instance termination**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation pane, choose **Instances**.
1. Select the instance.
1. Choose the **Storage** tab.
1. Under **Block devices**, scroll right to check the **Delete on termination** column.
+ If **Yes**, the volume is deleted when the instance is terminated.
+ If **No**, the volume is not be deleted when the instance is terminated. Any volumes not deleted continue to incur charges.
## Change the root volume to persist at launch
You can change the `DeleteOnTermination` attribute of an EBS root volume when you launch an instance. You can also use the following procedure for a data volume.
------
#### [ Console ]
**To change the root volume of an instance to persist at launch**
1. Follow the procedure to [launch an instance](ec2-launch-instance-wizard.md), but don't launch the instance until you've completed the following steps to change the root volume to persist.
1. On the **Configure storage** pane, choose **Advanced**.
1. Under **EBS volumes**, expand the root volume information.
1. For **Delete on termination**, choose **No**.
1. In the **Summary** panel, review your instance configuration, and then choose **Launch instance**. For more information, see [Launch an EC2 instance using the launch instance wizard in the console](ec2-launch-instance-wizard.md).
------
#### [ AWS CLI ]
**To change the root volume of an instance to persist at launch**
Use the [run-instances](https://docs.aws.amazon.com/cli/latest/reference/ec2/run-instances.html) command to change the value of `DeleteOnTermination` in the block device mapping.
Add the `--block-device-mappings` option:
```
--block-device-mappings file://mapping.json
```
In `mapping.json`, specify the device name, for example `/dev/sda1` or `/dev/xvda`, and for `DeleteOnTermination`, specify `false`.
```
[
{
"DeviceName": "device_name",
"Ebs": {
"DeleteOnTermination": false
}
}
]
```
------
#### [ PowerShell ]
**To change the root volume of an instance to persist at launch**
Use the [New-EC2Instance](https://docs.aws.amazon.com/powershell/latest/reference/items/New-EC2Instance.html) cmdlet to change the value of `DeleteOnTermination` in the block device mapping.
Add the `-BlockDeviceMapping` option:
```
-BlockDeviceMapping $bdm
```
In `bdm`, specify the device name, for example `/dev/sda1` or `/dev/xvda`, and for `DeleteOnTermination`, specify `false`.
```
$ebd = New-Object -TypeName Amazon.EC2.Model.EbsBlockDevice
$ebd.DeleteOnTermination = false
$bdm = New-Object -TypeName Amazon.EC2.Model.BlockDeviceMapping
$bdm.DeviceName = "/dev/sda1"
$bdm.Ebs = $ebd
```
------
## Change the root volume of a running instance to persist
You can change the EBS root volume of a running instance to persist. You can also use the following procedure for a data volume.
------
#### [ AWS CLI ]
**To change the root volume to persist**
Use the [modify-instance-attribute](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-attribute.html) command.
```
aws ec2 modify-instance-attribute \
--instance-id i-1234567890abcdef0 \
--block-device-mappings file://mapping.json
```
In `mapping.json`, specify the device name, for example `/dev/sda1` or `/dev/xvda`, and for `--DeleteOnTermination`, specify `false`.
```
[
{
"DeviceName": "device_name",
"Ebs": {
"DeleteOnTermination": false
}
}
]
```
------
#### [ PowerShell ]
**To change the root volume to persist**
Use the [Edit-EC2InstanceAttribute](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2InstanceAttribute.html) cmdlet.
Add the `-BlockDeviceMapping` option:
```
-BlockDeviceMapping $bdm
```
In `bdm`, specify the device name, for example `/dev/sda1` or `/dev/xvda`, and for `DeleteOnTermination`, specify `false`.
```
$ebd = New-Object -TypeName Amazon.EC2.Model.EbsBlockDevice
$ebd.DeleteOnTermination = false
$bdm = New-Object -TypeName Amazon.EC2.Model.BlockDeviceMapping
$bdm.DeviceName = "/dev/sda1"
$bdm.Ebs = $ebd
```
------
# Instance retirement
Retire
An instance is scheduled to be retired when AWS detects irreparable failure of the underlying hardware that hosts the instance. The instance root volume type determines the behavior of instance retirement:
+ If your instance root volume is an Amazon EBS volume, the instance is stopped, and you can start it again at any time. Starting the stopped instance migrates it to new hardware.
+ If your instance root volume is an instance store volume, the instance is terminated, and can't be used again.
For more information about the types of instance events, see [Scheduled events for Amazon EC2 instances](monitoring-instances-status-check_sched.md).
**Topics**
+ [
## Identify instances scheduled for retirement
](#instance-retirement-identify)
+ [
## Actions to take for EBS-backed instances scheduled for retirement
](#instance-retirement-actions-EBS)
+ [
## Actions to take for instance-store backed instances scheduled for retirement
](#instance-retirement-actions-instance-store)
## Identify instances scheduled for retirement
If your instance is scheduled for retirement, you receive an email prior to the event with the instance ID and retirement date. You can also check for instances that are scheduled for retirement.
**Important**
If an instance is scheduled for retirement, we recommend that you take action as soon as possible, because the instance might already be unreachable. For more information, see [Check if your instance is reachable](#check-instance).
**Topics**
+ [
### Monitor the email for the account contacts
](#identify-by-email)
+ [
### Check your instances
](#identify-in-console-cli)
### Monitor the email for the account contacts
If an instance is scheduled for retirement, the primary contact for the account and the operations contact receive an email prior to the event. This email includes the instance ID and scheduled retirement date. For more information, see [Update the primary contact for your AWS account](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-update-contact-primary.html) and [Update the alternate contacts for your AWS account](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-update-contact-alternate.html) in the *AWS Account Management Reference Guide*.
### Check your instances
If you use an email account that you do not check regularly, you might miss an instance retirement notification. You can check whether any of your instances are scheduled for retirement at any time.
------
#### [ Console ]
**To identify instances scheduled for retirement**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation pane, choose **EC2 Dashboard**. Under **Scheduled events**, you can see the events that are associated with your Amazon EC2 instances and volumes, organized by Region.
![\[Scheduled events\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/dashboard-scheduled-events.png)
1. If you have an instance with a scheduled event listed, select its link below the Region name to go to the **Events** page.
1. The **Events** page lists all resources that have events associated with them. To view instances that are scheduled for retirement, select **Instance resources** from the first filter list, and then **Instance stop or retirement** from the second filter list.
1. If the filter results show that an instance is scheduled for retirement, select it, and note the date and time in the **Start time** field in the details pane. This is your instance retirement date.
------
#### [ AWS CLI ]
**To find instances scheduled for retirement**
Use the following [describe-instance-status](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instance-status.html) command. Repeat in each Region where you have running instances.
```
aws ec2 describe-instance-status --filters Name=event.code,Values=instance-retirement
```
------
#### [ PowerShell ]
**To find instances scheduled for retirement**
Use the [Get-EC2InstanceStatus](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-EC2InstanceStatus.html) cmdlet. Repeat in each Region where you have running instances.
```
Get-EC2InstanceStatus -Filter @{Name="event.code"; Values="instance-retirement"}
```
------
## Actions to take for EBS-backed instances scheduled for retirement
To preserve the data on your retiring instance, you can perform one of the following actions. It's important that you take this action before the instance retirement date to prevent unforeseen downtime and data loss.
For Linux instances, if you are not sure whether your instance is backed by EBS or instance store, see [Root volumes for your Amazon EC2 instances](RootDeviceStorage.md).
**Check if your instance is reachable**
When you are notified that your instance is scheduled for retirement, we recommend that you take the following action as soon as possible:
+ Check if your instance is reachable by either [connecting to](connect.md) or pinging your instance.
+ If your instance is reachable, you should plan to stop/start your instance at an appropriate time before the scheduled retirement date, when the impact is minimal. For more information about stopping and starting your instance, and what to expect when your instance is stopped, such as the effect on public, private, and Elastic IP addresses that are associated with your instance, see [Stop and start Amazon EC2 instances](Stop_Start.md). Note that data on instance store volumes is lost when you stop and start your instance.
+ If your instance is unreachable, you should take immediate action and perform a [stop/start](Stop_Start.md) to recover your instance.
+ Alternatively, if you want to [terminate](terminating-instances.md) your instance, plan to do so as soon as possible so that you stop incurring charges for the instance.
**Create a backup of your instance**
Create an EBS-backed AMI from your instance so that you have a backup. To ensure data integrity, stop the instance before you create the AMI. You can wait for the scheduled retirement date when the instance is stopped, or stop the instance yourself before the retirement date. You can start the instance again at any time. For more information, see [Create an Amazon EBS-backed AMI](creating-an-ami-ebs.md).
**Launch a replacement instance**
After you create an AMI from your instance, you can use the AMI to launch a replacement instance. From the Amazon EC2 console, select your new AMI and then choose **Launch instance from AMI**. Configure the parameters for your instance and then choose **Launch instance**. For more information about each field, see [Launch an EC2 instance using the launch instance wizard in the console](ec2-launch-instance-wizard.md).
## Actions to take for instance-store backed instances scheduled for retirement
To preserve the data on your retiring instance, you can perform one of the following actions. It's important that you take this action before the instance retirement date to prevent unforeseen downtime and data loss.
**Warning**
If your instance has an instance store root volume and it passes its retirement date, it is terminated and you cannot recover the instance or any data that was stored on it. Regardless of the root volume type of your instance, the data on instance store volumes is lost when the instance is retired, even if the volumes are attached to an instance with an EBS root volume.
**Check if your instance is reachable**
When you are notified that your instance is scheduled for retirement, we recommend that you take the following action as soon as possible:
+ Check if your instance is reachable by either [connecting](connect-to-linux-instance.md) to or pinging your instance.
+ If your instance is unreachable, there is likely very little that can be done to recover your instance. For more information, see [Troubleshoot an unreachable Amazon EC2 instance](troubleshoot-unreachable-instance.md). AWS will terminate your instance on the scheduled retirement date, so, for an unreachable instance, you can immediately [terminate](terminating-instances.md) the instance yourself.
**Launch a replacement instance**
Create an Amazon S3-backed AMI from your instance using the AMI tools, as described in [Create an Amazon S3-backed AMI](creating-an-ami-instance-store.md). From the Amazon EC2 console, select your new AMI and then choose **Launch instance from AMI**. Configure the parameters for your instance and then choose **Launch instance**. For more information about each field, see [Launch an EC2 instance using the launch instance wizard in the console](ec2-launch-instance-wizard.md).
**Convert your instance to an EBS-backed instance**
Transfer your data to an EBS volume, take a snapshot of the volume, and then create AMI from the snapshot. You can launch a replacement instance from your new AMI. For more information, see [Convert your Amazon S3-backed AMI to an EBS-backed AMI](Using_ConvertingS3toEBS.md).
# Automatic instance recovery
**Important**
This section describes how to proactively configure recovery mechanisms on an EC2 instance. These recovery mechanisms are designed to restore instance availability when AWS detects an underlying hardware or software issue that causes a system status check to fail. If you are currently experiencing problems accessing your instance, see [Troubleshoot EC2 instances](ec2-instance-troubleshoot.md).
If AWS detects that an instance is unavailable due to an underlying hardware or software issue, there are two mechanisms that can automatically restore instance availability—[simplified automatic recovery](instance-configuration-recovery.md) and [Amazon CloudWatch action based recovery](cloudwatch-recovery.md). Restoring instance availability is also known as *instance recovery*.
During the instance recovery process, AWS will attempt to move your instance from the host with the underlying hardware or software issue to a different host. If successful, the instance recovery process will appear to the instance as an unplanned reboot. You can [verify if instance recovery occurred](verify-if-automatic-recovery-occurred.md).
If the recovery process is unsuccessful, the instance might continue running on the host with the underlying hardware or software issue. In this case, manual intervention is required. If the instance becomes unreachable or the system status check continues to fail, we recommend that you manually [stop and start](Stop_Start.md) the instance. When you start an instance, it is typically migrated to a new underlying host computer. However, unlike automatic instance recovery, where the instance retains its public IPv4 address, a restarted instance receives a new public IPv4 address unless it has an Elastic IP address.
To benefit from the automatic recovery mechanisms, they must be configured in advance on an instance before a system status check fails. By default, simplified automatic recovery is enabled during instance launch. You can optionally configure Amazon CloudWatch action based recovery after launch. Having one of these mechanisms configured makes your instance more resilient.
Simplified automatic recovery and Amazon CloudWatch action based recovery are only available on supported instances. For more information, see [Requirements for enabling simplified automatic recovery](instance-configuration-recovery.md#requirements-for-simplified-automatic-recovery) and [Requirements for enabling CloudWatch action based recovery](cloudwatch-recovery.md#requirements-for-cloudwatch-action-based-recovery).
**Warning**
When AWS recovers your instance due to an underlying hardware or software issue, be aware of the following consequences: data stored in volatile memory (RAM) will be lost and the operating system’s uptime will start over from zero. Furthermore, with CloudWatch action based recovery, data on instance store volumes will also be lost. To help protect against data loss, we recommend that you regularly create backups of valuable data. For more information about backup and recovery best practices for EC2 instances, see [Best practices for Amazon EC2](ec2-best-practices.md).
Automatic instance recovery mechanisms are designed for *individual instances*. For guidance on building a resilient *system*, see [Build a resilient system](#instance-recovery-build-a-resilient-system).
**Topics**
+ [
## Key concepts of automatic instance recovery
](#ec2-automatic-instance-recovery-key-concepts)
+ [
## Differences between simplified automatic recovery and CloudWatch action based recovery
](#differences)
+ [
## Build a resilient system
](#instance-recovery-build-a-resilient-system)
+ [
# Verify if automatic instance recovery occurred
](verify-if-automatic-recovery-occurred.md)
+ [
# Configure simplified automatic recovery on an Amazon EC2 instance
](instance-configuration-recovery.md)
+ [
# Configure CloudWatch action based recovery on an EC2 instance
](cloudwatch-recovery.md)
## Key concepts of automatic instance recovery
Automatic instance recovery is an Amazon EC2 feature that automatically restores instance availability when underlying hardware or software failures occur, enhancing the resilience and reliability of your EC2 instances.
The following are key concepts of automatic instance recovery:
**Configuration options**
Two mechanisms can be configured to support automatic instance recovery:
+ [Simplified automatic recovery](instance-configuration-recovery.md): Enabled by default on supported instances.
+ [CloudWatch action based recovery](cloudwatch-recovery.md): Requires manual configuration on supported instances.
**System status checks**
System status checks automatically monitor the AWS infrastructure on which your EC2 instance runs.
+ If a system status check fails, AWS initiates automatic instance recovery, which attempts to migrate the affected instance to different hardware.
+ A failed system status check indicates a problem with the host's hardware or software, and not a problem with the instance itself. Automatic instance recovery can recover an instance that fails a system status check. However, automatic instance recovery does not operate if only the instance status check fails.
+ For the differences between instance and system status checks, see [Types of status checks](monitoring-system-instance-status-check.md#types-of-instance-status-checks).
**Examples of underlying hardware or software problems**
Hardware or software issues that can cause a system status check to fail include loss of network connectivity, loss of system power, software issues on the physical host, and hardware issues on the physical host that impact network reachability.
**Characteristics of recovered instances**
A recovered instance is identical to the original instance, except for the elements that are lost.
Preserved elements:
+ Instance ID
+ Public, private, and Elastic IP addresses
+ Instance metadata
+ Placement group
+ Attached EBS volumes
+ Availability Zone
Lost elements:
+ Data stored in volatile memory (RAM)
+ Data stored on instance store volumes (applicable to CloudWatch action based recovery only)
+ Operating system uptime resets to zero
**Monitoring system status checks with CloudWatch**
The [StatusCheckFailed\$1System](viewing_metrics_with_cloudwatch.md#status-check-metrics) metric in CloudWatch indicates whether a system status check passed or failed.
Metric values:
+ **0** – The system status check passed.
+ **1** – The system status check failed.
**Events in Health Dashboard**
During automatic instance recovery attempts, AWS sends events to your Health Dashboard based on the configured recovery mechanism and its outcome:
+ Simplified automatic recovery
+ Success event: `AWS_EC2_SIMPLIFIED_AUTO_RECOVERY_SUCCESS`
+ Failure event: `AWS_EC2_SIMPLIFIED_AUTO_RECOVERY_FAILURE`
+ CloudWatch action based recovery
+ Success event: `AWS_EC2_INSTANCE_AUTO_RECOVERY_SUCCESS`
+ Failure event: `AWS_EC2_INSTANCE_AUTO_RECOVERY_FAILURE`
## Differences between simplified automatic recovery and CloudWatch action based recovery
The following table compares the key differences between simplified automatic recovery and CloudWatch action based recovery.
| Comparison point | Simplified automatic recovery | CloudWatch action based recovery |
| --- | --- | --- |
| Configuration | Enabled by default on supported instances | Requires manual configuration of CloudWatch alarms and actions |
| Flexibility | Fixed recovery behavior managed by AWS | Customizable actions and conditions |
| Notification | Basic notifications through Health Dashboard | Customizable notifications through SNS |
| Metal instance size | Excluded | Included |
| Instance store volumes attached at launch | Not supported for instances that attach instance store volumes at launch | Supported on selected instance types. Note that data on instance store volumes is lost during instance recovery. |
| Recovery time | Standard recovery attempt | Faster recovery attempts than simplified automatic recovery |
| Host problem resolves during migration | Migration might be canceled and the instance stays on the original host | Migration continues to a new host |
| Cost | No additional cost | Might incur CloudWatch charges |
## Build a resilient system
While simplified automatic recovery and CloudWatch action based recovery are effective for maintaining individual instance availability, AWS recommends implementing a high-availability architecture that allows failover of traffic to healthy instances.
To achieve this, consider using AWS services such as Elastic Load Balancing (which distributes incoming traffic across multiple EC2 instances) and Amazon EC2 Auto Scaling (which automatically adjusts the number of instances based on demand and health).
For more information about building a resilient, fault-tolerant system with EC2 instances, see the following resources:
+ [Back to Basics: Designing for Failure with EC2](https://www.youtube.com/watch?v=5Hq5YxOrKYs) on the *AWS YouTube channel*
+ [Disaster Recovery (DR) Architecture on AWS, Part I: Strategies for Recovery in the Cloud](https://aws.amazon.com/blogs/architecture/disaster-recovery-dr-architecture-on-aws-part-i-strategies-for-recovery-in-the-cloud/) on the *AWS Architecture Blog* site
+ [Application Load Balancers User Guide](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/introduction.html)
+ [Amazon EC2 Auto Scaling User Guide](https://docs.aws.amazon.com/autoscaling/ec2/userguide/what-is-amazon-ec2-auto-scaling.html)
+ [REL11-BP02 Fail over to healthy resources](https://docs.aws.amazon.com/wellarchitected/latest/reliability-pillar/rel_withstand_component_failures_failover2good.html) in the *Reliability Pillar AWS Well-Architected Framework*
# Verify if automatic instance recovery occurred
Verify if automatic recovery occurred
If your instance appears to have been offline and then unexpectedly rebooted, it might have undergone [automatic instance recovery](ec2-instance-recover.md#ec2-automatic-instance-recovery-key-concepts) in response to an underlying hardware or software issue. You can verify this by checking for automatic instance recovery events in your Health Dashboard. You can also check whether an underlying hardware or software issue was detected for your instance by checking the **StatusCheckFailed\$1System** Amazon CloudWatch metric.
## Check for events in Health Dashboard
When an automatic instance recovery attempt occurs, AWS sends events to your Health Dashboard. The specific event depends on the configured recovery mechanism and whether the attempt succeeded or failed.
**To check for automatic instance recovery events in the Health Dashboard**
1. Open the Health Dashboard at [https://phd.aws.amazon.com/phd/home\$1/](https://phd.aws.amazon.com/phd/).
1. Look for the events associated with automatic instance recovery. The presence of these events can confirm whether an attempt at automatic instance recovery occurred and its outcome.
+ Simplified automatic recovery
+ Success event: `AWS_EC2_SIMPLIFIED_AUTO_RECOVERY_SUCCESS`
+ Failure event: `AWS_EC2_SIMPLIFIED_AUTO_RECOVERY_FAILURE`
+ CloudWatch action based recovery
+ Success event: `AWS_EC2_INSTANCE_AUTO_RECOVERY_SUCCESS`
+ Failure event: `AWS_EC2_INSTANCE_AUTO_RECOVERY_FAILURE`
## Monitor system status checks with CloudWatch
You can verify if an underlying hardware or software issue was detected for your instance by checking the [StatusCheckFailed\$1System](viewing_metrics_with_cloudwatch.md#status-check-metrics) metric in CloudWatch. The metric value indicates whether a system status check passed (no hardware or software issue) or failed (hardware or software issue).
**To verify if an underlying hardware or software issue was detected**
1. Open the CloudWatch console **Metrics** page at [https://console.aws.amazon.com/cloudwatch/home?\$1metricsV2](https://console.aws.amazon.com/cloudwatch/home?#metricsV2).
1. Verify that you're in the same Region as your EC2 instance.
1. Paste the following metric in the **Metrics** search field, and press Enter.
```
StatusCheckFailed_System
```
1. Choose **EC2 > Per-Instance Metrics**.
1. In the table, select the check box next to the instance that you want to check.
1. Change the query period to the time that you suspect the recovery event occurred.
1. Choose the **Graphed metrics** tab, and for **StatusCheckFailed\$1System**, do the following:
1. For **Statistic**, choose either **Average**, **Maximum**, or **Minimum**.
1. For **Period**, choose **1 minute**.
1. Check the value for **StatusCheckFailed\$1System**.
+ Value of **0**: The system status check passed, indicating no underlying hardware or software issue.
+ Value of **1**: The system status check failed, indicating an underlying hardware or software issue.
For more information, see [Automatic instance recovery](ec2-instance-recover.md).
# Configure simplified automatic recovery on an Amazon EC2 instance
Simplified automatic recovery
**Important**
This section describes how to proactively configure recovery mechanisms on an EC2 instance. These recovery mechanisms are designed to restore instance availability when AWS detects an underlying hardware or software issue that causes a system status check to fail. If you are currently experiencing problems accessing your instance, see [Troubleshoot EC2 instances](ec2-instance-troubleshoot.md).
If AWS detects that an instance is unavailable due to an underlying hardware or software issue, *simplified automatic recovery* can automatically restore instance availability by moving the instance from the host with the underlying issue to a different host.
If simplified automatic recovery occurs, AWS sends one of the following events to your AWS Health Dashboard, depending on the outcome:
+ Success event: `AWS_EC2_SIMPLIFIED_AUTO_RECOVERY_SUCCESS`
+ Failure event: `AWS_EC2_SIMPLIFIED_AUTO_RECOVERY_FAILURE`
To be notified of these events, you can configure notifications. For more information, see [Creating your first notification configuration in AWS User Notifications](https://docs.aws.amazon.com/notifications/latest/userguide/getting-started.html) in the *AWS User Notifications User Guide*. You can also use [Amazon EventBridge rules](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-rules.html) to monitor simplified automatic recovery events.
Simplified automatic recovery is enabled by default on all supported instances during instance launch. However, it can only operate if an instance is in the `running` state, there are no service events listed in the AWS Health Dashboard, and there is available capacity for the instance type. In some situations, such as significant outages, capacity constraints might cause recovery attempts to fail. For more information, see [Troubleshoot simplified automatic recovery failures](#ec2-instance-recover-simplified-auto-recovery-troubleshooting).
You can disable simplified automatic recovery during or after launch, and re-enable it later if required.
**Warning**
When AWS recovers your instance due to an underlying hardware or software issue, be aware of the following consequences: data stored in volatile memory (RAM) will be lost and the operating system’s uptime will start over from zero. To help protect against data loss, we recommend that you regularly create backups of valuable data. For more information about backup and recovery best practices for EC2 instances, see [Best practices for Amazon EC2](ec2-best-practices.md).
Automatic instance recovery mechanisms are designed for *individual instances*. For guidance on building a resilient *system*, see [Build a resilient system](ec2-instance-recover.md#instance-recovery-build-a-resilient-system).
**Topics**
+ [
## Requirements for enabling simplified automatic recovery
](#requirements-for-simplified-automatic-recovery)
+ [
## Configure simplified automatic recovery
](#set-recovery-behavior)
+ [
## Troubleshoot simplified automatic recovery failures
](#ec2-instance-recover-simplified-auto-recovery-troubleshooting)
## Requirements for enabling simplified automatic recovery
Simplified automatic recovery can be enabled on instances that meet the following criteria:
**Instance types**
+ **General purpose:** A1, M3, M4, M5, M5a, M5n, M5zn, M6a, M6g, M6i, M6in, M7a, M7g, M7i, M7i-flex, M8a, M8azn, M8g, M8gb, M8gn, M8i, M8i-flex, T1, T2, T3, T3a, T4g
+ **Compute optimized:** C3, C4, C5, C5a, C5n, C6a, C6g, C6gn, C6i, C6in, C7a, C7g, C7gn, C7i, C7i-flex, C8a, C8g, C8gb, C8gn, C8i, C8i-flex
+ **Memory optimized:** R3, R4, R5, R5a, R5b, R5n, R6a, R6g, R6i, R6in, R7a, R7g, R7i, R7iz, R8a, R8g, R8gb, R8gn, R8i, R8i-flex, U-3tb1, U-6tb1, U-9tb1, U-12tb1, U-18tb1, U-24tb1, U7i-6tb, U7i-8tb, U7i-12tb, U7in-16tb, U7in-24tb, U7in-32tb, U7inh-32tb, X1, X1e, X2iezn, X8g, X8i
+ **Accelerated computing:** G3, G5g, Inf1, P3, VT1
+ **High-performance computing:** Hpc6a, Hpc7a, Hpc7g, Hpc8a
**Tenancy**
+ Shared
+ Dedicated Instance
For more information, see [Amazon EC2 Dedicated Instances](dedicated-instance.md).
**Limitations**
Simplified automatic recovery is not supported for instances with the following characteristics:
+ Instance size: `metal` instances
+ Tenancy: Dedicated Host. For Dedicated Hosts, use [Dedicated Host Auto Recovery](dedicated-hosts-recovery.md) instead.
+ Storage: Instances with instance store volumes
+ Networking: Instances using an Elastic Fabric Adapter
+ Auto Scaling: Instances that are part of an Auto Scaling group
+ Maintenance: Instances currently undergoing a scheduled maintenance event
## Configure simplified automatic recovery
Simplified automatic recovery is enabled by default when you launch a supported instance. You can set the automatic recovery behavior to `disabled` during or after launching the instance.
The `default` configuration doesn't enable simplified automatic recovery for an unsupported instance.
------
#### [ Console ]
**To disable simplified automatic recovery at launch**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation pane, choose **Instances**, and then choose **Launch instance**.
1. In the **Advanced details** section, for **Instance auto-recovery**, choose **Disabled**.
1. Configure the remaining instance launch settings as needed and then launch the instance.
**To disable simplified automatic recovery after launch**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation pane, choose **Instances**.
1. Select the instance, and then choose **Actions**, **Instance settings**, **Change auto-recovery behavior**.
1. Choose **Off**, and then choose **Save**.
**To enable simplified automatic recovery after launch**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation pane, choose **Instances**.
1. Select the instance, and then choose **Actions**, **Instance settings**, **Change auto-recovery behavior**.
1. Choose **Default (On)**, and then choose **Save**.
------
#### [ AWS CLI ]
**To disable simplified automatic recovery at launch**
Use the [run-instances](https://docs.aws.amazon.com/cli/latest/reference/ec2/run-instance.html) command with the `--maintenance-options` option.
```
--maintenance-options AutoRecovery=Disabled
```
**To disable simplified automatic recovery after launch**
Use the [modify-instance-maintenance-options](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-maintenance-options.html) command.
```
aws ec2 modify-instance-maintenance-options \
--instance-id i-1234567890abcdef0 \
--auto-recovery disabled
```
**To enable simplified automatic recovery after launch**
Use the [modify-instance-maintenance-options](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-maintenance-options.html) command.
```
aws ec2 modify-instance-maintenance-options \
--instance-id i-1234567890abcdef0 \
--auto-recovery default
```
------
#### [ PowerShell ]
**To disable simplified automatic recovery at launch**
Use the [New-EC2Instance](https://docs.aws.amazon.com/powershell/latest/reference/items/New-EC2Instance.html) cmdlet.
```
-MaintenanceOptions_AutoRecovery Disabled
```
**To disable simplified automatic recovery after launch**
Use the [Edit-EC2InstanceMaintenanceOption](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2InstanceMaintenanceOption.html) cmdlet.
```
Edit-EC2InstanceMaintenanceOption `
-InstanceId i-1234567890abcdef0 `
-AutoRecovery Disabled
```
**To enable simplified automatic recovery after launch**
Use the [Edit-EC2InstanceMaintenanceOption](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2InstanceMaintenanceOption.html) cmdlet.
```
Edit-EC2InstanceMaintenanceOption `
-InstanceId i-1234567890abcdef0 `
-AutoRecovery Enabled
```
------
## Troubleshoot simplified automatic recovery failures
If simplified automatic recovery fails to recover your instance, consider the following issues:
+ AWS service events are running
Simplified automatic recovery does not operate during service events in the AWS Health Dashboard. You might not receive recovery failure notifications for such events. For the latest service availability information, see the [Service health](https://health.aws.amazon.com/health/status) status page.
+ Insufficient capacity
There is temporarily insufficient replacement hardware to migrate the instance.
+ Maximum daily recovery attempts reached
The instance has reached the maximum daily allowance for recovery attempts. Your instance might subsequently be retired if automatic recovery fails and a hardware degradation is determined to be the root cause of the original failed system status check.
If the instance’s system status check failure persists despite multiple recovery attempts, see [Troubleshoot instances with failed status checks](TroubleshootingInstances.md) for additional guidance.
# Configure CloudWatch action based recovery on an EC2 instance
CloudWatch action based recovery
**Important**
This section describes how to proactively configure recovery mechanisms on an EC2 instance. These recovery mechanisms are designed to restore instance availability when AWS detects an underlying hardware or software issue that causes a system status check to fail. If you are currently experiencing problems accessing your instance, see [Troubleshoot EC2 instances](ec2-instance-troubleshoot.md).
If AWS detects that an instance is unavailable due to an underlying hardware or software issue, *CloudWatch action based recovery* can automatically restore instance availability by moving the instance from the host with the underlying issue to a different host.
If CloudWatch action based recovery occurs, AWS sends one of the following events to your AWS Health Dashboard, depending on the outcome:
+ Success event: `AWS_EC2_INSTANCE_AUTO_RECOVERY_SUCCESS`
+ Failure event: `AWS_EC2_INSTANCE_AUTO_RECOVERY_FAILURE`
You can configure CloudWatch action based recovery to add recovery actions to Amazon CloudWatch alarms. CloudWatch action based recovery works with the `StatusCheckFailed_System` metric. CloudWatch action based recovery provides to-the-minute recovery response time granularity and Amazon Simple Notification Service (Amazon SNS) notifications of recovery actions and outcomes. These configuration options allow for faster recovery attempts with more granular control over the system status check failure event response compared to simplified automatic recovery. For more information about available CloudWatch options, see [Status checks for your instances](monitoring-system-instance-status-check.md).
However, CloudWatch action based recovery can only operate if an instance is in the `running` state, there are no service events listed in the AWS Health Dashboard, and there is available capacity for the instance type. In some situations, such as significant outages, capacity constraints might cause recovery attempts to fail. For more information, see [Troubleshoot CloudWatch action based recovery failures](#ec2-instance-recover-cloudwatch-troubleshooting).
**Warning**
When AWS recovers your instance due to an underlying hardware or software issue, be aware of the following consequences: data stored in volatile memory (RAM) and on instance store volumes will be lost, and the operating system’s uptime will start over from zero. To help protect against data loss, we recommend that you regularly create backups of valuable data. For more information about backup and recovery best practices for EC2 instances, see [Best practices for Amazon EC2](ec2-best-practices.md).
Automatic instance recovery mechanisms are designed for *individual instances*. For guidance on building a resilient *system*, see [Build a resilient system](ec2-instance-recover.md#instance-recovery-build-a-resilient-system).
**Topics**
+ [
## Requirements for enabling CloudWatch action based recovery
](#requirements-for-cloudwatch-action-based-recovery)
+ [
## Configure CloudWatch action based recovery
](#ec2-instance-recover-cloudwatch-configure)
+ [
## Troubleshoot CloudWatch action based recovery failures
](#ec2-instance-recover-cloudwatch-troubleshooting)
## Requirements for enabling CloudWatch action based recovery
Requirements
CloudWatch action based recovery can be enabled on instances that meet the following criteria:
**Instance types**
+ **General purpose:** A1, M3, M4, M5, M5a, M5n, M5zn, M6a, M6g, M6i, M6in, M7a, M7g, M7i, M7i-flex, M8a, M8azn, M8g, M8gb, M8gn, M8i, M8i-flex, T1, T2, T3, T3a, T4g
+ **Compute optimized:** C3, C4, C5, C5a, C5n, C6a, C6g, C6gn, C6i, C6in, C7a, C7g, C7gn, C7i, C7i-flex, C8a, C8g, C8gb, C8gn, C8i, C8i-flex
+ **Memory optimized:** R3, R4, R5, R5a, R5b, R5n, R6a, R6g, R6i, R6in, R7a, R7g, R7i, R7iz, R8a, R8g, R8gb, R8gn, R8i, R8i-flex, U-3tb1, U-6tb1, U-9tb1, U-12tb1, U-18tb1, U-24tb1, U7i-6tb, U7i-8tb, U7i-12tb, U7in-16tb, U7in-24tb, U7in-32tb, U7inh-32tb, X1, X1e, X2idn, X2iedn, X2iezn, X8g, X8i
+ **Accelerated computing:** G3, G5g, Inf1, P3, VT1
+ **High-performance computing:** Hpc6a, Hpc7a, Hpc7g, Hpc8a
+ **Metal instances:** Any of the above instance types with the metal instance size.
+ **If instance store volumes are added at launch:** Then only the following instance types are supported: M3, C3, R3, X1, X1e, X2idn, X2iedn
**Tenancy**
+ Shared
+ Dedicated Instance
For more information, see [Amazon EC2 Dedicated Instances](dedicated-instance.md).
**Limitations**
CloudWatch action based recovery is not supported for instances with the following characteristics:
+ Tenancy: Dedicated Host. For Dedicated Hosts, use [Dedicated Host Auto Recovery](dedicated-hosts-recovery.md) instead.
+ Networking: Instances using an Elastic Fabric Adapter
+ Auto Scaling: Instances that are part of an Auto Scaling group
+ Maintenance: Instances currently undergoing a scheduled maintenance event
### Find a supported instance type
You can view the instance types that support CloudWatch action based recovery.
------
#### [ Console ]
**To view the instance types that support CloudWatch action based recovery**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the left navigation pane, choose **Instance Types**.
1. In the filter bar, add the filter **Auto Recovery support = true**. The **Instance types** table displays all the instance types that support CloudWatch action based recovery.
1. (Optional) Add filters to further scope to specific instance types of interest.
------
#### [ AWS CLI ]
**To view the instance types that support CloudWatch action based recovery**
Use the [describe-instance-types](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instance-types.html) command with the `auto-recovery-supported` filter.
```
aws ec2 describe-instance-types \
--filters Name=auto-recovery-supported,Values=true \
--query "InstanceTypes[*].[InstanceType]" \
--output text | sort
```
------
#### [ PowerShell ]
**To view the instance types that support CloudWatch action based recovery**
Use the [Get-EC2InstanceType](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-EC2InstanceType.html) cmdlet with the `auto-recovery-supported` filter.
```
Get-EC2InstanceType `
-Filter @{Name="auto-recovery-supported";Values="true"} | `
Select InstanceType | Sort-Object InstanceType
```
------
## Configure CloudWatch action based recovery
To configure CloudWatch action based recovery for an EC2 instance, create a CloudWatch alarm that monitors the `StatusCheckFailed_System` metric for the specified instance. Set the alarm to trigger when the metric value is **1**, indicating a failed system status check. Configure the alarm action to automatically recover the instance when triggered.
You can configure the alarm using either the Amazon EC2 console or the CloudWatch console. For the instructions, see [Add recover actions to Amazon CloudWatch alarms](UsingAlarmActions.md#AddingRecoverActions) in this user guide, or [Adding recover actions to Amazon CloudWatch alarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/UsingAlarmActions.html#AddingRecoverActions) in the *Amazon CloudWatch User Guide*.
## Troubleshoot CloudWatch action based recovery failures
Troubleshoot
If CloudWatch action based recovery fails to recover your instance, consider the following issues:
+ AWS service events are running
CloudWatch action based recovery does not operate during service events in the AWS Health Dashboard. You might not receive recovery failure notifications for such events. For the latest service availability information, see the [Service health](https://health.aws.amazon.com/health/status) status page.
+ Insufficient capacity
There is temporarily insufficient replacement hardware to migrate the instance.
+ Maximum daily recovery attempts reached
The instance has reached the maximum daily allowance for recovery attempts. Your instance might subsequently be retired if automatic recovery fails and a hardware degradation is determined to be the root cause of the original failed system status check.
If the instance’s system status check failure persists despite multiple recovery attempts, see [Troubleshoot instances with failed status checks](TroubleshootingInstances.md) for additional guidance.
# Use instance metadata to manage your EC2 instance
Instance metadata
*Instance metadata* is data about your instance that you can use to configure or manage the running instance. Instance metadata includes the following:
**Instance metadata properties**
Instance metadata properties are divided into [categories](#instancedata-data-categories), for example, host name, events, and security groups.
**Dynamic data**
Dynamic data is metadata that's generated when the instance is launched, such as an instance identity document. For more information, see [Dynamic data categories](#dynamic-data-categories).
**User data**
You can also use instance metadata to access *user data* that you specified when you launched your instance. For example, you can specify parameters for configuring your instance, or include a simple script. You can also build generic AMIs and use user data to modify the configuration files supplied at launch time. For example, if you run web servers for various small businesses, they can all use the same generic AMI and retrieve their content from an Amazon S3 bucket that you specify in the user data at launch. To add a new customer at any time, create a bucket for the customer, add their content, and launch your AMI with the unique bucket name provided to your code in the user data. If you launch multiple instances using the same `RunInstances` call, the user data is available to all instances in that reservation. Each instance that is part of the same reservation has a unique `ami-launch-index` number, so that you can write code that controls what the instances do. For example, the first host might elect itself as the original node in a cluster. For a detailed AMI launch example, see [Identify each instance launched in a single request](AMI-launch-index-examples.md).
**Important**
Although you can only access instance metadata and user data from within the instance itself, the data is not protected by authentication or cryptographic methods. Anyone who has direct access to the instance, and potentially any software running on the instance, can view its metadata. Therefore, you should not store sensitive data, such as passwords or long-lived encryption keys, as user data.
**Topics**
+ [
## Instance metadata categories
](#instancedata-data-categories)
+ [
## Dynamic data categories
](#dynamic-data-categories)
+ [
# Access instance metadata for an EC2 instance
](instancedata-data-retrieval.md)
+ [
# Configure the Instance Metadata Service options
](configuring-instance-metadata-options.md)
+ [
# Run commands when you launch an EC2 instance with user data input
](user-data.md)
+ [
# Identify each instance launched in a single request
](AMI-launch-index-examples.md)
## Instance metadata categories
Instance metadata properties are divided into categories. To retrieve instance metadata properties, you specify the category in the request, and the metadata is returned in the response.
When new categories are released, a new instance metadata build is created with a new version number. In the following table, the **Version when category was released** column specifies the build version when an instance metadata category was released. To avoid having to update your code every time Amazon EC2 releases a new instance metadata build, use `latest` instead of the version number in your metadata requests. For more information, see [Get the available versions of the instance metadata](configuring-instance-metadata-service.md#instance-metadata-ex-1).
When Amazon EC2 releases a new instance metadata category, the instance metadata for the new category might not be available for existing instances. With [Nitro-based instances](instance-types.md#instance-hypervisor-type), you can retrieve instance metadata only for the categories that were available at launch. For instances with the Xen hypervisor, you can [stop and then start](Stop_Start.md) the instance to update the categories that are available for the instance.
The following table lists the categories of instance metadata. Some of the category names include placeholders for data that is unique to your instance. For example, *mac* represents the MAC address for the network interface. You must replace the placeholders with actual values when you retrieve the instance metadata.
| Category | Description | Version when category was released |
| --- | --- | --- |
| ami-id | The AMI ID used to launch the instance. | 1.0 |
| ami-launch-index | If you launch multiple instances using the same RunInstances call, this value indicates the launch order for each instance. The value of the first instance launched is 0. If you launch instances using Auto Scaling or EC2 fleet, this value is always 0. | 1.0 |
| ami-manifest-path | The path to the AMI manifest file in Amazon S3. If you used an Amazon EBS-backed AMI to launch the instance, the returned result is unknown. | 1.0 |
| ancestor-ami-ids | The AMI IDs of any instances that were rebundled to create this AMI. This value will only exist if the AMI manifest file contained an ancestor-amis key. | 2007-10-10 |
| autoscaling/target-lifecycle-state | Value showing the target Auto Scaling lifecycle state that an Auto Scaling instance is transitioning to. Present when the instance transitions to one of the target lifecycle states after March 10, 2022. Possible values: `Detached` \$1 `InService` \$1 `Standby` \$1 `Terminated` \$1 `Warmed:Hibernated` \$1 `Warmed:Running` \$1 `Warmed:Stopped` \$1 `Warmed:Terminated`. See [Retrieve the target lifecycle state through instance metadata](https://docs.aws.amazon.com/autoscaling/ec2/userguide/retrieving-target-lifecycle-state-through-imds.html) in the *Amazon EC2 Auto Scaling User Guide*. | 2021-07-15 |
| block-device-mapping/ami | The virtual device that contains the root/boot file system. | 2007-12-15 |
| block-device-mapping/ebsN | The virtual devices associated with any Amazon EBS volumes. Amazon EBS volumes are only available in metadata if they were present at launch time or when the instance was last started. The N indicates the index of the Amazon EBS volume (such as ebs1 or ebs2). | 2007-12-15 |
| block-device-mapping/ephemeralN | The virtual devices for any non-NVMe instance store volumes. The N indicates the index of each volume. The number of instance store volumes in the block device mapping might not match the actual number of instance store volumes for the instance. The instance type determines the number of instance store volumes that are available to an instance. If the number of instance store volumes in a block device mapping exceeds the number available to an instance, the additional instance store volumes are ignored. | 2007-12-15 |
| block-device-mapping/root | The virtual devices or partitions associated with the root devices or partitions on the virtual device, where the root (/ or C:) file system is associated with the given instance. | 2007-12-15 |
| block-device-mapping/swap | The virtual devices associated with swap. Not always present. | 2007-12-15 |
| events/maintenance/history | If there are completed or canceled maintenance events for the instance, contains a JSON string with information about the events. | 2018-08-17 |
| events/maintenance/scheduled | If there are active maintenance events for the instance, contains a JSON string with information about the events. For more information, see [View scheduled events that affect your Amazon EC2 instances](viewing_scheduled_events.md). | 2018-08-17 |
| events/recommendations/rebalance | The approximate time, in UTC, when the EC2 instance rebalance recommendation notification is emitted for the instance. The following is an example of the metadata for this category: \$1"noticeTime": "2020-11-05T08:22:00Z"\$1. This category is available only after the notification is emitted. For more information, see [EC2 instance rebalance recommendations](rebalance-recommendations.md). | 2020-10-27 |
| hostname | If the EC2 instance is using IP-based naming (IPBN), this is the private IPv4 DNS hostname of the instance. If the EC2 instance is using Resource-based naming (RBN), this is the RBN. In cases where multiple network interfaces are present, this refers to the eth0 device (the device for which the device number is 0). For more information about IPBN and RBN, see [EC2 instance hostnames and domains](ec2-instance-naming.md). | 1.0 |
| iam/info | If there is an IAM role associated with the instance, contains information about the last time the instance profile was updated, including the instance's LastUpdated date, InstanceProfileArn, and InstanceProfileId. Otherwise, not present. | 2012-01-12 |
| iam/security-credentials/role-name | If there is an IAM role associated with the instance, role-name is the name of the role, and role-name contains the temporary security credentials associated with the role (for more information, see [Retrieve security credentials from instance metadata](instance-metadata-security-credentials.md)). Otherwise, not present. | 2012-01-12 |
| identity-credentials/ec2/info | Information about the credentials in identity-credentials/ec2/security-credentials/ec2-instance. | 2018-05-23 |
| identity-credentials/ec2/security-credentials/ec2-instance | Credentials for the instance identity role that allow on-instance software to identify itself to AWS to support features such as EC2 Instance Connect and AWS Systems Manager Default Host Management Configuration. These credentials have no policies attached, so they have no additional AWS API permissions beyond identifying the instance to the AWS feature. For more information, see [Instance identity roles for Amazon EC2 instances](iam-roles-for-amazon-ec2.md#ec2-instance-identity-roles). | 2018-05-23 |
| instance-action | Notifies the instance that it should reboot in preparation for bundling. Valid values: none \$1 shutdown \$1 bundle-pending. | 2008-09-01 |
| instance-id | The ID of this instance. | 1.0 |
| instance-life-cycle | The purchasing option of this instance. For more information, see [Amazon EC2 billing and purchasing options](instance-purchasing-options.md). | 2019-10-01 |
| instance-type | The type of instance. For more information, see [Amazon EC2 instance types](instance-types.md). | 2007-08-29 |
| ipv6 | The IPv6 address of the instance. In cases where multiple network interfaces are present, this refers to the eth0 device (the device for which the device number is 0) network interface and the first IPv6 address assigned. If no IPv6 address exists on network interface[0], this item is not set and results in an HTTP 404 response. | 2021-01-03 |
| kernel-id | The ID of the kernel launched with this instance, if applicable. | 2008-02-01 |
| local-hostname | In cases where multiple network interfaces are present, this refers to the eth0 device (the device for which the device number is 0). If the EC2 instance is using IP-based naming (IPBN), this is the private IPv4 DNS hostname of the instance. If the EC2 instance is using Resource-based naming (RBN), this is the RBN. For more information about IPBN, RBN, and EC2 instance naming, see [EC2 instance hostnames and domains](ec2-instance-naming.md). | 2007-01-19 |
| local-ipv4 | The private IPv4 address of the instance. In cases where multiple network interfaces are present, this refers to the eth0 device (the device for which the device number is 0). If this is an IPv6-only instance, this item is not set and results in an HTTP 404 response. | 1.0 |
| mac | The instance's media access control (MAC) address. In cases where multiple network interfaces are present, this refers to the eth0 device (the device for which the device number is 0). | 2011-01-01 |
| metrics/vhostmd | No longer available. | 2011-05-01 |
| network/interfaces/macs/mac/device-number | The unique device number associated with that interface. The device number corresponds to the device name; for example, a device-number of 2 is for the eth2 device. This category corresponds to the DeviceIndex and device-index fields that are used by the Amazon EC2 API and the EC2 commands for the AWS CLI. | 2011-01-01 |
| network/interfaces/macs/mac/interface-id | The ID of the network interface. | 2011-01-01 |
| network/interfaces/macs/mac/ipv4-associations/public-ip | The private IPv4 addresses that are associated with each public IP address and assigned to that interface. | 2011-01-01 |
| network/interfaces/macs/mac/ipv6s | The IPv6 addresses assigned to the interface. | 2016-06-30 |
| network/interfaces/macs/mac/ipv6-prefix | The IPv6 prefix assigned to the network interface. | |
| network/interfaces/macs/mac/local-hostname | The private IPv4 DNS hostname of the instance. In cases where multiple network interfaces are present, this refers to the eth0 device (the device for which the device number is 0). If this is a IPv6-only instance, this is the resource-based name. For more information about IPBN and RBN, see [EC2 instance hostnames and domains](ec2-instance-naming.md). | 2007-01-19 |
| network/interfaces/macs/mac/local-ipv4s | The private IPv4 addresses associated with the interface. If this is an IPv6-only network interface, this item is not set and results in an HTTP 404 response. | 2011-01-01 |
| network/interfaces/macs/mac/mac | The instance's MAC address. | 2011-01-01 |
| network/interfaces/macs/mac/network-card | The index of the network card. Some instance types support multiple network cards. | 2020-11-01 |
| network/interfaces/macs/mac/owner-id | The ID of the owner of the network interface. In multiple-interface environments, an interface can be attached by a third party, such as Elastic Load Balancing. Traffic on an interface is always billed to the interface owner. | 2011-01-01 |
| network/interfaces/macs/mac/public-hostname | The interface's public DNS (IPv4). This category is only returned if the enableDnsHostnames attribute is set to true. For more information, see [DNS attributes for your VPC](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-dns.html) in the Amazon VPC User Guide. If the instance only has a public-IPv6 address and no public-IPv4 address, this item is not set and results in an HTTP 404 response. | 2011-01-01 |
| network/interfaces/macs/mac/public-ipv4s | The public IP address or Elastic IP addresses associated with the interface. There may be multiple IPv4 addresses on an instance. | 2011-01-01 |
| network/interfaces/macs/mac/security-groups | Security groups to which the network interface belongs. | 2011-01-01 |
| network/interfaces/macs/mac/security-group-ids | The IDs of the security groups to which the network interface belongs. | 2011-01-01 |
| network/interfaces/macs/mac/subnet-id | The ID of the subnet in which the interface resides. | 2011-01-01 |
| network/interfaces/macs/mac/subnet-ipv4-cidr-block | The IPv4 CIDR block of the subnet in which the interface resides. | 2011-01-01 |
| network/interfaces/macs/mac/subnet-ipv6-cidr-blocks | The IPv6 CIDR block of the subnet in which the interface resides. | 2016-06-30 |
| network/interfaces/macs/mac/vpc-id | The ID of the VPC in which the interface resides. | 2011-01-01 |
| network/interfaces/macs/mac/vpc-ipv4-cidr-block | The primary IPv4 CIDR block of the VPC. | 2011-01-01 |
| network/interfaces/macs/mac/vpc-ipv4-cidr-blocks | The IPv4 CIDR blocks for the VPC. | 2016-06-30 |
| network/interfaces/macs/mac/vpc-ipv6-cidr-blocks | The IPv6 CIDR block of the VPC in which the interface resides. | 2016-06-30 |
| placement/availability-zone | The Availability Zone in which the instance launched. | 2008-02-01 |
| placement/availability-zone-id | The static Availability Zone ID in which the instance is launched. The Availability Zone ID is consistent across accounts. However, it might be different from the Availability Zone, which can vary by account. | 2019-10-01 |
| placement/group-name | The name of the placement group in which the instance is launched. | 2020-08-24 |
| placement/host-id | The ID of the host on which the instance is launched. Applicable only to Dedicated Hosts. | 2020-08-24 |
| placement/partition-number | The number of the partition in which the instance is launched. | 2020-08-24 |
| placement/region | The AWS Region in which the instance is launched. | 2020-08-24 |
| product-codes | AWS Marketplace product codes associated with the instance, if any. | 2007-03-01 |
| public-hostname | The instance's public DNS (IPv4). This category is only returned if the enableDnsHostnames attribute is set to true. For more information, see [DNS attributes for your VPC](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-dns.html) in the Amazon VPC User Guide. If the instance only has a public-IPv6 address and no public-IPv4 address, this item is not set and results in an HTTP 404 response. | 2007-01-19 |
| public-ipv4 | The public IPv4 address. If an Elastic IP address is associated with the instance, the value returned is the Elastic IP address. | 2007-01-19 |
| public-keys/0/openssh-key | Public key. Only available if supplied at instance launch time. | 1.0 |
| ramdisk-id | The ID of the RAM disk specified at launch time, if applicable. | 2007-10-10 |
| reservation-id | The ID of the reservation. | 1.0 |
| security-groups | The names of the security groups applied to the instance. After launch, you can change the security groups of the instances. Such changes are reflected here and in network/interfaces/macs/**mac**/security-groups. | 1.0 |
| services/domain | The domain for AWS resources for the Region. | 2014-02-25 |
| services/partition | The partition that the resource is in. For standard AWS Regions, the partition is `aws`. If you have resources in other partitions, the partition is `aws-partitionname`. For example, the partition for resources in the China (Beijing) Region is `aws-cn`. | 2015-10-20 |
| spot/instance-action | The action (hibernate, stop, or terminate) and the approximate time, in UTC, when the action will occur. This item is present only if the Spot Instance has been marked for hibernate, stop, or terminate. For more information, see [instance-action](spot-instance-termination-notices.md#instance-action-metadata). | 2016-11-15 |
| spot/termination-time | The approximate time, in UTC, that the operating system for your Spot Instance will receive the shutdown signal. This item is present and contains a time value (for example, 2015-01-05T18:02:00Z) only if the Spot Instance has been marked for termination by Amazon EC2. The termination-time item is not set to a time if you terminated the Spot Instance yourself. For more information, see [termination-time](spot-instance-termination-notices.md#termination-time-metadata). | 2014-11-05 |
| system | The underlying virtualization type (hypervisor) of the instance. | 2022-09-24 |
| tags/instance | The instance tags associated with the instance. Only available if you explicitly allow access to tags in instance metadata. For more information, see [Enable access to tags in instance metadata](work-with-tags-in-IMDS.md#allow-access-to-tags-in-IMDS). | 2021-03-23 |
## Dynamic data categories
The following table lists the categories of dynamic data.
| Category | Description | Version when category was released |
| --- | --- | --- |
| fws/instance-monitoring | Value showing whether the customer has enabled detailed one-minute monitoring in CloudWatch. Valid values: enabled \$1 disabled | 2009-04-04 |
| instance-identity/document | JSON containing instance attributes, such as instance-id, private IP address, etc. See [Instance identity documents for Amazon EC2 instances](instance-identity-documents.md). | 2009-04-04 |
| instance-identity/pkcs7 | Used to verify the document's authenticity and content against the signature. See [Instance identity documents for Amazon EC2 instances](instance-identity-documents.md). | 2009-04-04 |
| instance-identity/signature | Data that can be used by other parties to verify its origin and authenticity. See [Instance identity documents for Amazon EC2 instances](instance-identity-documents.md). | 2009-04-04 |
# Access instance metadata for an EC2 instance
Access instance metadata
You can access EC2 instance metadata from inside of the instance itself or from the EC2 console, API, SDKs, or the AWS CLI. To get the current instance metadata settings for an instance from the console or command line, see [Query instance metadata options for existing instances](#query-IMDS-existing-instances).
You can also modify user data for instances with an EBS root volume. The instance must be in the stopped state. For console directions, see [Update the instance user data](user-data.md#user-data-modify). For a Linux example that uses the AWS CLI, see [modify-instance-attribute](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-attribute.html). For a Windows example that uses the Tools for Windows PowerShell, see [User data and the Tools for Windows PowerShell](user-data.md#user-data-powershell).
**Note**
You are not billed for HTTP requests used to retrieve instance metadata and user data.
## Instance metadata access considerations
To avoid problems with instance metadata, consider the following.
**Instance launch failures due to IMDSv2 enforcement (`HttpTokensEnforced=enabled`)**
Before enabling IMDSv2 enforcement, you need all your software on the instance to support IMDSv2, after which you can change the default to disable IMDSv1 (`httpTokens=required`), after which you can enable enforcement. For more information, [Transition to using Instance Metadata Service Version 2](instance-metadata-transition-to-version-2.md).
**Command format**
The command format is different, depending on whether you use Instance Metadata Service Version 1 (IMDSv1) or Instance Metadata Service Version 2 (IMDSv2). By default, you can use both versions of the Instance Metadata Service. To require the use of IMDSv2, see [Use the Instance Metadata Service to access instance metadata](configuring-instance-metadata-service.md).
**If IMDSv2 is required, IMDSv1 does not work**
If you use IMDSv1 and receive no response, it's likely that IMDSv2 is required. To check whether IMDSv2 is required, select the instance to view its details. The **IMDSv2** value indicates either **Required** (you must use IMDSv2) or **Optional** (you can use either IMDSv2 or IMDSv1).
**(IMDSv2) Use /latest/api/token to retrieve the token**
Issuing `PUT` requests to any version-specific path, for example `/2021-03-23/api/token`, results in the metadata service returning 403 Forbidden errors. This behavior is intended.
**Metadata version**
To avoid having to update your code every time Amazon EC2 releases a new instance metadata build, we recommend that you use `latest` in the path, and not the version number.
**IPv6 support**
To retrieve instance metadata using an IPv6 address, ensure that you enable and use the IPv6 address of the IMDS `[fd00:ec2::254]` instead of the IPv4 address `169.254.169.254`. The instance must be a [Nitro-based instance](instance-types.md#instance-hypervisor-type) launched in a [subnet that supports IPv6](https://docs.aws.amazon.com/vpc/latest/userguide/configure-subnets.html#subnet-ip-address-range).
**(Windows) Create custom AMIs using Windows Sysprep**
To ensure that IMDS works when you launch an instance from a custom Windows AMI, the AMI must be a standardized image created with Windows Sysprep. Otherwise, the IMDS won't work. For more information, see [Create an Amazon EC2 AMI using Windows Sysprep](ami-create-win-sysprep.md).
**In a container environment, consider reconfiguration or increasing the hop limit to 2**
The AWS SDKs use IMDSv2 calls by default. If the IMDSv2 call receives no response, some AWS SDKs retry the call and, if still unsuccessful, use IMDSv1. This can result in a delay, especially in a container environment. For those AWS SDKs that *require* IMDSv2, if the hop limit is 1 in a container environment, the call might not receive a response at all because going to the container is considered an additional network hop.
To mitigate these issues in a container environment, consider changing the configuration to pass settings (such as the AWS Region) directly to the container, or consider increasing the hop limit to 2. For information about the hop limit impact, see [Add defense in depth against open firewalls, reverse proxies, and SSRF vulnerabilities with enhancements to the EC2 Instance Metadata Service](https://aws.amazon.com/blogs/security/defense-in-depth-open-firewalls-reverse-proxies-ssrf-vulnerabilities-ec2-instance-metadata-service/). For information about changing the hop limit, see [Change the PUT response hop limit](configuring-IMDS-existing-instances.md#modify-PUT-response-hop-limit).
**Packets per second (PPS) limit**
There is a 1024 packet per second (PPS) limit to services that use [link-local](using-instance-addressing.md#link-local-addresses) addresses. This limit includes the aggregate of [Route 53 Resolver DNS Queries](https://docs.aws.amazon.com/vpc/latest/userguide/AmazonDNS-concepts.html#vpc-dns-limits), Instance Metadata Service (IMDS) requests, [Amazon Time Service Network Time Protocol (NTP)](set-time.md) requests, and [Windows Licensing Service (for Microsoft Windows based instances)](https://aws.amazon.com/windows/resources/licensing/) requests.
**Additional considerations for user data access**
+ User data is treated as opaque data: what you specify is what you get back upon retrieval. It is up to the instance to interpret and act on user data.
+ User data must be base64-encoded. Depending on the tool or SDK that you're using, the base64-encoding might be performed for you. For example:
+ The Amazon EC2 console can perform the base64-encoding for you or accept base64-encoded input.
+ [AWS CLI version 2](https://docs.aws.amazon.com/cli/latest/userguide/cliv2-migration-changes.html#cliv2-migration-binaryparam) performs base64-encoding of binary parameters for you by default. AWS CLI version 1 performs the base64-encoding of the `--user-data` parameter for you.
+ The AWS SDK for Python (Boto3) performs base64-encoding of the `UserData` parameter for you.
+ User data is limited to 16 KB, in raw form, before it is base64-encoded. The size of a string of length *n* after base64-encoding is ceil(*n*/3)\$14.
+ User data must be base64-decoded when you retrieve it. If you retrieve the data using instance metadata or the console, it's decoded for you automatically.
+ If you stop an instance, modify its user data, and start the instance, the updated user data is not run automatically when you start the instance. With Windows instances, you can configure settings so that updated user data scripts are run one time when you start the instance or every time you reboot or start the instance.
+ User data is an instance attribute. If you create an AMI from an instance, the instance user data is not included in the AMI.
## Access instance metadata from within an EC2 instance
Because your instance metadata is available from your running instance, you do not need to use the Amazon EC2 console or the AWS CLI. This can be helpful when you're writing scripts to run from your instance. For example, you can access the local IP address of your instance from instance metadata to manage a connection to an external application.
All of the following are considered instance metadata, but they are accessed in different ways. Select the tab that represents the type of instance metadata you want to access to see more information.
------
#### [ Metadata ]
Instance metadata properties are divided into categories. For a description of each instance metadata category, see [Instance metadata categories](ec2-instance-metadata.md#instancedata-data-categories).
To access instance metadata properties from within a running instance, get the data from the following IPv4 or IPv6 URIs. These IP addresses are link-local addresses and are valid only from the instance. For more information, see [Link-local addresses](using-instance-addressing.md#link-local-addresses).
**IPv4**
```
http://169.254.169.254/latest/meta-data/
```
**IPv6**
```
http://[fd00:ec2::254]/latest/meta-data/
```
------
#### [ Dynamic data ]
To retrieve dynamic data from within a running instance, use one of the following URIs.
**IPv4**
```
http://169.254.169.254/latest/dynamic/
```
**IPv6**
```
http://[fd00:ec2::254]/latest/dynamic/
```
**Examples: Access with cURL**
The following examples use `cURL` to retrieve the high-level instance identity categories.
*IMDSv2*
```
[ec2-user ~]$ TOKEN=`curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600"` \
&& curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/dynamic/instance-identity/
rsa2048
pkcs7
document
signature
dsa2048
```
*IMDSv1*
```
[ec2-user ~]$ curl http://169.254.169.254/latest/dynamic/instance-identity/
rsa2048
pkcs7
document
signature
dsa2048
```
**Examples: Access with PowerShell**
The following examples use PowerShell to retrieve the high-level instance identity categories.
*IMDSv2*
```
PS C:\> [string]$token = Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token-ttl-seconds" = "21600"} -Method PUT -Uri http://169.254.169.254/latest/api/token
```
```
PS C:\> Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = $token} -Method GET -Uri http://169.254.169.254/latest/dynamic/instance-identity/
document
rsa2048
pkcs7
signature
```
*IMDSv1*
```
PS C:\> Invoke-RestMethod -uri http://169.254.169.254/latest/dynamic/instance-identity/
document
rsa2048
pkcs7
signature
```
For more information about dynamic data and examples of how to retrieve it, see [Instance identity documents for Amazon EC2 instances](instance-identity-documents.md).
------
#### [ User data ]
To retrieve user data from an instance, use one of the following URIs. To retrieve user data using the IPv6 address, you must enable it, and the instance must be a [Nitro-based instance](instance-types.md#instance-hypervisor-type) in a subnet that supports IPv6.
**IPv4**
```
http://169.254.169.254/latest/user-data
```
**IPv6**
```
http://[fd00:ec2::254]/latest/user-data
```
A request for user data returns the data as it is (content type `application/octet-stream`). If the instance does not have any user data, the request returns `404 - Not Found`.
**Examples: Access with cURL to retrieve comma-separated text**
The following examples use `cURL` to retrieve user data that was specified as comma-separated text.
*IMDSv2*
```
TOKEN=`curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600"` \
&& curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/user-data
1234,john,reboot,true | 4512,richard, | 173,,,
```
*IMDSv1*
```
curl http://169.254.169.254/latest/user-data
1234,john,reboot,true | 4512,richard, | 173,,,
```
**Examples: Access with PowerShell to retrieve comma-separated text**
The following examples use PowerShell to retrieve user data that was specified as comma-separated text.
*IMDSv2*
```
[string]$token = Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token-ttl-seconds" = "21600"} -Method PUT -Uri http://169.254.169.254/latest/api/token
```
```
Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = $token} -Method GET -Uri http://169.254.169.254/latest/user-data
1234,john,reboot,true | 4512,richard, | 173,,,
```
*IMDSv1*
```
Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token-ttl-seconds" = "21600"} `
-Method PUT -Uri http://169.254.169.254/latest/api/token} -Method GET -uri http://169.254.169.254/latest/user-data
1234,john,reboot,true | 4512,richard, | 173,,,
```
**Examples: Access with cURL to retrieve a script**
The following examples use `cURL` to retrieve user data that was specified as a script.
*IMDSv2*
```
TOKEN=`curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600"` \
&& curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/user-data
#!/bin/bash
yum update -y
service httpd start
chkconfig httpd on
```
*IMDSv1*
```
curl http://169.254.169.254/latest/user-data
#!/bin/bash
yum update -y
service httpd start
chkconfig httpd on
```
**Examples: Access with PowerShell to retrieve a script**
The following examples use PowerShell to retrieve user data that was specified as a script.
*IMDSv2*
```
[string]$token = Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token-ttl-seconds" = "21600"} -Method PUT -Uri http://169.254.169.254/latest/api/token
```
```
Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = $token} -Method GET -Uri http://169.254.169.254/latest/user-data
$file = $env:SystemRoot + "\Temp\" + (Get-Date).ToString("MM-dd-yy-hh-mm")
New-Item $file -ItemType file
true
```
*IMDSv1*
```
Invoke-RestMethod -uri http://169.254.169.254/latest/user-data
$file = $env:SystemRoot + "\Temp\" + (Get-Date).ToString("MM-dd-yy-hh-mm")
New-Item $file -ItemType file
true
```
------
## Query instance metadata options for existing instances
Query instance metadata options
You can query the instance metadata options for your existing instances.
------
#### [ Console ]
**To query the instance metadata options for an existing instance**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation pane, choose **Instances**.
1. Select your instance and check the following fields:
+ **IMDSv2** – The value is either **Required** or **Optional**.
+ **Allow tags in instance metadata** – The value is either **Enabled** or **Disabled**.
1. With your instance selected, choose **Actions**, **Instance settings**, **Modify instance metadata options**.
The dialog box displays whether the instance metadata service is enabled or disabled for the selected instance.
------
#### [ AWS CLI ]
**To query the instance metadata options for an existing instance**
Use the [describe-instances](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instances.html) command.
```
aws ec2 describe-instances \
--instance-id i-1234567898abcdef0 \
--query 'Reservations[].Instances[].MetadataOptions'
```
------
#### [ PowerShell ]
**To query the instance metadata options for an existing instance using the Tools for PowerShell**
Use the [Get-EC2Instance](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-EC2Instance.html) cmdlet.
```
(Get-EC2Instance `
-InstanceId i-1234567898abcdef0).Instances.MetadataOptions
```
------
## Responses and error messages
All instance metadata is returned as text (HTTP content type `text/plain`).
A request for a specific metadata resource returns the appropriate value, or a `404 - Not Found` HTTP error code if the resource is not available.
A request for a general metadata resource (the URI ends with a /) returns a list of available resources, or a `404 - Not Found` HTTP error code if there is no such resource. The list items are on separate lines, terminated by line feeds (ASCII 10).
If an IMDSv1 request receives no response, it's likely that IMDSv2 is required.
For requests made using IMDSv2, the following HTTP error codes can be returned:
+ `400 - Missing or Invalid Parameters` – The `PUT` request is not valid.
+ `401 - Unauthorized` – The `GET` request uses an invalid token. The recommended action is to generate a new token.
+ `403 - Forbidden` – The request is not allowed or the IMDS is turned off.
+ `404 - Not Found` – The resource is not available or there is no such resource.
+ `503` – The request could not be completed. Retry the request.
If the IMDS returns an error, **curl** prints the error message in the output and returns a success status code. The error message is stored in the `TOKEN` variable, which causes **curl** commands that use the token to fail. If you call **curl** with the **-f** option, it returns an error status code in the event of an HTTP server error. If you enable error handling, the shell can catch the error and stop the script.
## Query throttling
We throttle queries to the IMDS on a per-instance basis, and we place limits on the number of simultaneous connections from an instance to the IMDS.
If you're using the IMDS to retrieve AWS security credentials, avoid querying for credentials during every transaction or concurrently from a high number of threads or processes, as this might lead to throttling. Instead, we recommend that you cache the credentials until they start approaching their expiry time. For more information about IAM role and security credentials associated with the role, see [Retrieve security credentials from instance metadata](instance-metadata-security-credentials.md).
If you are throttled while accessing the IMDS, retry your query with an exponential backoff strategy.
# Use the Instance Metadata Service to access instance metadata
Use the IMDS
You can access instance metadata from a running instance using one of the following methods:
+ Instance Metadata Service Version 2 (IMDSv2) – a session-oriented method
For examples, see [Examples for IMDSv2](#instance-metadata-retrieval-examples).
+ Instance Metadata Service Version 1 (IMDSv1) – a request/response method
For examples, see [Examples for IMDSv1](#instance-metadata-retrieval-examples-imdsv1).
By default, you can use either IMDSv1 or IMDSv2, or both.
You can configure the Instance Metadata Service (IMDS) on each instance to only accept IMDSv2 calls, which will cause IMDSv1 calls to fail. For information about how to configure your instance to use IMDSv2, see [Configure the Instance Metadata Service options](configuring-instance-metadata-options.md).
The `PUT` or `GET` headers are unique to IMDSv2. If these headers are present in the request, then the request is intended for IMDSv2. If no headers are present, it is assumed the request is intended for IMDSv1.
For an extensive review of IMDSv2, see [Add defense in depth against open firewalls, reverse proxies, and SSRF vulnerabilities with enhancements to the EC2 Instance Metadata Service](https://aws.amazon.com/blogs/security/defense-in-depth-open-firewalls-reverse-proxies-ssrf-vulnerabilities-ec2-instance-metadata-service/).
**Topics**
+ [
## How Instance Metadata Service Version 2 works
](#instance-metadata-v2-how-it-works)
+ [
## Use a supported AWS SDK
](#use-a-supported-sdk-version-for-imdsv2)
+ [
## Examples for IMDSv2
](#instance-metadata-retrieval-examples)
+ [
## Examples for IMDSv1
](#instance-metadata-retrieval-examples-imdsv1)
## How Instance Metadata Service Version 2 works
How IMDSv2 works
IMDSv2 uses session-oriented requests. With session-oriented requests, you create a session token that defines the session duration, which can be a minimum of one second and a maximum of six hours. During the specified duration, you can use the same session token for subsequent requests. After the specified duration expires, you must create a new session token to use for future requests.
**Note**
The examples in this section use the IPv4 address of the Instance Metadata Service (IMDS): `169.254.169.254`. If you are retrieving instance metadata for EC2 instances over the IPv6 address, ensure that you enable and use the IPv6 address instead: `[fd00:ec2::254]`. The IPv6 address of the IMDS is compatible with IMDSv2 commands. The IPv6 address is only accessible on [Nitro-based instances](instance-types.md#instance-hypervisor-type) in an [IPv6-supported subnet](https://docs.aws.amazon.com/vpc/latest/userguide/configure-subnets.html#subnet-ip-address-range) (dual stack or IPv6 only).
The following examples use a shell script and IMDSv2 to retrieve the top-level instance metadata items. Each example:
+ Creates a session token lasting six hours (21,600 seconds) using the `PUT` request
+ Stores the session token header in a variable named `TOKEN` (Linux instances) or `token` (Windows instances)
+ Requests the top-level metadata items using the token
### Linux example
You can run two separate commands, or combine them.
**Separate commands**
First, generate a token using the following command.
```
[ec2-user ~]$ TOKEN=`curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600"`
```
Then, use the token to generate top-level metadata items using the following command.
```
[ec2-user ~]$ curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/
```
**Combined commands**
You can store the token and combine the commands. The following example combines the above two commands and stores the session token header in a variable named TOKEN.
**Note**
If there is an error in creating the token, instead of a valid token, an error message is stored in the variable, and the command will not work.
```
[ec2-user ~]$ TOKEN=`curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600"` \
&& curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/
```
After you've created a token, you can reuse it until it expires. In the following example command, which gets the ID of the AMI used to launch the instance, the token that is stored in `$TOKEN` in the previous example is reused.
```
[ec2-user ~]$ curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/ami-id
```
### Windows example
```
PS C:\> [string]$token = Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token-ttl-seconds" = "21600"} -Method PUT -Uri http://169.254.169.254/latest/api/token
```
```
PS C:\> Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = $token} -Method GET -Uri http://169.254.169.254/latest/meta-data/
```
After you've created a token, you can reuse it until it expires. In the following example command, which gets the ID of the AMI used to launch the instance, the token that is stored in `$token` in the previous example is reused.
```
PS C:\> Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = $token} `
-Method GET -uri http://169.254.169.254/latest/meta-data/ami-id
```
When you use IMDSv2 to request instance metadata, the request must include the following:
1. Use a `PUT` request to initiate a session to the instance metadata service. The `PUT` request returns a token that must be included in subsequent `GET` requests to the instance metadata service. The token is required to access metadata using IMDSv2.
1. Include the token in all `GET` requests to the IMDS. When token usage is set to `required`, requests without a valid token or with an expired token receive a `401 - Unauthorized` HTTP error code.
+ The token is an instance-specific key. The token is not valid on other EC2 instances and will be rejected if you attempt to use it outside of the instance on which it was generated.
+ The `PUT` request must include a header that specifies the time to live (TTL) for the token, in seconds, up to a maximum of six hours (21,600 seconds). The token represents a logical session. The TTL specifies the length of time that the token is valid and, therefore, the duration of the session.
+ After a token expires, to continue accessing instance metadata, you must create a new session using another `PUT`.
+ You can choose to reuse a token or create a new token with every request. For a small number of requests, it might be easier to generate and immediately use a token each time you need to access the IMDS. But for efficiency, you can specify a longer duration for the token and reuse it rather than having to write a `PUT` request every time you need to request instance metadata. There is no practical limit on the number of concurrent tokens, each representing its own session. IMDSv2 is, however, still constrained by normal IMDS connection and throttling limits. For more information, see [Query throttling](instancedata-data-retrieval.md#instancedata-throttling).
HTTP `GET` and `HEAD` methods are allowed in IMDSv2 instance metadata requests. `PUT` requests are rejected if they contain an X-Forwarded-For header.
By default, the response to `PUT` requests has a response hop limit (time to live) of `1` at the IP protocol level. If you need a bigger hop limit, you can adjust it by using the [modify-instance-metadata-options](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-metadata-options.html) AWS CLI command. For example, you might need a bigger hop limit for backward compatibility with container services running on the instance. For more information, see [Modify instance metadata options for existing instances](configuring-IMDS-existing-instances.md).
## Use a supported AWS SDK
Supported SDKs
To use IMDSv2, your EC2 instances must use an AWS SDK version that supports using IMDSv2. The latest versions of all the AWS SDKs support using IMDSv2.
**Important**
We recommend that you to stay up to date with SDK releases to keep up with the latest features, security updates, and underlying dependencies. Continued use of an unsupported SDK version is not recommended and is done at your discretion. For more information, see the [AWS SDKs and Tools maintenance policy](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html) in the *AWS SDKs and Tools Reference Guide*.
The following are the minimum versions that support using IMDSv2:
+ [AWS CLI](https://github.com/aws/aws-cli) – 1.16.289
+ [AWS Tools for Windows PowerShell](https://github.com/aws/aws-tools-for-powershell) – 4.0.1.0
+ [AWS SDK for .NET](https://github.com/aws/aws-sdk-net) – 3.3.634.1
+ [AWS SDK for C\$1\$1](https://github.com/aws/aws-sdk-cpp) – 1.7.229
+ [AWS SDK for Go](https://github.com/aws/aws-sdk-go) – 1.25.38
+ [AWS SDK for Go v2](https://github.com/aws/aws-sdk-go-v2) – 0.19.0
+ [AWS SDK for Java](https://github.com/aws/aws-sdk-java) – 1.11.678
+ [AWS SDK for Java 2.x](https://github.com/aws/aws-sdk-java-v2) – 2.10.21
+ [AWS SDK for JavaScript in Node.js](https://github.com/aws/aws-sdk-js) – 2.722.0
+ [AWS SDK for Kotlin](https://github.com/awslabs/aws-sdk-kotlin) – 1.1.4
+ [AWS SDK for PHP](https://github.com/aws/aws-sdk-php) – 3.147.7
+ [AWS SDK for Python (Botocore)](https://github.com/boto/botocore) – 1.13.25
+ [AWS SDK for Python (Boto3)](https://github.com/boto/boto3) – 1.12.6
+ [AWS SDK for Ruby](https://github.com/aws/aws-sdk-ruby) – 3.79.0
## Examples for IMDSv2
Run the following examples on your Amazon EC2 instance to retrieve the instance metadata for IMDSv2.
On Windows instances, you can use Windows PowerShell or you can install cURL or wget. If you install a third-party tool on a Windows instance, ensure that you read the accompanying documentation carefully, as the calls and the output might be different from what is described here.
**Topics**
+ [
### Get the available versions of the instance metadata
](#instance-metadata-ex-1)
+ [
### Get the top-level metadata items
](#instance-metadata-ex-2)
+ [
### Get the values for metadata items
](#instance-metadata-ex-2a)
+ [
### Get the list of available public keys
](#instance-metadata-ex-3)
+ [
### Show the formats in which public key 0 is available
](#instance-metadata-ex-4)
+ [
### Get public key 0 (in the OpenSSH key format)
](#instance-metadata-ex-5)
+ [
### Get the subnet ID for an instance
](#instance-metadata-ex-6)
+ [
### Get the instance tags for an instance
](#instance-metadata-ex-7)
### Get the available versions of the instance metadata
This example gets the available versions of the instance metadata. Each version refers to an instance metadata build when new instance metadata categories were released. The instance metadata build versions do not correlate with the Amazon EC2 API versions. The earlier versions are available to you in case you have scripts that rely on the structure and information present in a previous version.
------
#### [ cURL ]
```
[ec2-user ~]$ TOKEN=`curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600"` \
&& curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/
1.0
2007-01-19
2007-03-01
2007-08-29
2007-10-10
2007-12-15
2008-02-01
2008-09-01
2009-04-04
2011-01-01
2011-05-01
2012-01-12
2014-02-25
2014-11-05
2015-10-20
2016-04-19
...
latest
```
------
#### [ PowerShell ]
```
PS C:\> [string]$token = Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token-ttl-seconds" = "21600"} -Method PUT -Uri http://169.254.169.254/latest/api/token
```
```
PS C:\> Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = $token} -Method GET -Uri http://169.254.169.254/
1.0
2007-01-19
2007-03-01
2007-08-29
2007-10-10
2007-12-15
2008-02-01
2008-09-01
2009-04-04
2011-01-01
2011-05-01
2012-01-12
2014-02-25
2014-11-05
2015-10-20
2016-04-19
...
latest
```
------
### Get the top-level metadata items
This example gets the top-level metadata items. For more information about the items in the response, see [Instance metadata categories](ec2-instance-metadata.md#instancedata-data-categories).
Note that tags are included in this output only if you've allowed access. For more information, see [Enable access to tags in instance metadata](work-with-tags-in-IMDS.md#allow-access-to-tags-in-IMDS).
------
#### [ cURL ]
```
[ec2-user ~]$ TOKEN=`curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600"` \
&& curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/
ami-id
ami-launch-index
ami-manifest-path
block-device-mapping/
events/
hostname
iam/
instance-action
instance-id
instance-life-cycle
instance-type
local-hostname
local-ipv4
mac
metrics/
network/
placement/
profile
public-hostname
public-ipv4
public-keys/
reservation-id
security-groups
services/
tags/
```
------
#### [ PowerShell ]
```
PS C:\> [string]$token = Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token-ttl-seconds" = "21600"} -Method PUT -Uri http://169.254.169.254/latest/api/token
```
```
PS C:\> Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = $token} -Method GET -Uri http://169.254.169.254/latest/meta-data/
ami-id
ami-launch-index
ami-manifest-path
block-device-mapping/
hostname
iam/
instance-action
instance-id
instance-life-cycle
instance-type
local-hostname
local-ipv4
mac
metrics/
network/
placement/
profile
public-hostname
public-ipv4
public-keys/
reservation-id
security-groups
services/
tags/
```
------
### Get the values for metadata items
These examples get the values of some of the top-level metadata items that were obtained in the preceding example. These requests use the stored token that was created using the command in the previous example. The token must not be expired.
------
#### [ cURL ]
```
[ec2-user ~]$ curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/ami-id
ami-0abcdef1234567890
```
```
[ec2-user ~]$ curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/reservation-id
r-0efghijk987654321
```
```
[ec2-user ~]$ curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/local-hostname
ip-10-251-50-12.ec2.internal
```
```
[ec2-user ~]$ curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/public-hostname
ec2-203-0-113-25.compute-1.amazonaws.com
```
------
#### [ PowerShell ]
```
PS C:\> Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = $token} -Method GET -Uri http://169.254.169.254/latest/meta-data/ami-id
ami-0abcdef1234567890
```
```
PS C:\> Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = $token} -Method GET -Uri http://169.254.169.254/latest/meta-data/reservation-id
r-0efghijk987654321
```
```
PS C:\> Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = $token} -Method GET -Uri http://169.254.169.254/latest/meta-data/local-hostname
ip-10-251-50-12.ec2.internal
```
```
PS C:\> Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = $token} -Method GET -Uri http://169.254.169.254/latest/meta-data/public-hostname
ec2-203-0-113-25.compute-1.amazonaws.com
```
------
### Get the list of available public keys
This example gets the list of available public keys.
------
#### [ cURL ]
```
[ec2-user ~]$ TOKEN=`curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600"` \
&& curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/public-keys/
0=my-public-key
```
------
#### [ PowerShell ]
```
PS C:\> [string]$token = Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token-ttl-seconds" = "21600"} -Method PUT -Uri http://169.254.169.254/latest/api/token
```
```
PS C:\> Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = $token} -Method GET -Uri http://169.254.169.254/latest/meta-data/public-keys/
0=my-public-key
```
------
### Show the formats in which public key 0 is available
This example shows the formats in which public key 0 is available.
------
#### [ cURL ]
```
[ec2-user ~]$ TOKEN=`curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600"` \
&& curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/public-keys/0/
openssh-key
```
------
#### [ PowerShell ]
```
PS C:\> [string]$token = Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token-ttl-seconds" = "21600"} -Method PUT -Uri http://169.254.169.254/latest/api/token
```
```
PS C:\> Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = $token} -Method GET -Uri http://169.254.169.254/latest/meta-data/public-keys/0/openssh-key
openssh-key
```
------
### Get public key 0 (in the OpenSSH key format)
This example gets public key 0 (in the OpenSSH key format).
------
#### [ cURL ]
```
[ec2-user ~]$ TOKEN=`curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600"` \
&& curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/public-keys/0/openssh-key
ssh-rsa MIICiTCCAfICCQD6m7oRw0uXOjANBgkqhkiG9w0BAQUFADCBiDELMAkGA1UEBhMC
VVMxCzAJBgNVBAgTAldBMRAwDgYDVQQHEwdTZWF0dGxlMQ8wDQYDVQQKEwZBbWF6
b24xFDASBgNVBAsTC0lBTSBDb25zb2xlMRIwEAYDVQQDEwlUZXN0Q2lsYWMxHzAd
BgkqhkiG9w0BCQEWEG5vb25lQGFtYXpvbi5jb20wHhcNMTEwNDI1MjA0NTIxWhcN
MTIwNDI0MjA0NTIxWjCBiDELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAldBMRAwDgYD
VQQHEwdTZWF0dGxlMQ8wDQYDVQQKEwZBbWF6b24xFDASBgNVBAsTC0lBTSBDb25z
b2xlMRIwEAYDVQQDEwlUZXN0Q2lsYWMxHzAdBgkqhkiG9w0BCQEWEG5vb25lQGFt
YXpvbi5jb20wgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAMaK0dn+a4GmWIWJ
21uUSfwfEvySWtC2XADZ4nB+BLYgVIk60CpiwsZ3G93vUEIO3IyNoH/f0wYK8m9T
rDHudUZg3qX4waLG5M43q7Wgc/MbQITxOUSQv7c7ugFFDzQGBzZswY6786m86gpE
Ibb3OhjZnzcvQAaRHhdlQWIMm2nrAgMBAAEwDQYJKoZIhvcNAQEFBQADgYEAtCu4
nUhVVxYUntneD9+h8Mg9q6q+auNKyExzyLwaxlAoo7TJHidbtS4J5iNmZgXL0Fkb
FFBjvSfpJIlJ00zbhNYS5f6GuoEDmFJl0ZxBHjJnyp378OD8uTs7fLvjx79LjSTb
NYiytVbZPQUQ5Yaxu2jXnimvw3rrszlaEXAMPLE my-public-key
```
------
#### [ PowerShell ]
```
PS C:\> [string]$token = Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token-ttl-seconds" = "21600"} -Method PUT -Uri http://169.254.169.254/latest/api/token
```
```
PS C:\> Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = $token} -Method GET -Uri http://169.254.169.254/latest/meta-data/public-keys/0/openssh-key
ssh-rsa MIICiTCCAfICCQD6m7oRw0uXOjANBgkqhkiG9w0BAQUFADCBiDELMAkGA1UEBhMC
VVMxCzAJBgNVBAgTAldBMRAwDgYDVQQHEwdTZWF0dGxlMQ8wDQYDVQQKEwZBbWF6
b24xFDASBgNVBAsTC0lBTSBDb25zb2xlMRIwEAYDVQQDEwlUZXN0Q2lsYWMxHzAd
BgkqhkiG9w0BCQEWEG5vb25lQGFtYXpvbi5jb20wHhcNMTEwNDI1MjA0NTIxWhcN
MTIwNDI0MjA0NTIxWjCBiDELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAldBMRAwDgYD
VQQHEwdTZWF0dGxlMQ8wDQYDVQQKEwZBbWF6b24xFDASBgNVBAsTC0lBTSBDb25z
b2xlMRIwEAYDVQQDEwlUZXN0Q2lsYWMxHzAdBgkqhkiG9w0BCQEWEG5vb25lQGFt
YXpvbi5jb20wgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAMaK0dn+a4GmWIWJ
21uUSfwfEvySWtC2XADZ4nB+BLYgVIk60CpiwsZ3G93vUEIO3IyNoH/f0wYK8m9T
rDHudUZg3qX4waLG5M43q7Wgc/MbQITxOUSQv7c7ugFFDzQGBzZswY6786m86gpE
Ibb3OhjZnzcvQAaRHhdlQWIMm2nrAgMBAAEwDQYJKoZIhvcNAQEFBQADgYEAtCu4
nUhVVxYUntneD9+h8Mg9q6q+auNKyExzyLwaxlAoo7TJHidbtS4J5iNmZgXL0Fkb
FFBjvSfpJIlJ00zbhNYS5f6GuoEDmFJl0ZxBHjJnyp378OD8uTs7fLvjx79LjSTb
NYiytVbZPQUQ5Yaxu2jXnimvw3rrszlaEXAMPLE my-public-key
```
------
### Get the subnet ID for an instance
This example gets the subnet ID for an instance.
------
#### [ cURL ]
```
[ec2-user ~]$ TOKEN=`curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600"` \
&& curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/network/interfaces/macs/02:29:96:8f:6a:2d/subnet-id
subnet-be9b61d7
```
------
#### [ PowerShell ]
```
PS C:\> [string]$token = Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token-ttl-seconds" = "21600"} -Method PUT -Uri http://169.254.169.254/latest/api/token
```
```
PS C:\> Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = $token} -Method GET -Uri http://169.254.169.254/latest/meta-data/network/interfaces/macs/02:29:96:8f:6a:2d/subnet-id
subnet-be9b61d7
```
------
### Get the instance tags for an instance
If access to instance tags in the instance metadata is turned on, you can get the tags for a instance from instance metadata. For more information, see [Retrieve tags from instance metadata](work-with-tags-in-IMDS.md#retrieve-tags-from-IMDS).
## Examples for IMDSv1
Run the following examples on your Amazon EC2 instance to retrieve the instance metadata for IMDSv1.
On Windows instances, you can use Windows PowerShell or you can install cURL or wget. If you install a third-party tool on a Windows instance, ensure that you read the accompanying documentation carefully, as the calls and the output might be different from what is described here.
**Topics**
+ [
### Get the available versions of the instance metadata
](#instance-metadata-ex-1-imdsv1)
+ [
### Get the top-level metadata items
](#instance-metadata-ex-2-imdsv1)
+ [
### Get the values for metadata items
](#instance-metadata-ex-2a-imdsv1)
+ [
### Get the list of available public keys
](#instance-metadata-ex-3-imdsv1)
+ [
### Show the formats in which public key 0 is available
](#instance-metadata-ex-4-imdsv1)
+ [
### Get public key 0 (in the OpenSSH key format)
](#instance-metadata-ex-5-imdsv1)
+ [
### Get the subnet ID for an instance
](#instance-metadata-ex-6-imdsv1)
+ [
### Get the instance tags for an instance
](#instance-metadata-ex-7-imdsv1)
### Get the available versions of the instance metadata
This example gets the available versions of the instance metadata. Each version refers to an instance metadata build when new instance metadata categories were released. The instance metadata build versions do not correlate with the Amazon EC2 API versions. The earlier versions are available to you in case you have scripts that rely on the structure and information present in a previous version.
------
#### [ cURL ]
```
[ec2-user ~]$ curl http://169.254.169.254/
1.0
2007-01-19
2007-03-01
2007-08-29
2007-10-10
2007-12-15
2008-02-01
2008-09-01
2009-04-04
2011-01-01
2011-05-01
2012-01-12
2014-02-25
2014-11-05
2015-10-20
2016-04-19
...
latest
```
------
#### [ PowerShell ]
```
PS C:\> Invoke-RestMethod -uri http://169.254.169.254/
1.0
2007-01-19
2007-03-01
2007-08-29
2007-10-10
2007-12-15
2008-02-01
2008-09-01
2009-04-04
2011-01-01
2011-05-01
2012-01-12
2014-02-25
2014-11-05
2015-10-20
2016-04-19
...
latest
```
------
### Get the top-level metadata items
This example gets the top-level metadata items. For more information about the items in the response, see [Instance metadata categories](ec2-instance-metadata.md#instancedata-data-categories).
Note that tags are included in this output only if you've allowed access. For more information, see [Enable access to tags in instance metadata](work-with-tags-in-IMDS.md#allow-access-to-tags-in-IMDS).
------
#### [ cURL ]
```
[ec2-user ~]$ curl http://169.254.169.254/latest/meta-data/
ami-id
ami-launch-index
ami-manifest-path
block-device-mapping/
events/
hostname
iam/
instance-action
instance-id
instance-type
local-hostname
local-ipv4
mac
metrics/
network/
placement/
profile
public-hostname
public-ipv4
public-keys/
reservation-id
security-groups
services/
tags/
```
------
#### [ PowerShell ]
```
PS C:\> Invoke-RestMethod -uri http://169.254.169.254/latest/meta-data/
ami-id
ami-launch-index
ami-manifest-path
block-device-mapping/
hostname
iam/
instance-action
instance-id
instance-type
local-hostname
local-ipv4
mac
metrics/
network/
placement/
profile
public-hostname
public-ipv4
public-keys/
reservation-id
security-groups
services/
tags/
```
------
### Get the values for metadata items
These examples get the values of some of the top-level metadata items that were obtained in the previous example.
------
#### [ cURL ]
```
[ec2-user ~]$ curl http://169.254.169.254/latest/meta-data/ami-id
ami-0abcdef1234567890
```
```
[ec2-user ~]$ curl http://169.254.169.254/latest/meta-data/reservation-id
r-0efghijk987654321
```
```
[ec2-user ~]$ curl http://169.254.169.254/latest/meta-data/local-hostname
ip-10-251-50-12.ec2.internal
```
```
[ec2-user ~]$ curl http://169.254.169.254/latest/meta-data/public-hostname
ec2-203-0-113-25.compute-1.amazonaws.com
```
------
#### [ PowerShell ]
```
PS C:\> Invoke-RestMethod -uri http://169.254.169.254/latest/meta-data/ami-id
ami-0abcdef1234567890
```
```
PS C:\> Invoke-RestMethod -uri http://169.254.169.254/latest/meta-data/reservation-id
r-0efghijk987654321
```
```
PS C:\> Invoke-RestMethod -uri http://169.254.169.254/latest/meta-data/local-hostname
ip-10-251-50-12.ec2.internal
```
```
PS C:\> Invoke-RestMethod -uri http://169.254.169.254/latest/meta-data/public-hostname
ec2-203-0-113-25.compute-1.amazonaws.com
```
------
### Get the list of available public keys
This example gets the list of available public keys.
------
#### [ cURL ]
```
[ec2-user ~]$ curl http://169.254.169.254/latest/meta-data/public-keys/
0=my-public-key
```
------
#### [ PowerShell ]
```
PS C:\> Invoke-RestMethod -uri http://169.254.169.254/latest/meta-data/public-keys/ 0=my-public-key
```
------
### Show the formats in which public key 0 is available
This example shows the formats in which public key 0 is available.
------
#### [ cURL ]
```
[ec2-user ~]$ curl http://169.254.169.254/latest/meta-data/public-keys/0/
openssh-key
```
------
#### [ PowerShell ]
```
PS C:\> Invoke-RestMethod -uri http://169.254.169.254/latest/meta-data/public-keys/0/openssh-key
openssh-key
```
------
### Get public key 0 (in the OpenSSH key format)
This example gets public key 0 (in the OpenSSH key format).
------
#### [ cURL ]
```
[ec2-user ~]$ curl http://169.254.169.254/latest/meta-data/public-keys/0/openssh-key
ssh-rsa MIICiTCCAfICCQD6m7oRw0uXOjANBgkqhkiG9w0BAQUFADCBiDELMAkGA1UEBhMC
VVMxCzAJBgNVBAgTAldBMRAwDgYDVQQHEwdTZWF0dGxlMQ8wDQYDVQQKEwZBbWF6
b24xFDASBgNVBAsTC0lBTSBDb25zb2xlMRIwEAYDVQQDEwlUZXN0Q2lsYWMxHzAd
BgkqhkiG9w0BCQEWEG5vb25lQGFtYXpvbi5jb20wHhcNMTEwNDI1MjA0NTIxWhcN
MTIwNDI0MjA0NTIxWjCBiDELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAldBMRAwDgYD
VQQHEwdTZWF0dGxlMQ8wDQYDVQQKEwZBbWF6b24xFDASBgNVBAsTC0lBTSBDb25z
b2xlMRIwEAYDVQQDEwlUZXN0Q2lsYWMxHzAdBgkqhkiG9w0BCQEWEG5vb25lQGFt
YXpvbi5jb20wgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAMaK0dn+a4GmWIWJ
21uUSfwfEvySWtC2XADZ4nB+BLYgVIk60CpiwsZ3G93vUEIO3IyNoH/f0wYK8m9T
rDHudUZg3qX4waLG5M43q7Wgc/MbQITxOUSQv7c7ugFFDzQGBzZswY6786m86gpE
Ibb3OhjZnzcvQAaRHhdlQWIMm2nrAgMBAAEwDQYJKoZIhvcNAQEFBQADgYEAtCu4
nUhVVxYUntneD9+h8Mg9q6q+auNKyExzyLwaxlAoo7TJHidbtS4J5iNmZgXL0Fkb
FFBjvSfpJIlJ00zbhNYS5f6GuoEDmFJl0ZxBHjJnyp378OD8uTs7fLvjx79LjSTb
NYiytVbZPQUQ5Yaxu2jXnimvw3rrszlaEXAMPLE my-public-key
```
------
#### [ PowerShell ]
```
PS C:\> Invoke-RestMethod -uri http://169.254.169.254/latest/meta-data/public-keys/0/openssh-key
ssh-rsa MIICiTCCAfICCQD6m7oRw0uXOjANBgkqhkiG9w0BAQUFADCBiDELMAkGA1UEBhMC
VVMxCzAJBgNVBAgTAldBMRAwDgYDVQQHEwdTZWF0dGxlMQ8wDQYDVQQKEwZBbWF6
b24xFDASBgNVBAsTC0lBTSBDb25zb2xlMRIwEAYDVQQDEwlUZXN0Q2lsYWMxHzAd
BgkqhkiG9w0BCQEWEG5vb25lQGFtYXpvbi5jb20wHhcNMTEwNDI1MjA0NTIxWhcN
MTIwNDI0MjA0NTIxWjCBiDELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAldBMRAwDgYD
VQQHEwdTZWF0dGxlMQ8wDQYDVQQKEwZBbWF6b24xFDASBgNVBAsTC0lBTSBDb25z
b2xlMRIwEAYDVQQDEwlUZXN0Q2lsYWMxHzAdBgkqhkiG9w0BCQEWEG5vb25lQGFt
YXpvbi5jb20wgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAMaK0dn+a4GmWIWJ
21uUSfwfEvySWtC2XADZ4nB+BLYgVIk60CpiwsZ3G93vUEIO3IyNoH/f0wYK8m9T
rDHudUZg3qX4waLG5M43q7Wgc/MbQITxOUSQv7c7ugFFDzQGBzZswY6786m86gpE
Ibb3OhjZnzcvQAaRHhdlQWIMm2nrAgMBAAEwDQYJKoZIhvcNAQEFBQADgYEAtCu4
nUhVVxYUntneD9+h8Mg9q6q+auNKyExzyLwaxlAoo7TJHidbtS4J5iNmZgXL0Fkb
FFBjvSfpJIlJ00zbhNYS5f6GuoEDmFJl0ZxBHjJnyp378OD8uTs7fLvjx79LjSTb
NYiytVbZPQUQ5Yaxu2jXnimvw3rrszlaEXAMPLE my-public-key
```
------
### Get the subnet ID for an instance
This example gets the subnet ID for an instance.
------
#### [ cURL ]
```
[ec2-user ~]$ curl http://169.254.169.254/latest/meta-data/network/interfaces/macs/02:29:96:8f:6a:2d/subnet-id
subnet-be9b61d7
```
------
#### [ PowerShell ]
```
PS C:\> Invoke-RestMethod -uri http://169.254.169.254/latest/meta-data/network/interfaces/macs/02:29:96:8f:6a:2d/subnet-id
subnet-be9b61d7
```
------
### Get the instance tags for an instance
If access to instance tags in the instance metadata is turned on, you can get the tags for a instance from instance metadata. For more information, see [Retrieve tags from instance metadata](work-with-tags-in-IMDS.md#retrieve-tags-from-IMDS).
# Transition to using Instance Metadata Service Version 2
Transition to IMDSv2
If you want to configure your instances to only accept Instance Metadata Service Version 2 (IMDSv2) calls, we recommend that you use the following tools and transition path.
**Topics**
+ [
## Tools for transitioning to IMDSv2
](#tools-for-transitioning-to-imdsv2)
+ [
## Recommended path to requiring IMDSv2
](#recommended-path-for-requiring-imdsv2)
## Tools for transitioning to IMDSv2
The following tools can help you identify, monitor, and manage the transition of your software from IMDSv1 to IMDSv2. For the instructions on how to use these tools, see [Recommended path to requiring IMDSv2](#recommended-path-for-requiring-imdsv2).
**AWS software**
The latest versions of the AWS CLI and AWS SDKs support IMDSv2. To use IMDSv2, update your EC2 instances to use the latest versions. For the minimum AWS SDK versions that support IMDSv2, see [Use a supported AWS SDK](configuring-instance-metadata-service.md#use-a-supported-sdk-version-for-imdsv2).
All Amazon Linux 2 and Amazon Linux 2023 software packages support IMDSv2. Amazon Linux 2023 disables IMDSv1 by default.
**IMDS Packet Analyzer**
IMDS Packet Analyzer is an open-source tool that identifies and logs IMDSv1 calls during your instance’s boot phase and runtime operations. By analyzing these logs, you can precisely identify the software making IMDSv1 calls on your instances and determine what needs to be updated to support IMDSv2 only on your instances. You can run IMDS Packet Analyzer from a command line or install it as a service. For more information, see [AWS ImdsPacketAnalyzer](https://github.com/aws/aws-imds-packet-analyzer) on *GitHub*.
**CloudWatch**
CloudWatch provides the following two metrics for monitoring your instances:
`MetadataNoToken` – IMDSv2 uses token-backed sessions, while IMDSv1 does not. The `MetadataNoToken` metric tracks the number of calls to the Instance Metadata Service (IMDS) that are using IMDSv1. By tracking this metric to zero, you can determine if and when all of your software has been upgraded to use IMDSv2.
`MetadataNoTokenRejected` – After you've disabled IMDSv1, you can use the `MetadataNoTokenRejected` metric to track the number of times an IMDSv1 call was attempted and rejected. By tracking this metric, you can ascertain whether your software needs to be updated to use IMDSv2.
For each EC2 instance, these metrics are mutually exclusive. When IMDSv1 is enabled (`httpTokens = optional`), only `MetadataNoToken` emits. When IMDSv1 is disabled (`httpTokens = required`), only `MetadataNoTokenRejected` emits. For when to use these metrics, see [Recommended path to requiring IMDSv2](#recommended-path-for-requiring-imdsv2).
For more information, see [Instance metrics](viewing_metrics_with_cloudwatch.md#ec2-cloudwatch-metrics).
**Launch APIs**
**New instances:** Use the [RunInstances](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_RunInstances.html) API to launch new instances that require the use of IMDSv2. For more information, see [Configure instance metadata options for new instances](configuring-IMDS-new-instances.md).
**Existing instances:** Use the [ModifyInstanceMetadataOptions](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyInstanceMetadataOptions.html) API to require the use of IMDSv2 on existing instances. For more information, see [Modify instance metadata options for existing instances](configuring-IMDS-existing-instances.md).
**New instances launched by Auto Scaling groups:** To require the use of IMDSv2 on all new instances launched by Auto Scaling groups, your Auto Scaling groups can use either a launch template or a launch configuration. When you [create a launch template](https://docs.aws.amazon.com/cli/latest/reference/ec2/create-launch-template.html) or [create a launch configuration](https://docs.aws.amazon.com/cli/latest/reference/autoscaling/create-launch-configuration.html), you must configure the `MetadataOptions` parameters to require the use of IMDSv2. The Auto Scaling group launches new instances using the new launch template or launch configuration, but existing instances are not affected.
**Existing instances in an Auto Scaling group:** Use the [ModifyInstanceMetadataOptions](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyInstanceMetadataOptions.html) API to require the use of IMDSv2 on existing instances, or terminate the instances and the Auto Scaling group will launch new replacement instances with the instance metadata options settings that are defined in the new launch template or launch configuration.
**AMIs**
AMIs configured with the `ImdsSupport` parameter set to `v2.0` will launch instances that require IMDSv2 by default. Amazon Linux 2023 is configured with `ImdsSupport = v2.0`.
**New AMIs:** Use the [register-image](https://docs.aws.amazon.com/cli/latest/reference/ec2/register-image.html) CLI command to set the `ImdsSupport` parameter to `v2.0` when creating a new AMI.
**Existing AMIs:** Use the [modify-image-attribute](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-image-attribute.html) CLI command to set the `ImdsSupport` parameter to `v2.0` when modifying an existing AMI.
For more information, see [Configure the AMI](configuring-IMDS-new-instances.md#configure-IMDS-new-instances-ami-configuration).
**Account-level controls**
You can configure default values for all the instance metadata options at the account level. The default values are automatically applied when you launch an instance. For more information. see [Set IMDSv2 as the default for the account](configuring-IMDS-new-instances.md#set-imdsv2-account-defaults).
You can also enforce the requirement to use IMDSv2 at the account level. When IMDSv2 enforcement is enabled:
+ **New instances:** Instances configured to launch with IMDSv1 enabled will fail to launch
+ **Existing instances with IMDSv1 disabled:** Attempts to enable IMDSv1 on existing instances will be prevented.
+ **Existing instances with IMDSv1 enabled:** Existing instances with IMDSv1 already enabled will not be affected.
For more information, see [Enforce IMDSv2 at the account level](configuring-IMDS-new-instances.md#enforce-imdsv2-at-the-account-level).
**IAM policies and SCPs**
You can use an IAM policy or AWS Organizations service control policy (SCP) to control users as follows:
+ Can't launch an instance using the [RunInstances](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_RunInstances.html) API unless the instance is configured to use IMDSv2.
+ Can't modify an existing instance using the [ModifyInstanceMetadataOptions](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyInstanceMetadataOptions.html) API to re-enable IMDSv1.
The IAM policy or SCP must contain the following IAM condition keys:
+ `ec2:MetadataHttpEndpoint`
+ `ec2:MetadataHttpPutResponseHopLimit`
+ `ec2:MetadataHttpTokens`
If a parameter in the API or CLI call doesn't match the state specified in the policy that contains the condition key, the API or CLI call fails with an `UnauthorizedOperation` response.
Furthermore, you can choose an additional layer of protection to enforce the change from IMDSv1 to IMDSv2. At the access management layer with respect to the APIs called via EC2 Role credentials, you can use a condition key in either IAM policies or AWS Organizations service control policies (SCPs). Specifically, by using the condition key `ec2:RoleDelivery` with a value of `2.0` in your IAM policies, API calls made with EC2 Role credentials obtained from IMDSv1 will receive an `UnauthorizedOperation` response. The same thing can be achieved more broadly with that condition required by an SCP. This ensures that credentials delivered via IMDSv1 cannot actually be used to call APIs because any API calls not matching the specified condition will receive an `UnauthorizedOperation` error.
For example IAM policies, see [Work with instance metadata](ExamplePolicies_EC2.md#iam-example-instance-metadata). For more information on SCPs, see [Service control policies](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_scps.html) in the *AWS Organizations User Guide*.
**Declarative Policies**
Use Declarative Policies (a feature of AWS Organizations) to centrally set IMDS account defaults, including IMDSv2 enforcement, across your organization. For an example policy, see the **Instance Metadata** tab in the [Supported declarative policies](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_declarative_syntax.html#declarative-policy-examples) section in the *AWS Organizations User Guide*.
## Recommended path to requiring IMDSv2
**Topics**
+ [
### Step 1: Identify instances with IMDSv2=optional and audit IMDSv1 usage
](#path-step-1)
+ [
### Step 2: Update software to IMDSv2
](#path-step-2)
+ [
### Step 3: Require IMDSv2 on instances
](#path-step-3)
+ [
### Step 4: Set IMDSv2=required as the default
](#path-step-4)
+ [
### Step 5: Enforce instances to require IMDSv2
](#path-step-5)
### Step 1: Identify instances with IMDSv2=optional and audit IMDSv1 usage
To assess your IMDSv2 migration scope, identify instances that are configured to allow either IMDSv1 or IMDSv2, and audit IMDSv1 calls.
1. **Identify instances that are configured to allow either IMDSv1 or IMDSv2:**
------
#### [ Amazon EC2 console ]
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation pane, choose **Instances**.
1. To see only the instances that are configured to allow IMDSv1 or IMDSv2, add the filter **IMDSv2 = optional**.
1. Alternatively, to see whether IMDSv2 is **optional** or **required** for all instances, open the **Preferences** window (gear icon), toggle on **IMDSv2**, and choose **Confirm**. This adds the **IMDSv2** column to the **Instances** table.
------
#### [ AWS CLI ]
Use the [describe-instances](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ec2/modify-instance-metadata-options.html) command and filter by `metadata-options.http-tokens = optional`, as follows:
```
aws ec2 describe-instances --filters "Name=metadata-options.http-tokens,Values=optional" --query "Reservations[*].Instances[*].[InstanceId]" --output text
```
------
1. **Audit IMDSv1 calls on each instance:**
Use the CloudWatch metric `MetadataNoToken`. This metric shows the number of IMDSv1 calls to the IMDS on your instances. For more information, see [Instance metrics](https://docs.aws.amazon.com/en_us/AWSEC2/latest/UserGuide/viewing_metrics_with_cloudwatch.html#ec2-cloudwatch-metrics).
1. **Identify software on your instances making IMDSv1 calls:**
Use the open source [IMDS Packet Analyzer](https://github.com/aws/aws-imds-packet-analyzer) to identify and log IMDSv1 calls during your instance’s boot phase and runtime operations. Use this information to identify the software to update to get your instances ready to use IMDSv2 only. You can run IMDS Packet Analyzer from a command line or install it as a service.
### Step 2: Update software to IMDSv2
Update all SDKs, CLIs, and software that use Role credentials on your instances to IMDSv2-compatible versions. For more information about updating the CLI, see [Installing or updating to the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) in the *AWS Command Line Interface User Guide*.
### Step 3: Require IMDSv2 on instances
After confirming zero IMDSv1 calls through the `MetadataNoToken` metric, configure your existing instances to require IMDSv2. Also, configure all new instances to require IMDSv2. In other words, disable IMDSv1 on all existing and new instances.
1. **Configure existing instances to require IMDSv2:**
------
#### [ Amazon EC2 console ]
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation pane, choose **Instances**.
1. Select your instance.
1. Choose **Actions**, **Instance settings**, **Modify instance metadata options**.
1. For **IMDSv2**, choose **Required**.
1. Choose **Save**.
------
#### [ AWS CLI ]
Use the [modify-instance-metadata-options](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ec2/modify-instance-metadata-options.html) CLI command to specify that only IMDSv2 is to be used.
------
**Note**
You can modify this setting on running instances. The change takes effect immediately without needing an instance restart.
For more information, see [Require the use of IMDSv2](configuring-IMDS-existing-instances.md#modify-require-IMDSv2).
1. **Monitor for issues after disabling IMDSv1:**
1. Track the number of times an IMDSv1 call was attempted and rejected with the `MetadataNoTokenRejected` CloudWatch metric.
1. If the `MetadataNoTokenRejected` metric records IMDSv1 calls on an instance that is experiencing software issues, this indicates that the software requires updating to use IMDSv2.
1. **Configure new instances to require IMDSv2:**
------
#### [ Amazon EC2 console ]
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. Follow the steps to [launch an instance](ec2-launch-instance-wizard.md).
1. Expand **Advanced details**, and for **Metadata version**, choose **V2 only (token required)**.
1. In the **Summary panel**, review your instance configuration, and then choose **Launch instance**.
For more information, see [Configure the instance at launch](configuring-IMDS-new-instances.md#configure-IMDS-new-instances-instance-settings).
------
#### [ AWS CLI ]
AWS CLI: Use the [run-instances](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ec2/run-instances.html) command and specify that IMDSv2 is required.
------
### Step 4: Set IMDSv2=required as the default
You can set IMDSv2=required as the default configuration at either the account or organization level. This ensures that all newly launched instances are automatically configured to require IMDSv2.
1. **Set account-level default:**
------
#### [ Amazon EC2 console ]
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation pane, choose **Dashboard**.
1. On the **Account attributes** card, under **Settings**, choose **Data protection and security**.
1. Under **IMDS defaults**, choose **Manage**.
1. For **Instance metadata service **, choose **Enabled**.
1. For **Metadata version**, choose to **V2 only (token required)**.
1. Choose **Update**.
------
#### [ AWS CLI ]
Use the [modify-instance-metadata-defaults](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ec2/modify-instance-metadata-defaults.html) CLI command and specify `--http-tokens required` and `--http-put-response-hop-limit 2`.
------
For more information, see [Set IMDSv2 as the default for the account](configuring-IMDS-new-instances.md#set-imdsv2-account-defaults).
1. **Alternatively, set organization-level default using a Declarative Policy:**
Use a Declarative Policy to set the organization default for IMDSv2 to required. For an example policy, see the **Instance Metadata** tab in the [Supported declarative policies](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_declarative_syntax.html#declarative-policy-examples) section in the *AWS Organizations User Guide*.
### Step 5: Enforce instances to require IMDSv2
Once you’ve confirmed that there is no dependency on IMDSv1 on any of your instances, we recommend that you enforce IMDSv2 on all new instances.
Use one of the following options to enforce IMDSv2:
1. **Enforce IMDSv2 with an account property**
You can enforce the use of IMDSv2 at the account level for each AWS Region. When enforced, instances can only launch if they're configured to require IMDSv2. This enforcement applies regardless of how the instance or AMI is configured. For more information, see [Enforce IMDSv2 at the account level](configuring-IMDS-new-instances.md#enforce-imdsv2-at-the-account-level). To apply this setting at an organization level, set a Declarative Policy. For an example policy, see the **Instance Metadata** tab in the [Supported declarative policies](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_declarative_syntax.html#declarative-policy-examples) section in the *AWS Organizations User Guide*.
To prevent a reversal of enforcement, you should use an IAM policy to prevent access to the [ModifyInstanceMetadataDefaults](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyInstanceMetadataDefaults.html) API. For more information, see [Use an IAM policy](configuring-IMDS-new-instances.md#configure-IMDS-new-instances-iam-policy).
**Note**
This setting does not change the IMDS version of existing instances, but blocks enabling IMDSv1 on existing instances that currently have IMDSv1 disabled.
**Warning**
If IMDSv2 enforcement is enabled and `httpTokens` is not set to `required` in either the instance configuration at launch, the account settings, or the AMI configuration, the instance launch will fail. For troubleshooting information, see [Launching an IMDSv1-enabled instance fails](troubleshooting-launch.md#launching-an-imdsv1-enabled-instance-fails).
1. **Alternatively, enforce IMDSv2 by using the following IAM or SCP condition keys:**
+ `ec2:MetadataHttpTokens`
+ `ec2:MetadataHttpPutResponseHopLimit`
+ `ec2:MetadataHttpEndpoint`
These condition keys control the use of the [RunInstances](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_RunInstances.html) and the [ModifyInstanceMetadataOptions](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyInstanceMetadataOptions.html) APIs and corresponding CLIs. If a policy is created, and a parameter in the API call does not match the state specified in the policy using the condition key, the API or CLI call fails with an `UnauthorizedOperation` response.
For example IAM policies, see [Work with instance metadata](ExamplePolicies_EC2.md#iam-example-instance-metadata).
# Limit access to the Instance Metadata Service
Limit access to IMDS
You can consider using local firewall rules to disable access from some or all processes to the Instance Metadata Service (IMDS).
For [Nitro-based instances](instance-types.md#instance-hypervisor-type), the IMDS can be reached from your own network when a network appliance within your VPC, such as a virtual router, forwards packets to the IMDS address, and the default [source/destination check](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_NAT_Instance.html#EIP_Disable_SrcDestCheck) on the instance is disabled. To prevent a source from outside your VPC reaching the IMDS, we recommend that you modify the configuration of the network appliance to drop packets with the destination IPv4 address of the IMDS `169.254.169.254` and, if you enabled the IPv6 endpoint, the IPv6 address of the IMDS `[fd00:ec2::254]`.
## Limit IMDS access for Linux instances
**Using iptables to limit access**
The following example uses Linux iptables and its `owner` module to prevent the Apache webserver (based on its default installation user ID of `apache`) from accessing 169.254.169.254. It uses a *deny rule* to reject all instance metadata requests (whether IMDSv1 or IMDSv2) from any process running as that user.
```
$ sudo iptables --append OUTPUT --proto tcp --destination 169.254.169.254 --match owner --uid-owner apache --jump REJECT
```
Or, you can consider only allowing access to particular users or groups, by using *allow rules*. Allow rules might be easier to manage from a security perspective, because they require you to make a decision about what software needs access to instance metadata. If you use *allow rules*, it's less likely you will accidentally allow software to access the metadata service (that you did not intend to have access) if you later change the software or configuration on an instance. You can also combine group usage with allow rules, so that you can add and remove users from a permitted group without needing to change the firewall rule.
The following example prevents access to the IMDS by all processes, except for processes running in the user account `trustworthy-user`.
```
$ sudo iptables --append OUTPUT --proto tcp --destination 169.254.169.254 --match owner ! --uid-owner trustworthy-user --jump REJECT
```
**Note**
To use local firewall rules, you need to adapt the preceding example commands to suit your needs.
By default, iptables rules are not persistent across system reboots. They can be made to be persistent by using OS features, not described here.
The iptables `owner` module only matches group membership if the group is the primary group of a given local user. Other groups are not matched.
**Using PF or IPFW to limit access**
If you are using FreeBSD or OpenBSD, you can also consider using PF or IPFW. The following examples limit access to the IMDS to just the root user.
**PF**
```
$ block out inet proto tcp from any to 169.254.169.254
```
```
$ pass out inet proto tcp from any to 169.254.169.254 user root
```
**IPFW**
```
$ allow tcp from any to 169.254.169.254 uid root
```
```
$ deny tcp from any to 169.254.169.254
```
**Note**
The order of the PF and IPFW commands matter. PF defaults to last matching rule and IPFW defaults to first matching rule.
## Limit IMDS access for Windows instances
**Using Windows firewall to limit access**
The following PowerShell example uses the built-in Windows firewall to prevent the Internet Information Server webserver (based on its default installation user ID of `NT AUTHORITY\IUSR`) from accessing 169.254.169.254. It uses a *deny rule* to reject all instance metadata requests (whether IMDSv1 or IMDSv2) from any process running as that user.
```
PS C:\> $blockPrincipal = New-Object -TypeName System.Security.Principal.NTAccount ("NT AUTHORITY\IUSR")
PS C:\> $BlockPrincipalSID = $blockPrincipal.Translate([System.Security.Principal.SecurityIdentifier]).Value
PS C:\> $BlockPrincipalSDDL = "D:(A;;CC;;;$BlockPrincipalSID)"
PS C:\> New-NetFirewallRule -DisplayName "Block metadata service from IIS" -Action block -Direction out `
-Protocol TCP -RemoteAddress 169.254.169.254 -LocalUser $BlockPrincipalSDDL
```
Or, you can consider only allowing access to particular users or groups, by using *allow rules*. Allow rules might be easier to manage from a security perspective, because they require you to make a decision about what software needs access to instance metadata. If you use *allow rules*, it's less likely you will accidentally allow software to access the metadata service (that you did not intend to have access) if you later change the software or configuration on an instance. You can also combine group usage with allow rules, so that you can add and remove users from a permitted group without needing to change the firewall rule.
The following example prevents access to instance metadata by all processes running as an OS group specified in the variable `blockPrincipal` (in this example, the Windows group `Everyone`), except for processes specified in `exceptionPrincipal` (in this example, a group called `trustworthy-users`). You must specify both deny and allow principals because Windows Firewall, unlike the `! --uid-owner trustworthy-user` rule in Linux iptables, does not provide a shortcut mechanism to allow only a particular principal (user or group) by denying all the others.
```
PS C:\> $blockPrincipal = New-Object -TypeName System.Security.Principal.NTAccount ("Everyone")
PS C:\> $BlockPrincipalSID = $blockPrincipal.Translate([System.Security.Principal.SecurityIdentifier]).Value
PS C:\> $exceptionPrincipal = New-Object -TypeName System.Security.Principal.NTAccount ("trustworthy-users")
PS C:\> $ExceptionPrincipalSID = $exceptionPrincipal.Translate([System.Security.Principal.SecurityIdentifier]).Value
PS C:\> $PrincipalSDDL = "O:LSD:(D;;CC;;;$ExceptionPrincipalSID)(A;;CC;;;$BlockPrincipalSID)"
PS C:\> New-NetFirewallRule -DisplayName "Block metadata service for $($blockPrincipal.Value), exception: $($exceptionPrincipal.Value)" -Action block -Direction out `
-Protocol TCP -RemoteAddress 169.254.169.254 -LocalUser $PrincipalSDDL
```
**Note**
To use local firewall rules, you need to adapt the preceding example commands to suit your needs.
**Using netsh rules to limit access**
You can consider blocking all software using `netsh` rules, but those are much less flexible.
```
C:\> netsh advfirewall firewall add rule name="Block metadata service altogether" dir=out protocol=TCP remoteip=169.254.169.254 action=block
```
**Note**
To use local firewall rules, you need to adapt the preceding example commands to suit your needs.
`netsh` rules must be set from an elevated command prompt, and can’t be set to deny or allow particular principals.
# Configure the Instance Metadata Service options
Configure IMDS options
The Instance Metadata Service (IMDS) runs locally on every EC2 instance. The *instance metadata options* refer to a set of configurations that control the accessibility and behavior of the IMDS on an EC2 instance.
You can configure the following instance metadata options on each instance:
**Instance metadata service (IMDS)**: `enabled` \$1 `disabled`
You can enable or disable the IMDS on an instance. When disabled, you or any code won't be able to access the instance metadata on the instance.
The IMDS has two endpoints on an instance: IPv4 (`169.254.169.254`) and IPv6 (`[fd00:ec2::254]`). When you enable the IMDS, the IPv4 endpoint is automatically enabled. If you want to enable the IPv6 endpoint, you need to do so explicitly.
**IMDS IPv6 endpoint**: `enabled` \$1 `disabled`
You can explicitly enable the IPv6 IMDS endpoint on an instance. When the IPv6 endpoint is enabled, the IPv4 endpoint remains enabled. The IPv6 endpoint is only supported on [Nitro-based instances](instance-types.md#instance-hypervisor-type) in [IPv6-supported subnets](https://docs.aws.amazon.com/vpc/latest/userguide/configure-subnets.html#subnet-ip-address-range) (dual stack or IPv6 only).
**Metadata version**: `IMDSv1 or IMDSv2 (token optional)` \$1 `IMDSv2 only (token required)`
When requesting instance metadata, IMDSv2 calls require a token. IMDSv1 calls do not require a token. You can configure an instance to allow either IMDSv1 or IMDSv2 calls (where a token is optional), or to only allow IMDSv2 calls (where a token is required).
**Metadata response hop limit**: `1`–`64`
The hop limit is the number of network hops that the PUT response is allowed to make. You can set the hop limit to a minimum of `1` and a maximum of `64`. In a container environment, a hop limit of `1` can cause issues. For information about how to mitigate these issues, see the information about container environments under [Instance metadata access considerations](instancedata-data-retrieval.md#imds-considerations).
**Access to tags in instance metadata**: `enabled` \$1 `disabled`
You can enable or disable access to the instance's tags from an instance's metadata. For more information, see [View tags for your EC2 instances using instance metadata](work-with-tags-in-IMDS.md).
To view an instance's current configuration, see [Query instance metadata options for existing instances](instancedata-data-retrieval.md#query-IMDS-existing-instances).
## Where to configure instance metadata options
Instance metadata options can be configured at different levels, as follows:
+ **Account** – You can set default values for the instance metadata options at the account level for each AWS Region. When an instance is launched, the instance metadata options are automatically set to the account-level values. You can change these values at launch. Account-level default values do not affect existing instances.
+ **AMI** – You can set the `imds-support` parameter to `v2.0` when you register or modify an AMI. When an instance is launched with this AMI, the instance metadata version is automatically set to IMDSv2 and the hop limit is set to 2.
+ **Instance** – You can change all the instance metadata options on an instance at launch, overriding the default settings. You can also change the instance metadata options after launch on a running or stopped instance. Note that changes may be restricted by an IAM or SCP policy.
For more information, see [Configure instance metadata options for new instances](configuring-IMDS-new-instances.md) and [Modify instance metadata options for existing instances](configuring-IMDS-existing-instances.md).
## Order of precedence for instance metadata options
The value for each instance metadata option is determined at instance launch, following a hierarchical order of precedence. The hierarchy, with the highest precedence at the top, is as follows:
+ **Precedence 1: Instance configuration at launch** – Values can be specified either in the launch template or in the instance configuration. Any values specified here override values specified at the account level or in the AMI.
+ **Precedence 2: Account settings** – If a value is not specified at instance launch, then it is determined by the account-level settings (which are set for each AWS Region). Account-level settings either include a value for each metadata option, or indicate no preference at all.
+ **Precedence 3: AMI configuration** – If a value is not specified at instance launch or at the account level, then it is determined by the AMI configuration. This applies only to `HttpTokens` and `HttpPutResponseHopLimit`.
Each metadata option is evaluated separately. The instance can be configured with a mix of direct instance configuration, account-level defaults, and the configuration from the AMI.
You can change the value of any metadata option after launch on a running or stopped instance, unless changes are restricted by an IAM or SCP policy.
**Note**
The account-level IMDSv2 enforcement setting is evaluated after the order of precedence has determined the instance's IMDS settings. When IMDSv2 enforcement is enabled, instances enabled with IMDSv1 will fail. For more information about enforcement, see [Enforce IMDSv2 at the account level](configuring-IMDS-new-instances.md#enforce-imdsv2-at-the-account-level).
**Warning**
If IMDSv2 enforcement is enabled and `httpTokens` has not been set to `required` in either the instance configuration at launch, the account settings, or the AMI configuration, your launch will fail.
**Example 1 – Determine values for metadata options**
In this example, an EC2 instance is launched into a Region where the `HttpPutResponseHopLimit` is set to `1` at the account level. The specified AMI has `ImdsSupport` set to `v2.0`. No metadata options are specified directly on the instance at launch. The instance is launched with the following metadata options:
```
"MetadataOptions": {
...
"HttpTokens": "required",
"HttpPutResponseHopLimit": 1,
...
```
These values were determined as follows:
+ **No metadata options specified at launch:** During the launch of the instance, specific values for the metadata options were not provided either in the instance launch parameters or in the launch template.
+ **Account settings take next precedence:** In the absence of specific values specified at launch, the settings at the account level within the Region take precedence. This means that the default values configured at the account level are applied. In this case, the `HttpPutResponseHopLimit` was set to `1`.
+ **AMI settings take last precedence:** In the absence of a specific value specified at launch or at the account level for `HttpTokens` (the instance metadata version), the AMI setting is applied. In this case, the AMI setting `ImdsSupport: v2.0` determined that `HttpTokens` was set to `required`. Note that while the AMI setting `ImdsSupport: v2.0` is designed to set `HttpPutResponseHopLimit: 2`, it was overridden by the account-level setting `HttpPutResponseHopLimit: 1`, which has higher precedence.
**Example 2 – Determine values for metadata options**
In this example, the EC2 instance is launched with the same settings as in the previous Example 1, but with `HttpTokens` set to `optional` directly on the instance at launch. The instance is launched with the following metadata options:
```
"MetadataOptions": {
...
"HttpTokens": "optional",
"HttpPutResponseHopLimit": 1,
...
```
The value for `HttpPutResponseHopLimit` is determined in the same way as in Example 1. However, the value for `HttpTokens` is determined as follows: Metadata options configured on the instance at launch take first precedence. Even though the AMI was configured with `ImdsSupport: v2.0` (in other words, `HttpTokens` is set to `required`), the value specified on the instance at launch (`HttpTokens` set to `optional`) took precedence.
**Example 3 – Determine values for metadata options with HttpTokensEnforced enabled**
In this example, the account in the Region has `HttpTokens = required` and `HttpTokensEnforced = enabled`.
Consider the following EC2 instance launch attempts:
+ Launch attempt with `HttpTokens` set to `optional` – The launch fails because the account-level enforcement is enabled (`HttpTokensEnforced = enabled`) and the launch parameter takes precedence over the account default.
+ Launch attempt with `HttpTokens` set to `required` – The launch succeeds because it complies with the account-level enforcement.
+ Launch attempt with no `HttpTokens` value specified – The launch succeeds because the value defaults to `required` based on the account settings.
### Set the instance metadata version
When an instance is launched, the value for the instance *metadata version* is either **IMDSv1 or IMDSv2 (token optional)** (`httpTokens=optional`) or **IMDSv2 only (token required) (`httpTokens=required`) **.
At instance launch, you can either manually specify the value for the metadata version, or use the default value. If you manually specify the value, it overrides any defaults. If you opt not to manually specify the value, it will be determined by a combination of default settings.
The following flowchart shows how the metadata version for an instance at launch is determined by the settings at the different levels of the configuration and where enforcement is evaluated. The table that follows provides the specific settings at each level.
![\[A flowchart that shows the evaluation points for the instance metadata version and IMDSv2 enforcement.\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/imds-defaults-launch-flow.png)
The table shows how the metadata version for an instance at launch (indicated by **Resulting instance configuration** in column 4) is determined by the settings at the different levels of configuration. The order of precedence is from left to right, where the first column takes the highest precedence, as follows:
+ Column 1: **Launch parameter** – Represents the setting on the instance that you manually specify at launch.
+ Column 2: **Account level default** – Represents the setting for the account.
+ Column 3: **AMI default** – Represents the setting on the AMI.
| Launch parameter | Account level default | AMI default | Resulting instance configuration |
| --- | --- | --- | --- |
| V2 only (token required) | No preference | V2 only | V2 only |
| V2 only (token required) | V2 only | V2 only | V2 only |
| V2 only (token required) | V1 or V2 | V2 only | V2 only |
| V1 or V2 (token optional) | No preference | V2 only | V1 or V2 |
| V1 or V2 (token optional) | V2 only | V2 only | V1 or V2 |
| V1 or V2 (token optional) | V1 or V2 | V2 only | V1 or V2 |
| Not set | No preference | V2 only | V2 only |
| Not set | V2 only | V2 only | V2 only |
| Not set | V1 or V2 | V2 only | V1 or V2 |
| V2 only (token required) | No preference | null | V2 only |
| V2 only (token required) | V2 only | null | V2 only |
| V2 only (token required) | V1 or V2 | null | V2 only |
| V1 or V2 (token optional) | No preference | null | V1 or V2 |
| V1 or V2 (token optional) | V2 only | null | V1 or V2 |
| V1 or V2 (token optional) | V1 or V2 | null | V1 or V2 |
| Not set | No preference | null | V1 or V2 |
| Not set | V2 only | null | V2 only |
| Not set | V1 or V2 | null | V1 or V2 |
## Use IAM condition keys to restrict instance metadata options
You can use IAM condition keys in an IAM policy or SCP as follows:
+ Allow an instance to launch only if it's configured to require the use of IMDSv2
+ Restrict the number of allowed hops
+ Turn off access to instance metadata
**Topics**
+ [
## Where to configure instance metadata options
](#where-to-configure-instance-metadata-options)
+ [
## Order of precedence for instance metadata options
](#instance-metadata-options-order-of-precedence)
+ [
## Use IAM condition keys to restrict instance metadata options
](#iam-condition-keys-and-imds)
+ [
# Configure instance metadata options for new instances
](configuring-IMDS-new-instances.md)
+ [
# Modify instance metadata options for existing instances
](configuring-IMDS-existing-instances.md)
**Note**
You should proceed cautiously and conduct careful testing before making any changes. Take note of the following:
If you enforce the use of IMDSv2, applications or agents that use IMDSv1 for instance metadata access will break.
If you turn off all access to instance metadata, applications or agents that rely on instance metadata access to function will break.
For IMDSv2, you must use `/latest/api/token` when retrieving the token.
(Windows only) If your PowerShell version is earlier than 4.0, you must [update to Windows Management Framework 4.0](https://devblogs.microsoft.com/powershell/windows-management-framework-wmf-4-0-update-now-available-for-windows-server-2012-windows-server-2008-r2-sp1-and-windows-7-sp1/) to require the use of IMDSv2.
# Configure instance metadata options for new instances
For new instances
You can configure the following instance metadata options for new instances.
**Topics**
+ [
## Require the use of IMDSv2
](#configure-IMDS-new-instances)
+ [
## Enable the IMDS IPv4 and IPv6 endpoints
](#configure-IMDS-new-instances-ipv4-ipv6-endpoints)
+ [
## Turn off access to instance metadata
](#configure-IMDS-new-instances--turn-off-instance-metadata)
+ [
## Allow access to tags in instance metadata
](#configure-IMDS-new-instances-tags-in-instance-metadata)
**Note**
The settings for these options are configured at the account level, either directly in the account or by using a declarative policy. They must be configured in each AWS Region where you want to configure instance metadata options. Using a declarative policy allows you to apply the settings across multiple Regions simultaneously, as well as across multiple accounts simultaneously. When a declarative policy is in use, you can't modify the settings directly within an account. This topic describes how to configure the settings directly within an account. For information about using declarative policies, see [Declarative policies](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_declarative.html) in the *AWS Organizations User Guide.*
## Require the use of IMDSv2
You can use the following methods to require the use of IMDSv2 on your new instances.
**Topics**
+ [
### Set IMDSv2 as the default for the account
](#set-imdsv2-account-defaults)
+ [
### Enforce IMDSv2 at the account level
](#enforce-imdsv2-at-the-account-level)
+ [
### Configure the instance at launch
](#configure-IMDS-new-instances-instance-settings)
+ [
### Configure the AMI
](#configure-IMDS-new-instances-ami-configuration)
+ [
### Use an IAM policy
](#configure-IMDS-new-instances-iam-policy)
### Set IMDSv2 as the default for the account
You can set the default version for the instance metadata service (IMDS) at the account level for each AWS Region. This means that when you launch a *new* instance, the instance metadata version is automatically set to the account-level default. However, you can manually override the value at launch or after launch. For more information about how the account-level settings and manual overrides affect an instance, see [Order of precedence for instance metadata options](configuring-instance-metadata-options.md#instance-metadata-options-order-of-precedence).
**Note**
Setting the account-level default does not reset *existing* instances. For example, if you set the account-level default to IMDSv2, any existing instances that are set to IMDSv1 are not affected. If you want to change the value on existing instances, you must manually change the value on the instances themselves.
You can set the account default for the instance metadata version to IMDSv2 so that all *new* instances in the account launch with IMDSv2 required, and IMDSv1 will be disabled. With this account default, when you launch an instance, the following are the default values for the instance:
+ Console: **Metadata version** is set to **V2 only (token required)** and **Metadata response hop limit** is set to **2**.
+ AWS CLI: `HttpTokens` is set to `required` and `HttpPutResponseHopLimit` is set to `2`.
**Note**
Before setting the account default to IMDSv2, ensure that your instances do not depend on IMDSv1. For more information, see [Recommended path to requiring IMDSv2](instance-metadata-transition-to-version-2.md#recommended-path-for-requiring-imdsv2).
------
#### [ Console ]
**To set IMDSv2 as the default for the account for the specified Region**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. To change the AWS Region, use the Region selector in the upper-right corner of the page.
1. In the navigation pane, choose **Dashboard**.
1. On the **Account attributes** card, under **Settings**, choose **Data protection and security**.
1. Next to **IMDS defaults**, choose **Manage**.
1. On the **Manage IMDS defaults** page, do the following:
1. For **Instance metadata service**, choose **Enabled**.
1. For **Metadata version**, choose **V2 only (token required)**.
1. For **Metadata response hop limit**, specify **2** if your instances will host containers. Otherwise, select **No preference**. When no preference is specified, at launch, the value defaults to **2** if the AMI has the setting `ImdsSupport: v2.0`; otherwise it defaults to **1**.
1. Choose **Update**.
------
#### [ AWS CLI ]
**To set IMDSv2 as the default for the account for the specified Region**
Use the [modify-instance-metadata-defaults](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-metadata-defaults.html) command and specify the Region in which to modify the IMDS account level settings. Include `--http-tokens` set to `required` and `--http-put-response-hop-limit` set to `2` if your instances will host containers. Otherwise, specify `-1` to indicate no preference. When `-1` (no preference) is specified, at launch, the value defaults to `2` if the AMI has the setting `ImdsSupport: v2.0`; otherwise it defaults to `1`.
```
aws ec2 modify-instance-metadata-defaults \
--region us-east-1 \
--http-tokens required \
--http-put-response-hop-limit 2
```
The following is example output.
```
{
"Return": true
}
```
**To view the default account settings for the instance metadata options for the specified Region**
Use the [get-instance-metadata-defaults](https://docs.aws.amazon.com/cli/latest/reference/ec2/get-instance-metadata-defaults.html) command and specify the Region.
```
aws ec2 get-instance-metadata-defaults --region us-east-1
```
The following is example output.
```
{
"AccountLevel": {
"HttpTokens": "required",
"HttpPutResponseHopLimit": 2
},
"ManagedBy": "account"
}
```
The `ManagedBy` field indicates the entity that configured the settings. In this example, `account` indicates that the settings were configured directly in the account. A value of `declarative-policy` would mean the settings were configured by a declarative policy. For more information, see [Declarative policies](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_declarative.html) in the *AWS Organizations User Guide*.
**To set IMDSv2 as the default for the account for all Regions**
Use the [modify-instance-metadata-defaults](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-metadata-defaults.html) command to modify the IMDS account level settings for all Regions. Include `--http-tokens` set to `required` and `--http-put-response-hop-limit` set to `2` if your instances will host containers. Otherwise, specify `-1` to indicate no preference. When `-1` (no preference) is specified, at launch, the value defaults to `2` if the AMI has the setting `ImdsSupport: v2.0`; otherwise it defaults to `1`.
```
echo -e "Region \t Modified" ; \
echo -e "-------------- \t ---------" ; \
for region in $(
aws ec2 describe-regions \
--region us-east-1 \
--query "Regions[*].[RegionName]" \
--output text
);
do (output=$(
aws ec2 modify-instance-metadata-defaults \
--region $region \
--http-tokens required \
--http-put-response-hop-limit 2 \
--output text)
echo -e "$region \t $output"
);
done
```
The following is example output.
```
Region Modified
-------------- ---------
ap-south-1 True
eu-north-1 True
eu-west-3 True
...
```
**To view the default account settings for the instance metadata options for all Regions**
Use the [get-instance-metadata-defaults](https://docs.aws.amazon.com/cli/latest/reference/ec2/get-instance-metadata-defaults.html) command.
```
echo -e "Region \t Level Hops HttpTokens" ; \
echo -e "-------------- \t ------------ ---- ----------" ; \
for region in $(
aws ec2 describe-regions \
--region us-east-1 \
--query "Regions[*].[RegionName]" \
--output text
);
do (output=$(
aws ec2 get-instance-metadata-defaults \
--region $region \
--output text)
echo -e "$region \t $output"
);
done
```
The following is example output.
```
Region Level Hops HttpTokens
-------------- ------------ ---- ----------
ap-south-1 ACCOUNTLEVEL 2 required
eu-north-1 ACCOUNTLEVEL 2 required
eu-west-3 ACCOUNTLEVEL 2 required
...
```
------
#### [ PowerShell ]
**To set IMDSv2 as the default for the account for the specified Region**
Use the [Edit-EC2InstanceMetadataDefault](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2InstanceMetadataDefault.html) cmdlet and specify the Region in which to modify the IMDS account level settings. Include `-HttpToken` set to `required` and `-HttpPutResponseHopLimit` set to `2` if your instances will host containers. Otherwise, specify `-1` to indicate no preference. When `-1` (no preference) is specified, at launch, the value defaults to `2` if the AMI has the setting `ImdsSupport: v2.0`; otherwise it defaults to `1`.
```
Edit-EC2InstanceMetadataDefault `
-Region us-east-1 `
-HttpToken required `
-HttpPutResponseHopLimit 2
```
The following is example output.
```
True
```
**To view the default account settings for the instance metadata options for the specified Region**
Use the [Get-EC2InstanceMetadataDefault](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-EC2InstanceMetadataDefault.html) cmdlet and specify the Region.
```
Get-EC2InstanceMetadataDefault -Region us-east-1 | Format-List
```
The following is example output.
```
HttpEndpoint :
HttpPutResponseHopLimit : 2
HttpTokens : required
InstanceMetadataTags :
```
**To set IMDSv2 as the default for the account for all Regions**
Use the [Edit-EC2InstanceMetadataDefault](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2InstanceMetadataDefault.html) cmdlet to modify the IMDS account level settings for all Regions. Include `-HttpToken` set to `required` and `-HttpPutResponseHopLimit` set to `2` if your instances will host containers. Otherwise, specify `-1` to indicate no preference. When `-1` (no preference) is specified, at launch, the value defaults to `2` if the AMI has the setting `ImdsSupport: v2.0`; otherwise it defaults to `1`.
```
(Get-EC2Region).RegionName | `
ForEach-Object {
[PSCustomObject]@{
Region = $_
Modified = (Edit-EC2InstanceMetadataDefault `
-Region $_ `
-HttpToken required `
-HttpPutResponseHopLimit 2)
}
} | `
Format-Table Region, Modified -AutoSize
```
Expected output
```
Region Modified
------ --------
ap-south-1 True
eu-north-1 True
eu-west-3 True
...
```
**To view the default account settings for the instance metadata options for all Regions**
Use the [Get-EC2InstanceMetadataDefault](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-EC2InstanceMetadataDefault.html) cmdlet.
```
(Get-EC2Region).RegionName | `
ForEach-Object {
[PSCustomObject]@{
Region = $_
HttpPutResponseHopLimit = (Get-EC2InstanceMetadataDefault -Region $_).HttpPutResponseHopLimit
HttpTokens = (Get-EC2InstanceMetadataDefault -Region $_).HttpTokens
}
} | `
Format-Table -AutoSize
```
Example output
```
Region HttpPutResponseHopLimit HttpTokens
------ ----------------------- ----------
ap-south-1 2 required
eu-north-1 2 required
eu-west-3 2 required
...
```
------
### Enforce IMDSv2 at the account level
You can enforce the use of IMDSv2 at the account level for each AWS Region. When enforced, instances can only launch if they're configured to require IMDSv2. This enforcement applies regardless of how the instance or AMI is configured.
**Note**
Before enabling IMDSv2 enforcement at the account level, ensure that your applications and AMIs support IMDSv2. For more information, see [Recommended path to requiring IMDSv2](instance-metadata-transition-to-version-2.md#recommended-path-for-requiring-imdsv2). If IMDSv2 enforcement is enabled and `httpTokens` is not set to `required` in either the instance configuration at launch, the account settings, or the AMI configuration, the instance launch will fail. For troubleshooting information, see [Launching an IMDSv1-enabled instance fails](troubleshooting-launch.md#launching-an-imdsv1-enabled-instance-fails).
**Note**
This setting does not change the IMDS version of existing instances, but blocks enabling IMDSv1 on existing instances that currently have IMDSv1 disabled.
------
#### [ Console ]
**To enforce IMDSv2 for the account in the specified Region**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. To change the AWS Region, use the Region selector in the top right corner of the page.
1. In the navigation pane, choose **Dashboard**.
1. On the **Account attributes** card, under **Settings**, choose **Data protection and security**.
1. Next to **IMDS defaults**, choose **Manage**.
1. On the **Manage IMDS defaults** page, do the following:
1. For **Metadata version**, choose **V2 only (token required)**.
1. For **Enforce IMDSv2**, choose **Enabled**.
1. Choose **Update**.
------
#### [ AWS CLI ]
**To enforce IMDSv2 for the account in the specified Region**
Use the [modify-instance-metadata-defaults](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-metadata-defaults.html) command and specify the Region in which to enforce IMDSv2.
```
aws ec2 modify-instance-metadata-defaults \
--region us-east-1 \
--http-tokens required \
--http-tokens-enforced enabled
```
The following is example output.
```
{
"Return": true
}
```
**To view the IMDSv2 enforcement setting for the account in a specific Region**
Use the [get-instance-metadata-defaults](https://docs.aws.amazon.com/cli/latest/reference/ec2/get-instance-metadata-defaults.html) command and specify the Region.
```
aws ec2 get-instance-metadata-defaults --region us-east-1
```
The following is example output.
```
{
"AccountLevel": {
"HttpTokens": "required",
"HttpTokensEnforced": "enabled"
},
"ManagedBy": "account"
}
```
The `ManagedBy` field indicates the entity that configured the settings. In this example, `account` indicates that the settings were configured directly in the account. A value of `declarative-policy` would mean the settings were configured by a declarative policy. For more information, see [Declarative policies](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_declarative.html) in the *AWS Organizations User Guide*.
**To enforce IMDSv2 for the account for all Regions**
Use the [modify-instance-metadata-defaults](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-metadata-defaults.html) command to enforce IMDSv2 in all Regions.
```
echo -e "Region \t Modified" ; \
echo -e "-------------- \t ---------" ; \
for region in $(
aws ec2 describe-regions \
--region us-east-1 \
--query "Regions[*].[RegionName]" \
--output text
);
do (output=$(
aws ec2 modify-instance-metadata-defaults \
--region $region \
--http-tokens-enforced enabled \
--output text)
echo -e "$region \t $output"
);
done
```
The following is example output.
```
Region Modified
-------------- ---------
ap-south-1 True
eu-north-1 True
eu-west-3 True
...
```
**To view the IMDSv2 enforcement settings for the account in all Regions**
Use the [get-instance-metadata-defaults](https://docs.aws.amazon.com/cli/latest/reference/ec2/get-instance-metadata-defaults.html) command.
```
echo -e "Region \t Level HttpTokensEnforced" ; \
echo -e "-------------- \t ------------ ----------------" ; \
for region in $(
aws ec2 describe-regions \
--region us-east-1 \
--query "Regions[*].[RegionName]" \
--output text
);
do (output=$(
aws ec2 get-instance-metadata-defaults \
--region $region \
--query 'AccountLevel.HttpTokensEnforced' \
--output text)
echo -e "$region \t ACCOUNTLEVEL $output"
);
done
```
The following is example output.
```
Region Level HttpTokensEnforced
-------------- ------------ ------------------
ap-south-1 ACCOUNTLEVEL enabled
eu-north-1 ACCOUNTLEVEL enabled
eu-west-3 ACCOUNTLEVEL enabled
...
```
------
#### [ PowerShell ]
**To enforce IMDSv2 for the account in the specified Region**
Use the [Edit-EC2InstanceMetadataDefault](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2InstanceMetadataDefault.html) cmdlet and specify the Region in which to enforce IMDSv2.
```
Edit-EC2InstanceMetadataDefault `
-Region us-east-1 `
-HttpToken required `
-HttpPutResponseHopLimit 2
```
The following is example output.
```
@{
Return = $true
}
```
**To view the IMDSv2 enforcement setting for the account in a specific Region**
Use the Get-EC2InstanceMetadataDefault command and specify the Region.
```
Get-EC2InstanceMetadataDefault -Region us-east-1
```
The following is example output.
```
@{
AccountLevel = @{
HttpTokens = "required"
HttpTokensEnforced = "enabled"
}
ManagedBy = "account"
}
```
The `ManagedBy` field indicates the entity that configured the settings. In this example, `account` indicates that the settings were configured directly in the account. A value of `declarative-policy` would mean the settings were configured by a declarative policy. For more information, see [Declarative policies](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_declarative.html) in the *AWS Organizations User Guide*.
**To enforce IMDSv2 for the account for all Regions**
Use the [modify-instance-metadata-defaults](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-metadata-defaults.html) command to enforce IMDSv2 in all Regions.
```
echo -e "Region \t Modified" ; \
echo -e "-------------- \t ---------" ; \
for region in $(
aws ec2 describe-regions \
--region us-east-1 \
--query "Regions[*].[RegionName]" \
--output text
);
do (output=$(
aws ec2 modify-instance-metadata-defaults \
--region $region \
--http-tokens-enforced enabled \
--output text)
echo -e "$region \t $output"
);
done
```
The following is example output.
```
Region Modified
-------------- ---------
ap-south-1 True
eu-north-1 True
eu-west-3 True
...
```
**To set IMDSv2 as the default for the account for all Regions**
Use the [Edit-EC2InstanceMetadataDefault](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2InstanceMetadataDefault.html) cmdlet to modify the IMDS account level settings for all Regions. Include `-HttpToken` set to `required` and `-HttpPutResponseHopLimit` set to `2` if your instances will host containers. Otherwise, specify `-1` to indicate no preference. When `-1` (no preference) is specified, at launch, the value defaults to `2` if the AMI has the setting `ImdsSupport: v2.0`; otherwise it defaults to `1`.
```
(Get-EC2Region).RegionName | `
ForEach-Object {
[PSCustomObject]@{
Region = $_
Modified = (Edit-EC2InstanceMetadataDefault `
-Region $_ `
-HttpToken required `
-HttpPutResponseHopLimit 2)
}
} | `
Format-Table Region, Modified -AutoSize
```
Expected output
```
Region Modified
------ --------
ap-south-1 True
eu-north-1 True
eu-west-3 True
...
```
**To view the default account settings for the instance metadata options for all Regions**
Use the [Get-EC2InstanceMetadataDefault](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-EC2InstanceMetadataDefault.html) cmdlet.
```
(Get-EC2Region).RegionName | `
ForEach-Object {
[PSCustomObject]@{
Region = $_
HttpPutResponseHopLimit = (Get-EC2InstanceMetadataDefault -Region $_).HttpPutResponseHopLimit
HttpTokens = (Get-EC2InstanceMetadataDefault -Region $_).HttpTokens
}
} | `
Format-Table -AutoSize
```
Example output
```
Region HttpPutResponseHopLimit HttpTokens
------ ----------------------- ----------
ap-south-1 2 required
eu-north-1 2 required
eu-west-3 2 required
...
```
------
### Configure the instance at launch
When you [launch an instance](ec2-launch-instance-wizard.md), you can configure the instance to require the use of IMDSv2 by configuring the following fields:
+ Amazon EC2 console: Set **Metadata version** to **V2 only (token required)**.
+ AWS CLI: Set `HttpTokens` to `required`.
When you specify that IMDSv2 is required, you must also enable the Instance Metadata Service (IMDS) endpoint by setting **Metadata accessible** to **Enabled** (console) or `HttpEndpoint` to `enabled` (AWS CLI).
In a container environment, when IMDSv2 is required, we recommend setting the hop limit to `2`. For more information, see [Instance metadata access considerations](instancedata-data-retrieval.md#imds-considerations).
------
#### [ Console ]
**To require the use of IMDSv2 on a new instance**
+ When launching a new instance in the Amazon EC2 console, expand **Advanced details**, and do the following:
+ For **Metadata accessible**, choose **Enabled**.
+ For **Metadata version**, choose **V2 only (token required)**.
+ (Container environment) For **Metadata response hop limit**, choose **2**.
For more information, see [Advanced details](ec2-instance-launch-parameters.md#liw-advanced-details).
------
#### [ AWS CLI ]
**To require the use of IMDSv2 on a new instance**
The following [run-instances](https://docs.aws.amazon.com/cli/latest/reference/ec2/run-instances.html) example launches a `c6i.large` instance with `--metadata-options` set to `HttpTokens=required`. When you specify a value for `HttpTokens`, you must also set `HttpEndpoint` to `enabled`. Because the secure token header is set to `required` for metadata retrieval requests, this requires the instance to use IMDSv2 when requesting instance metadata.
In a container environment, when IMDSv2 is required, we recommend setting the hop limit to `2` with `HttpPutResponseHopLimit=2`.
```
aws ec2 run-instances \
--image-id ami-0abcdef1234567890 \
--instance-type c6i.large \
...
--metadata-options "HttpEndpoint=enabled,HttpTokens=required,HttpPutResponseHopLimit=2"
```
------
#### [ PowerShell ]
**To require the use of IMDSv2 on a new instance**
The following [New-EC2Instance](https://docs.aws.amazon.com/powershell/latest/reference/items/New-EC2Instance.html) cmdlet example launches a `c6i.large` instance with `MetadataOptions_HttpEndpoint` set to `enabled` and the `MetadataOptions_HttpTokens` parameter to `required`. When you specify a value for `HttpTokens`, you must also set `HttpEndpoint` to `enabled`. Because the secure token header is set to `required` for metadata retrieval requests, this requires the instance to use IMDSv2 when requesting instance metadata.
```
New-EC2Instance `
-ImageId ami-0abcdef1234567890 `
-InstanceType c6i.large `
-MetadataOptions_HttpEndpoint enabled `
-MetadataOptions_HttpTokens required
```
------
#### [ CloudFormation ]
To specify the metadata options for an instance using CloudFormation, see the [AWS::EC2::LaunchTemplate MetadataOptions](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-ec2-launchtemplate-metadataoptions.html) property in the *AWS CloudFormation User Guide*.
------
### Configure the AMI
When you register a new AMI or modify an existing AMI, you can set the `imds-support` parameter to `v2.0`. Instances launched from this AMI will have **Metadata version** set to **V2 only (token required)** (console) or `HttpTokens` set to `required` (AWS CLI). With these settings, the instance requires that IMDSv2 is used when requesting instance metadata.
Note that when you set `imds-support` to `v2.0`, instances launched from this AMI will also have **Metadata response hop limit** (console) or `http-put-response-hop-limit` (AWS CLI) set to **2**.
**Important**
Do not use this parameter unless your AMI software supports IMDSv2. After you set the value to `v2.0`, you can't undo it. The only way to "reset" your AMI is to create a new AMI from the underlying snapshot.
**To configure a new AMI for IMDSv2**
Use one of the following methods to configure a new AMI for IMDSv2.
------
#### [ AWS CLI ]
The following [register-image](https://docs.aws.amazon.com/cli/latest/reference/ec2/register-image.html) example registers an AMI using the specified snapshot of an EBS root volume as device `/dev/xvda`. Specify `v2.0` for the `imds-support` parameter so that instances launched from this AMI will require that IMDSv2 is used when requesting instance metadata.
```
aws ec2 register-image \
--name my-image \
--root-device-name /dev/xvda \
--block-device-mappings DeviceName=/dev/xvda,Ebs={SnapshotId=snap-0123456789example} \
--architecture x86_64 \
--imds-support v2.0
```
------
#### [ PowerShell ]
The following [Register-EC2Image](https://docs.aws.amazon.com/powershell/latest/reference/items/Register-EC2Image.html) cmdlet example registers an AMI using the specified snapshot of an EBS root volume as device `/dev/xvda`. Specify `v2.0` for the `ImdsSupport` parameter so that instances launched from this AMI will require that IMDSv2 is used when requesting instance metadata.
```
Register-EC2Image `
-Name 'my-image' `
-RootDeviceName /dev/xvda `
-BlockDeviceMapping (
New-Object `
-TypeName Amazon.EC2.Model.BlockDeviceMapping `
-Property @{
DeviceName = '/dev/xvda';
EBS = (New-Object -TypeName Amazon.EC2.Model.EbsBlockDevice -Property @{
SnapshotId = 'snap-0123456789example'
VolumeType = 'gp3'
} )
} ) `
-Architecture X86_64 `
-ImdsSupport v2.0
```
------
**To configure an existing AMI for IMDSv2**
Use one of the following methods to configure an existing AMI for IMDSv2.
------
#### [ AWS CLI ]
The following [modify-image-attribute](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-image-attribute.html) example modifies an existing AMI for IMDSv2 only. Specify `v2.0` for the `imds-support` parameter so that instances launched from this AMI will require that IMDSv2 is used when requesting instance metadata.
```
aws ec2 modify-image-attribute \
--image-id ami-0abcdef1234567890 \
--imds-support v2.0
```
------
#### [ PowerShell ]
The following [Edit-EC2ImageAttribute](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2ImageAttribute.html) cmdlet example modifies an existing AMI for IMDSv2 only. Specify `v2.0` for the `imds-support` parameter so that instances launched from this AMI will require that IMDSv2 is used when requesting instance metadata.
```
Edit-EC2ImageAttribute `
-ImageId ami-0abcdef1234567890 `
-ImdsSupport 'v2.0'
```
------
### Use an IAM policy
You can create an IAM policy that does one of the following:
+ Prevents users from launching new instances unless they require IMDSv2 on the new instance.
+ Prevents users from calling the ModifyInstanceMetadataOptions API to change the metadata options of a running instance. Restrict access to the ModifyInstanceMetadataOptions httpTokens property to prevent unintended updates of running instances.
+ Prevent users from calling the ModifyInstanceMetadataDefaults API to change the account default settings of both httpTokens and httpTokensEnforced. Restricting access to these two properties will ensure that only authorized roles can modify the account defaults.
**To enforce the use of IMDSv2 on all new instances by using an IAM policy**
To ensure that users can only launch instances that require the use of IMDSv2 when requesting instance metadata, do the following:
+ Restrict access to both `ModifyInstanceMetadataOptions` and `ModifyInstanceMetadataDefaults` API, and more specifically the `httpTokens` and `httpTokensEnforced` properties.
+ Then, set the account default to `httpTokens = required` and `httpTokensEnforced = enabled`.
For the example IAM policy, see [Work with instance metadata](ExamplePolicies_EC2.md#iam-example-instance-metadata).
## Enable the IMDS IPv4 and IPv6 endpoints
The IMDS has two endpoints on an instance: IPv4 (`169.254.169.254`) and IPv6 (`[fd00:ec2::254]`). When you enable the IMDS, the IPv4 endpoint is automatically enabled. The IPv6 endpoint remains disabled even if you launch an instance into an IPv6-only subnet. To enable the IPv6 endpoint, you need to do so explicitly. When you enable the IPv6 endpoint, the IPv4 endpoint remains enabled.
You can enable the IPv6 endpoint at instance launch or after.
**Requirements for enabling the IPv6 endpoint**
+ The selected instance type is a [Nitro-based instance](instance-types.md#instance-hypervisor-type).
+ The selected subnet supports IPv6, where the subnet is either [dual stack or IPv6 only](https://docs.aws.amazon.com/vpc/latest/userguide/configure-subnets.html#subnet-ip-address-range).
Use any of the following methods to launch an instance with the IMDS IPv6 endpoint enabled.
------
#### [ Console ]
**To enable the IMDS IPv6 endpoint at instance launch**
+ [Launch the instance](ec2-launch-instance-wizard.md) in the Amazon EC2 console with the following specified under **Advanced details**:
+ For **Metadata IPv6 endpoint**, choose **Enabled**.
For more information, see [Advanced details](ec2-instance-launch-parameters.md#liw-advanced-details).
------
#### [ AWS CLI ]
**To enable the IMDS IPv6 endpoint at instance launch**
The following [run-instances](https://docs.aws.amazon.com/cli/latest/reference/ec2/run-instances.html) example launches a `c6i.large` instance with the IPv6 endpoint enabled for the IMDS. To enable the IPv6 endpoint, for the `--metadata-options` parameter, specify `HttpProtocolIpv6=enabled`. When you specify a value for `HttpProtocolIpv6`, you must also set `HttpEndpoint` to `enabled`.
```
aws ec2 run-instances \
--image-id ami-0abcdef1234567890 \
--instance-type c6i.large \
...
--metadata-options "HttpEndpoint=enabled,HttpProtocolIpv6=enabled"
```
------
#### [ PowerShell ]
**To enable the IMDS IPv6 endpoint at instance launch**
The following [New-EC2Instance](https://docs.aws.amazon.com/powershell/latest/reference/items/New-EC2Instance.html) cmdlet example launches a `c6i.large` instance with the IPv6 endpoint enabled for the IMDS. To enable the IPv6 endpoint, specify `MetadataOptions_HttpProtocolIpv6` as `enabled`. When you specify a value for `MetadataOptions_HttpProtocolIpv6`, you must also set `MetadataOptions_HttpEndpoint` to `enabled`.
```
New-EC2Instance `
-ImageId ami-0abcdef1234567890 `
-InstanceType c6i.large `
-MetadataOptions_HttpEndpoint enabled `
-MetadataOptions_HttpProtocolIpv6 enabled
```
------
## Turn off access to instance metadata
You can turn off access to the instance metadata by disabling the IMDS when you launch an instance. You can turn on access later by re-enabling the IMDS. For more information, see [Turn on access to instance metadata](configuring-IMDS-existing-instances.md#enable-instance-metadata-on-existing-instances).
**Important**
You can choose to disable the IMDS at launch or after launch. If you disable the IMDS *at launch*, the following might not work:
You might not have SSH access to your instance. The `public-keys/0/openssh-key`, which is your instance's public SSH key, will not be accessible because the key is normally provided and accessed from EC2 instance metadata.
EC2 user data will not be available and will not run at instance start. EC2 user data is hosted on the IMDS. If you disable the IMDS, you effectively turn off access to user data.
To access this functionality, you can re-enable the IMDS after launch.
------
#### [ Console ]
**To turn off access to instance metadata at launch**
+ [Launch the instance](ec2-launch-instance-wizard.md) in the Amazon EC2 console with the following specified under **Advanced details**:
+ For **Metadata accessible**, choose **Disabled**.
For more information, see [Advanced details](ec2-instance-launch-parameters.md#liw-advanced-details).
------
#### [ AWS CLI ]
**To turn off access to instance metadata at launch at launch**
Launch the instance with `--metadata-options` set to `HttpEndpoint=disabled`.
```
aws ec2 run-instances \
--image-id ami-0abcdef1234567890 \
--instance-type c6i.large \
...
--metadata-options "HttpEndpoint=disabled"
```
------
#### [ PowerShell ]
**To turn off access to instance metadata at launch at launch**
The following [New-EC2Instance](https://docs.aws.amazon.com/powershell/latest/reference/items/New-EC2Instance.html) cmdlet example launches an instance with `MetadataOptions_HttpEndpoint` set to `disabled`.
```
New-EC2Instance `
-ImageId ami-0abcdef1234567890 `
-InstanceType c6i.large `
-MetadataOptions_HttpEndpoint disabled
```
------
#### [ CloudFormation ]
To specify the metadata options for an instance using CloudFormation, see the [AWS::EC2::LaunchTemplate MetadataOptions](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-ec2-launchtemplate-metadataoptions.html) property in the *CloudFormation User Guide*.
------
## Allow access to tags in instance metadata
By default, instance tags are not accessible in the instance metadata. For each instance, you must explicitly allow access. If access is allowed, instance tag *keys* must comply with specific character restrictions, otherwise the instance launch will fail. For more information, see [Enable access to tags in instance metadata](work-with-tags-in-IMDS.md#allow-access-to-tags-in-IMDS).
# Modify instance metadata options for existing instances
For existing instances
You can modify the instance metadata options for existing instances.
You can also create an IAM policy that prevents users from modifying the instance metadata options on existing instances. To control which users can modify the instance metadata options, specify a policy that prevents all users other than users with a specified role to use the [ModifyInstanceMetadataOptions](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyInstanceMetadataOptions.html) API. For the example IAM policy, see [Work with instance metadata](ExamplePolicies_EC2.md#iam-example-instance-metadata).
**Note**
If a declarative policy was used to configure the instance metadata options, you can't modify them directly within the account. For more information, see [Declarative policies](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_declarative.html) in the *AWS Organizations User Guide.*
## Require the use of IMDSv2
Use one of the following methods to modify the instance metadata options on an existing instance to require that IMDSv2 is used when requesting instance metadata. When IMDSv2 is required, IMDSv1 cannot be used.
**Note**
Before requiring that IMDSv2 is used, ensure that the instance isn't making IMDSv1 calls. The `MetadataNoToken` CloudWatch metric tracks IMDSv1 calls. When `MetadataNoToken` records zero IMDSv1 usage for an instance, the instance is then ready to require IMDSv2.
------
#### [ Console ]
**To require the use of IMDSv2 on an existing instance**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation pane, choose **Instances**.
1. Select your instance.
1. Choose **Actions**, **Instance settings**, **Modify instance metadata options**.
1. In the **Modify instance metadata options** dialog box, do the following:
1. For **Instance metadata service**, select **Enable**.
1. For **IMDSv2**, choose **Required**.
1. Choose **Save**.
------
#### [ AWS CLI ]
**To require the use of IMDSv2 on an existing instance**
Use the [modify-instance-metadata-options](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-metadata-options.html) CLI command and set the `http-tokens` parameter to `required`. When you specify a value for `http-tokens`, you must also set `http-endpoint` to `enabled`.
```
aws ec2 modify-instance-metadata-options \
--instance-id i-1234567890abcdef0 \
--http-tokens required \
--http-endpoint enabled
```
------
#### [ PowerShell ]
**To require the use of IMDSv2 on an existing instance**
Use the [Edit-EC2InstanceMetadataOption](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2InstanceMetadataOption.html) cmdlet and set the `HttpTokens` parameter to `required`. When you specify a value for `HttpTokens`, you must also set `HttpEndpoint` to `enabled`.
```
(Edit-EC2InstanceMetadataOption `
-InstanceId i-1234567890abcdef0 `
-HttpTokens required `
-HttpEndpoint enabled).InstanceMetadataOptions
```
------
## Restore the use of IMDSv1
When IMDSv2 is required on an instance, using an IMDSv1 request will fail. When IMDSv2 is optional, then both IMDSv2 and IMDSv1 will work. Therefore, to restore IMDSv1, set IMDSv2 to optional (`httpTokens = optional`) using one of the following methods.
The `httpTokensEnforced` IMDS property also prevents attempts to enable IMDSv1 on an existing instance. When enabled for an account in a Region, an attempt to set `httpTokens` to `optional` will result in an `UnsupportedOperation` exception. Fore more information, see [Troubleshooting](#troubleshoot-modifying-an-imdsv1-enabled-instance-fails).
**Important**
If your instance launches are failing due to IMDSv2 enforcement, you have two options to enable launches to succeed:
**Launch instances as IMDSv2-only** – If the software running on the instances uses IMDSv2 only (no dependency on IMDSv1), then you can launch the instances as IMDSv2 only. To do this, configure IMDSv2 only by setting `httpTokens = required` either in the launch parameters or in the metadata defaults for the account in the Region.
**Disable enforcement** – If your software still depends on IMDSv1, set `httpTokensEnforced` to `disabled` for the account in the Region. For more information, see [Enforce IMDSv2 at the account level](configuring-IMDS-new-instances.md#enforce-imdsv2-at-the-account-level).
------
#### [ Console ]
**To restore the use of IMDSv1 on an instance**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation pane, choose **Instances**.
1. Select your instance.
1. Choose **Actions**, **Instance settings**, **Modify instance metadata options**.
1. In the **Modify instance metadata options** dialog box, do the following:
1. For **Instance metadata service**, make sure that **Enable** is selected.
1. For **IMDSv2**, choose **Optional**.
1. Choose **Save**.
------
#### [ AWS CLI ]
**To restore the use of IMDSv1 on an instance**
You can use the [modify-instance-metadata-options](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-metadata-options.html) CLI command with `http-tokens` set to `optional` to restore the use of IMDSv1 when requesting instance metadata.
```
aws ec2 modify-instance-metadata-options \
--instance-id i-1234567890abcdef0 \
--http-tokens optional \
--http-endpoint enabled
```
------
#### [ PowerShell ]
**To restore the use of IMDSv1 on an instance**
You can use the [Edit-EC2InstanceMetadataOption](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2InstanceMetadataOption.html) cmdlet with `HttpTokens` set to `optional` to restore the use of IMDSv1 when requesting instance metadata.
```
(Edit-EC2InstanceMetadataOption `
-InstanceId i-1234567890abcdef0 `
-HttpTokens optional `
-HttpEndpoint enabled).InstanceMetadataOptions
```
------
## Change the PUT response hop limit
For existing instances, you can change the settings of the `PUT` response hop limit.
Currently only the AWS CLI and AWS SDKs support changing the PUT response hop limit.
------
#### [ AWS CLI ]
**To change the PUT response hop limit**
Use the [modify-instance-metadata-options](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-metadata-options.html) CLI command and set the `http-put-response-hop-limit` parameter to the required number of hops. In the following example, the hop limit is set to `3`. Note that when specifying a value for `http-put-response-hop-limit`, you must also set `http-endpoint` to `enabled`.
```
aws ec2 modify-instance-metadata-options \
--instance-id i-1234567890abcdef0 \
--http-put-response-hop-limit 3 \
--http-endpoint enabled
```
------
#### [ PowerShell ]
**To change the PUT response hop limit**
Use the [Edit-EC2InstanceMetadataOption](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2InstanceMetadataOption.html) cmdlet and set the `HttpPutResponseHopLimit` parameter to the required number of hops. In the following example, the hop limit is set to `3`. Note that when specifying a value for `HttpPutResponseHopLimit`, you must also set `HttpEndpoint` to `enabled`.
```
(Edit-EC2InstanceMetadataOption `
-InstanceId i-1234567890abcdef0 `
-HttpPutResponseHopLimit 3 `
-HttpEndpoint enabled).InstanceMetadataOptions
```
------
## Enable the IMDS IPv4 and IPv6 endpoints
The IMDS has two endpoints on an instance: IPv4 (`169.254.169.254`) and IPv6 (`[fd00:ec2::254]`). When you enable the IMDS, the IPv4 endpoint is automatically enabled. The IPv6 endpoint remains disabled even if you launch an instance into an IPv6-only subnet. To enable the IPv6 endpoint, you need to do so explicitly. When you enable the IPv6 endpoint, the IPv4 endpoint remains enabled.
You can enable the IPv6 endpoint at instance launch or after.
**Requirements for enabling the IPv6 endpoint**
+ The selected instance type is a [Nitro-based instance](instance-types.md#instance-hypervisor-type).
+ The selected subnet supports IPv6, where the subnet is either [dual stack or IPv6 only](https://docs.aws.amazon.com/vpc/latest/userguide/configure-subnets.html#subnet-ip-address-range).
Currently only the AWS CLI and AWS SDKs support enabling the IMDS IPv6 endpoint after instance launch.
------
#### [ AWS CLI ]
**To enable the IMDS IPv6 endpoint for your instance**
Use the [modify-instance-metadata-options](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-metadata-options.html) CLI command and set the `http-protocol-ipv6` parameter to `enabled`. Note that when specifying a value for `http-protocol-ipv6`, you must also set `http-endpoint` to `enabled`.
```
aws ec2 modify-instance-metadata-options \
--instance-id i-1234567890abcdef0 \
--http-protocol-ipv6 enabled \
--http-endpoint enabled
```
------
#### [ PowerShell ]
**To enable the IMDS IPv6 endpoint for your instance**
Use the [Edit-EC2InstanceMetadataOption](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2InstanceMetadataOption.html) cmdlet and set the `HttpProtocolIpv6` parameter to `enabled`. Note that when specifying a value for `HttpProtocolIpv6`, you must also set `HttpEndpoint` to `enabled`.
```
(Edit-EC2InstanceMetadataOption `
-InstanceId i-1234567890abcdef0 `
-HttpProtocolIpv6 enabled `
-HttpEndpoint enabled).InstanceMetadataOptions
```
------
## Turn on access to instance metadata
You can turn on access to instance metadata by enabling the HTTP endpoint of the IMDS on your instance, regardless of which version of the IMDS you are using. You can reverse this change at any time by disabling the HTTP endpoint.
Use one of the following methods to turn on access to instance metadata on an instance.
------
#### [ Console ]
**To turn on access to instance metadata**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation pane, choose **Instances**.
1. Select your instance.
1. Choose **Actions**, **Instance settings**, **Modify instance metadata options**.
1. In the **Modify instance metadata options** dialog box, do the following:
1. For **Instance metadata service**, select **Enable**.
1. Choose **Save**.
------
#### [ AWS CLI ]
**To turn on access to instance metadata**
Use the [modify-instance-metadata-options](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-metadata-options.html) CLI command and set the `http-endpoint` parameter to `enabled`.
```
aws ec2 modify-instance-metadata-options \
--instance-id i-1234567890abcdef0 \
--http-endpoint enabled
```
------
#### [ PowerShell ]
**To turn on access to instance metadata**
Use the [Edit-EC2InstanceMetadataOption](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2InstanceMetadataOption.html) cmdlet and set the `HttpEndpoint` parameter to `enabled`.
```
(Edit-EC2InstanceMetadataOption `
-InstanceId i-1234567890abcdef0 `
-HttpEndpoint enabled).InstanceMetadataOptions
```
------
## Turn off access to instance metadata
You can turn off access to instance metadata by disabling the HTTP endpoint of the IMDS on your instance, regardless of which version of the IMDS you are using. You can reverse this change at any time by enabling the HTTP endpoint.
Use one of the following methods to turn off access to instance metadata on an instance.
------
#### [ Console ]
**To turn off access to instance metadata**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation pane, choose **Instances**.
1. Select your instance.
1. Choose **Actions**, **Instance settings**, **Modify instance metadata options**.
1. In the **Modify instance metadata options** dialog box, do the following:
1. For **Instance metadata service**, clear **Enable**.
1. Choose **Save**.
------
#### [ AWS CLI ]
**To turn off access to instance metadata**
Use the [modify-instance-metadata-options](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-metadata-options.html) CLI command and set the `http-endpoint` parameter to `disabled`.
```
aws ec2 modify-instance-metadata-options \
--instance-id i-1234567890abcdef0 \
--http-endpoint disabled
```
------
#### [ PowerShell ]
**To turn off access to instance metadata**
Use the [Edit-EC2InstanceMetadataOption](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2InstanceMetadataOption.html) cmdlet and set the `HttpEndpoint` parameter to `disabled`.
```
(Edit-EC2InstanceMetadataOption `
-InstanceId i-1234567890abcdef0 `
-HttpEndpoint disabled).InstanceMetadataOptions
```
------
## Allow access to tags in instance metadata
You can allow access to tags in the instance metadata on a running or stopped instance. For each instance, you must explicitly allow access. If access is allowed, instance tag *keys* must comply with specific character restrictions, otherwise you get an error. For more information, see [Enable access to tags in instance metadata](work-with-tags-in-IMDS.md#allow-access-to-tags-in-IMDS).
## Troubleshooting
### Modifying an IMDSv1-enabled instance fails
#### Description
You get the following error message:
`You can't launch instances with IMDSv1 because httpTokensEnforced is enabled for this account. Either launch the instance with httpTokens=required or contact your account owner to disable httpTokensEnforced using the ModifyInstanceMetadataDefaults API or the account settings in the EC2 console.`
#### Cause
This error is thrown when you attempt to modify an existing instance to be IMDSv1 enabled (`httpTokens = optional`) in an account where the EC2 account settings or an AWS Organization declarative policy enforces the use of IMDSv2 (`httpTokensEnforced = enabled`).
#### Solution
If you require IMDSv1 support on existing instances, you'll need to disable IMDSv2 enforcement for the account in the Region. To disable IMDSv2 enforcement, set `HttpTokensEnforced` to `disabled`. For more information, see [ModifyInstanceMetadataDefaults](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyInstanceMetadataDefaults.html) in the Amazon EC2 API Reference. If you prefer to configure this setting using the console, see [Enforce IMDSv2 at the account level](configuring-IMDS-new-instances.md#enforce-imdsv2-at-the-account-level).
We recommend that you use IMDSv2 only (`httpTokens=required`). For more information, see [Transition to using Instance Metadata Service Version 2](instance-metadata-transition-to-version-2.md).
# Run commands when you launch an EC2 instance with user data input
Run commands at launch
When you launch an Amazon EC2 instance, you can pass user data to the instance that is used to perform automated configuration tasks, or to run scripts after the instance starts.
If you're interested in more complex automation scenarios, you might consider CloudFormation. For more information, see [Deploying applications on Amazon EC2 with CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/deploying.applications.html) in the *AWS CloudFormation User Guide*.
On Linux instances, you can pass two types of user data to Amazon EC2: shell scripts and cloud-init directives. You can also pass this data into the launch instance wizard as plain text, as a file (this is useful for launching instances with the command line tools), or as base64-encoded text (for API calls).
On Windows instances, the launch agents handle your user data scripts.
**Considerations**
+ User data is treated as opaque data: what you give is what you get back. It is up to the instance to interpret it.
+ User data must be base64-encoded. The Amazon EC2 console can perform the base64-encoding for your or accept base64-encoded input. If you retrieve the user data using instance metadata or the console, it's base64-decoded for you automatically.
+ User data is limited to 16 KB, in raw form, before it is base64-encoded. The size of a string of length *n* after base64-encoding is ceil(*n*/3)\$14.
+ User data is an instance attribute. If you create an AMI from an instance, the instance user data is not included in the AMI.
## User data in the AWS Management Console
User data in the console
You can specify instance user data when you launch the instance. If the root volume of the instance is an EBS volume, you can also stop the instance and update its user data.
### Specify instance user data at launch with the Launch Wizard
You can specify user data when you launch an instance with the Launch Wizard in the EC2 console. To specify user data on launch, follow the procedure for [launching an instance](ec2-launch-instance-wizard.md). The **User data** field is located in the [Advanced details](ec2-instance-launch-parameters.md#liw-advanced-details) section of the launch instance wizard. Enter your PowerShell script in the **User data** field, and then complete the instance launch procedure.
In the following screenshot of the **User data** field, the example script creates a file in the Windows temporary folder, using the current date and time in the file name. When you include `true`, the script is run every time you reboot or start the instance. If you leave the **User data has already been base64 encoded** checkbox empty, the Amazon EC2 console performs the base64 encoding for you.
![\[Advance Details user data text field.\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/configure_ec2config_userdata.png)
For more information, see [Specify instance user data at launch with the Launch Wizard](#user-data-launch-instance-wizard). For a Linux example that uses the AWS CLI, see [User data and the AWS CLI](#user-data-api-cli). For a Windows example that uses the Tools for Windows PowerShell, see [User data and the Tools for Windows PowerShell](#user-data-powershell).
### View and update the instance user data
You can view the instance user data for any instance, and you can update the instance user data for a stopped instance.
**To update the user data for an instance using the console**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation pane, choose **Instances**.
1. Select the instance and choose **Actions**, **Instance state**, **Stop instance**.
**Warning**
When you stop an instance, the data on instance store volumes is lost. To preserve this data, back it up to persistent storage.
1. When prompted for confirmation, choose **Stop**. It can take a few minutes for the instance to stop.
1. With the instance still selected, choose **Actions**, **Instance settings**, **Edit user data**. You can't change the user data if the instance is running, but you can view it.
1. In the **Edit user data** dialog box, update the user data, and then choose **Save**. To run user data scripts every time you reboot or start the instance, add `true`, as shown in the following example:
![\[Edit User Data dialog box.\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/view-change-user-data.png)
1. Start the instance. If you enabled user data execution for subsequent reboots or starts, the updated user data scripts are run as part of the instance start process.
## How Amazon EC2 handles user data for Linux instances
User data for Linux instances
The following examples use user data to run commands that set up a LAMP server when the instance launches. In each example, the following tasks are performed:
+ The distribution software packages are updated.
+ The web server, `php`, and `mariadb` packages are installed.
+ The `httpd` service is started and turned on.
+ The user `ec2-user` is added to the apache group.
+ The appropriate ownership and file permissions are set for the web directory and the files contained within it.
+ A simple web page is created to test the web server and PHP engine.
**Topics**
+ [
### Prerequisites
](#user-data-requirements)
+ [
### User data and shell scripts
](#user-data-shell-scripts)
+ [
### Update the instance user data
](#user-data-modify)
+ [
### User data and cloud-init directives
](#user-data-cloud-init)
+ [
### User data and the AWS CLI
](#user-data-api-cli)
+ [
### Combine shell scripts and cloud-init directives
](#user-data-mime-multi)
### Prerequisites
The examples in this topic assume the following:
+ Your instance has a public DNS name that is reachable from the internet.
+ The security group associated with your instance is configured to allow SSH (port 22) traffic so that you can connect to the instance to view the output log files.
+ Your instance is launched using an Amazon Linux AMI. The commands and directives might not work for other Linux distributions. For more information about other distributions, such as their support for cloud-init, see documentation for the specific distribution.
### User data and shell scripts
If you are familiar with shell scripting, this is the easiest and most complete way to send instructions to an instance at launch. Adding these tasks at boot time adds to the amount of time it takes to boot the instance. You should allow a few minutes of extra time for the tasks to complete before you test that the user script has finished successfully.
**Important**
By default, user data scripts and cloud-init directives run only during the boot cycle when you first launch an instance. You can update your configuration to ensure that your user data scripts and cloud-init directives run every time you restart your instance. For more information, see [How can I utilize user data to automatically run a script with every restart of my Amazon EC2 Linux instance?](https://repost.aws/knowledge-center/execute-user-data-ec2) in the AWS Knowledge Center.
User data shell scripts must start with the `#!` characters and the path to the interpreter you want to read the script (commonly **/bin/bash)**. For an introduction on shell scripting, see the [Bash Reference Manual](https://www.gnu.org/software/bash/manual/bash.html) on the *GNU Operating System* website.
Scripts entered as user data are run as the root user, so do not use the **sudo** command in the script. Remember that any files you create will be owned by the root user; if you need a non-root user to have file access, you should modify the permissions accordingly in the script. Also, because the script is not run interactively, you cannot include commands that require user feedback (such as **yum update** without the `-y` flag).
If you use an AWS API, including the AWS CLI, in a user data script, you must use an instance profile when launching the instance. An instance profile provides the appropriate AWS credentials required by the user data script to issue the API call. For more information, see [Use instance profiles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2_instance-profiles.html) in the IAM User Guide. The permissions you assign to the IAM role depend on which services you are calling with the API. For more information, see [IAM roles for Amazon EC2](iam-roles-for-amazon-ec2.md).
The cloud-init output log file captures console output so it is easy to debug your scripts following a launch if the instance does not behave the way you intended. To view the log file, [connect to the instance](connect-to-linux-instance.md) and open `/var/log/cloud-init-output.log`.
When a user data script is processed, it is copied to and run from `/var/lib/cloud/instances/instance-id/`. The script is not deleted after it is run. Be sure to delete the user data scripts from `/var/lib/cloud/instances/instance-id/` before you create an AMI from the instance. Otherwise, the script will exist in this directory on any instance launched from the AMI.
### Update the instance user data
To update the instance user data, you must first stop the instance. If the instance is running, you can view the user data but you cannot modify it.
**Warning**
When you stop an instance, the data on instance store volumes is lost. To preserve this data, back it up to persistent storage.
**To modify instance user data**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation pane, choose **Instances**.
1. Select the instance and choose **Instance state**, **Stop instance**. If this option is disabled, either the instance is already stopped or its root volume is an instance store volume.
1. When prompted for confirmation, choose **Stop**. It can take a few minutes for the instance to stop.
1. With the instance still selected, choose **Actions**, **Instance settings**, **Edit user data**.
1. Modify the user data as needed, and then choose **Save**.
1. Start the instance. The new user data is visible on your instance after you start it; however, user data scripts are not run.
### User data and cloud-init directives
The cloud-init package configures specific aspects of a new Amazon Linux instance when it is launched; most notably, it configures the `.ssh/authorized_keys` file for the ec2-user so you can log in with your own private key. For more information about the configuration tasks that the cloud-init package performs for Amazon Linux instances, see the following documentation:
+ **Amazon Linux 2023** – [Customized cloud-init](https://docs.aws.amazon.com/linux/al2023/ug/cloud-init.html)
+ **Amazon Linux 2** – [Using cloud-init on Amazon Linux 2](https://docs.aws.amazon.com/linux/al2/ug/amazon-linux-cloud-init.html)
The cloud-init user directives can be passed to an instance at launch the same way that a script is passed, although the syntax is different. For more information about cloud-init, see [https://cloudinit.readthedocs.org/en/latest/index.html](https://cloudinit.readthedocs.org/en/latest/index.html).
**Important**
By default, user data scripts and cloud-init directives run only during the boot cycle when you first launch an instance. You can update your configuration to ensure that your user data scripts and cloud-init directives run every time you restart your instance. For more information, see [How can I utilize user data to automatically run a script with every restart of my Amazon EC2 Linux instance?](https://repost.aws/knowledge-center/execute-user-data-ec2) in the AWS Knowledge Center.
Adding these tasks at boot time adds to the amount of time it takes to boot an instance. You should allow a few minutes of extra time for the tasks to complete before you test that your user data directives have completed.
**To pass cloud-init directives to an Amazon Linux instance**
1. Follow the procedure for [launching an instance](ec2-launch-instance-wizard.md). The **User data** field is located in the [Advanced details](ec2-instance-launch-parameters.md#liw-advanced-details) section of the launch instance wizard. Enter your cloud-init directive text in the **User data** field, and then complete the instance launch procedure.
In the examples below, the directives create and configure a web server on Amazon Linux. The `#cloud-config` line at the top is required in order to identify the commands as cloud-init directives.
------
#### [ AL2023 ]
```
#cloud-config
package_update: true
package_upgrade: all
packages:
- httpd
- mariadb105-server
- php8.1
- php8.1-mysqlnd
runcmd:
- systemctl start httpd
- systemctl enable httpd
- [ sh, -c, "usermod -a -G apache ec2-user" ]
- [ sh, -c, "chown -R ec2-user:apache /var/www" ]
- chmod 2775 /var/www
- [ find, /var/www, -type, d, -exec, chmod, 2775, {}, \; ]
- [ find, /var/www, -type, f, -exec, chmod, 0664, {}, \; ]
- [ sh, -c, 'echo "" > /var/www/html/phpinfo.php' ]
```
------
#### [ AL2 ]
```
#cloud-config
package_update: true
package_upgrade: all
packages:
- httpd
- mariadb-server
runcmd:
- [ sh, -c, "amazon-linux-extras install -y lamp-mariadb10.2-php7.2 php7.2" ]
- systemctl start httpd
- systemctl enable httpd
- [ sh, -c, "usermod -a -G apache ec2-user" ]
- [ sh, -c, "chown -R ec2-user:apache /var/www" ]
- chmod 2775 /var/www
- [ find, /var/www, -type, d, -exec, chmod, 2775, {}, \; ]
- [ find, /var/www, -type, f, -exec, chmod, 0664, {}, \; ]
- [ sh, -c, 'echo "" > /var/www/html/phpinfo.php' ]
```
------
1. Allow enough time for the instance to launch and run the directives in your user data, and then check to see that your directives have completed the tasks you intended.
For this example, in a web browser, enter the URL of the PHP test file the directives created. This URL is the public DNS address of your instance followed by a forward slash and the file name.
```
http://my.public.dns.amazonaws.com/phpinfo.php
```
You should see the PHP information page. If you are unable to see the PHP information page, check that the security group you are using contains a rule to allow HTTP (port 80) traffic. For more information, see [Configure security group rules](changing-security-group.md#add-remove-security-group-rules).
1. (Optional) If your directives did not accomplish the tasks you were expecting them to, or if you just want to verify that your directives completed without errors, [connect to the instance](connect-to-linux-instance.md), examine the output log file (`/var/log/cloud-init-output.log`), and look for error messages in the output. For additional debugging information, you can add the following line to your directives:
```
output : { all : '| tee -a /var/log/cloud-init-output.log' }
```
This directive sends **runcmd** output to `/var/log/cloud-init-output.log`.
### User data and the AWS CLI
You can use the AWS CLI to specify, modify, and view the user data for your instance. For information about viewing user data from your instance using instance metadata, see [Access instance metadata for an EC2 instance](instancedata-data-retrieval.md).
On Windows, you can use the AWS Tools for Windows PowerShell instead of using the AWS CLI. For more information, see [User data and the Tools for Windows PowerShell](#user-data-powershell) .
**Example: Specify user data at launch**
To specify user data when you launch your instance, use the [run-instances](https://docs.aws.amazon.com/cli/latest/reference/ec2/run-instances.html) command with the `--user-data` parameter. With **run-instances**, the AWS CLI performs base64 encoding of the user data for you.
The following example shows how to specify a script as a string on the command line:
```
aws ec2 run-instances --image-id ami-abcd1234 --count 1 --instance-type m3.medium \
--key-name my-key-pair --subnet-id subnet-abcd1234 --security-group-ids sg-abcd1234 \
--user-data echo user data
```
The following example shows how to specify a script using a text file. Be sure to use the `file://` prefix to specify the file.
```
aws ec2 run-instances --image-id ami-abcd1234 --count 1 --instance-type m3.medium \
--key-name my-key-pair --subnet-id subnet-abcd1234 --security-group-ids sg-abcd1234 \
--user-data file://my_script.txt
```
The following is an example text file with a shell script.
```
#!/bin/bash
yum update -y
service httpd start
chkconfig httpd on
```
**Example: Modify the user data of a stopped instance**
You can modify the user data of a stopped instance using the [modify-instance-attribute](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-attribute.html) command. With **modify-instance-attribute**, the AWS CLI does not perform base64 encoding of the user data for you.
+ On a **Linux** computer, use the base64 command to encode the user data.
```
base64 my_script.txt >my_script_base64.txt
```
+ On a **Windows** computer, use the certutil command to encode the user data. Before you can use this file with the AWS CLI, you must remove the first (BEGIN CERTIFICATE) and last (END CERTIFICATE) lines.
```
certutil -encode my_script.txt my_script_base64.txt
notepad my_script_base64.txt
```
Use the `--attribute` and `--value` parameters to use the encoded text file to specify the user data. Be sure to use the `file://` prefix to specify the file.
```
aws ec2 modify-instance-attribute --instance-id i-1234567890abcdef0 --attribute userData --value file://my_script_base64.txt
```
**Example: Clear the user data of a stopped instance**
To delete the existing user data, use the [modify-instance-attribute](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-attribute.html) command as follows:
```
aws ec2 modify-instance-attribute --instance-id i-1234567890abcdef0 --user-data Value=
```
**Example: View user data**
To retrieve the user data for an instance, use the [describe-instance-attribute](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instance-attribute.html) command. With **describe-instance-attribute**, the AWS CLI does not perform base64 decoding of the user data for you.
```
aws ec2 describe-instance-attribute --instance-id i-1234567890abcdef0 --attribute userData
```
The following is example output with the user data base64 encoded.
```
{
"UserData": {
"Value": "IyEvYmluL2Jhc2gKeXVtIHVwZGF0ZSAteQpzZXJ2aWNlIGh0dHBkIHN0YXJ0CmNoa2NvbmZpZyBodHRwZCBvbg=="
},
"InstanceId": "i-1234567890abcdef0"
}
```
+ On a **Linux** computer , use the `--query` option to get the encoded user data and the base64 command to decode it.
```
aws ec2 describe-instance-attribute --instance-id i-1234567890abcdef0 --attribute userData --output text --query "UserData.Value" | base64 --decode
```
+ On a **Windows** computer, use the `--query` option to get the coded user data and the certutil command to decode it. Note that the encoded output is stored in a file and the decoded output is stored in another file.
```
aws ec2 describe-instance-attribute --instance-id i-1234567890abcdef0 --attribute userData --output text --query "UserData.Value" >my_output.txt
certutil -decode my_output.txt my_output_decoded.txt
type my_output_decoded.txt
```
The following is example output.
```
#!/bin/bash
yum update -y
service httpd start
chkconfig httpd on
```
### Combine shell scripts and cloud-init directives
By default, you can include only one content type in user data at a time. However, you can use the `text/cloud-config` and `text/x-shellscript` content-types in a mime-multi part file to include both a shell script and cloud-init directives in your user data.
The following shows the mime-multi part format.
```
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-init directives
--//
Content-Type: text/x-shellscript; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment; filename="userdata.txt"
#!/bin/bash
shell script commands
--//--
```
For example, the following user data includes cloud-init directives and a bash shell script. The cloud-init directives creates a file (`/test-cloudinit/cloud-init.txt`), and writes `Created by cloud-init` to that file. The bash shell script creates a file (`/test-userscript/userscript.txt`) and writes `Created by bash shell script` to that file.
```
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
runcmd:
- [ mkdir, /test-cloudinit ]
write_files:
- path: /test-cloudinit/cloud-init.txt
content: Created by cloud-init
--//
Content-Type: text/x-shellscript; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment; filename="userdata.txt"
#!/bin/bash
mkdir test-userscript
touch /test-userscript/userscript.txt
echo "Created by bash shell script" >> /test-userscript/userscript.txt
--//--
```
## How Amazon EC2 handles user data for Windows instances
User data for Windows instances
On Windows instances, the launch agent performs the tasks related to user data. For more information, see the following:
+ [EC2Launch v2](ec2launch-v2.md)
+ [EC2Launch](ec2launch.md)
+ [EC2Config service](ec2config-service.md)
For examples of the assembly of a `UserData` property in a CloudFormation template, see [Base64 Encoded UserData Property](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/quickref-general.html#scenario-userdata-base64) and [Base64 Encoded UserData Property with AccessKey and SecretKey](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/quickref-general.html#scenario-userdata-base64-with-keys).
For an example of running commands on an instance within an Auto Scaling group that works with lifecycle hooks, see [Tutorial: Configure user data to retrieve the target lifecycle state through instance metadata](https://docs.aws.amazon.com/autoscaling/ec2/userguide/tutorial-lifecycle-hook-instance-metadata.html) in the *Amazon EC2 Auto Scaling User Guide*.
**Topics**
+ [
### User data scripts
](#user-data-scripts)
+ [
### Compressed user data
](#user-data-compressed)
+ [
### User data execution
](#user-data-execution)
+ [
### User data and the Tools for Windows PowerShell
](#user-data-powershell)
### User data scripts
For `EC2Config` or `EC2Launch` to run scripts, you must enclose the script within a special tag when you add it to user data. The tag that you use depends on whether the commands run in a Command Prompt window (batch commands) or use Windows PowerShell.
If you specify both a batch script and a Windows PowerShell script, the batch script runs first and the Windows PowerShell script runs next, regardless of the order in which they appear in the instance user data.
If you use an AWS API, including the AWS CLI, in a user data script, you must use an instance profile when launching the instance. An instance profile provides the appropriate AWS credentials required by the user data script to make the API call. For more information, see [Instance profiles](iam-roles-for-amazon-ec2.md#ec2-instance-profile). The permissions you assign to the IAM role depend on which services you are calling with the API. For more information, see [IAM roles for Amazon EC2](iam-roles-for-amazon-ec2.md).
**Topics**
+ [
#### Syntax for batch scripts
](#user-data-batch-scripts)
+ [
#### Syntax for Windows PowerShell scripts
](#user-data-powershell-scripts)
+ [
#### Syntax for YAML configuration scripts
](#user-data-yaml-scripts)
+ [
#### Base64 encoding
](#user-data-base64-encoding)
#### Syntax for batch scripts
Specify a batch script using the `script` tag. Separate the commands using line breaks as shown in the following example.
```
```
By default, user data scripts run one time when you launch the instance. To run the user data scripts every time you reboot or start the instance, add `true` to the user data.
```
true
```
**EC2Launch v2 agent**
To run an XML user data script as a detached process with the EC2Launch v2 **executeScript** task in the `UserData` stage, add `true` to the user data.
**Note**
The detach tag is not supported by previous launch agents.
```
true
```
#### Syntax for Windows PowerShell scripts
The AWS Windows AMIs include the [AWS Tools for Windows PowerShell](https://aws.amazon.com/powershell/), so you can specify these cmdlets in user data. If you associate an IAM role with your instance, you don't need to specify credentials to the cmdlets, as applications that run on the instance use the role's credentials to access AWS resources (for example, Amazon S3 buckets).
Specify a Windows PowerShell script using the `` tag. Separate the commands using line breaks. The `` tag is case-sensitive.
For example:
```
$file = $env:SystemRoot + "\Temp\" + (Get-Date).ToString("MM-dd-yy-hh-mm")
New-Item $file -ItemType file
```
By default, the user data scripts run one time when you launch the instance. To run the user data scripts every time you reboot or start the instance, add `true` to the user data.
```
$file = $env:SystemRoot + "\Temp\" + (Get-Date).ToString("MM-dd-yy-hh-mm")
New-Item $file -ItemType file
true
```
You can specify one or more PowerShell arguments with the `` tag. If no arguments are passed, EC2Launch and EC2Launch v2 add the following argument by default: `-ExecutionPolicy Unrestricted`.
**Example:**
```
$file = $env:SystemRoot + "\Temp" + (Get-Date).ToString("MM-dd-yy-hh-mm")
New-Item $file -ItemType file
-ExecutionPolicy Unrestricted -NoProfile -NonInteractive
```
**EC2Launch v2 agent**
To run an XML user data script as a detached process with the EC2Launch v2 **executeScript** task in the `UserData` stage, add `true` to the user data.
**Note**
The detach tag is not supported by previous launch agents.
```
$file = $env:SystemRoot + "\Temp\" + (Get-Date).ToString("MM-dd-yy-hh-mm")
New-Item $file -ItemType file
true
```
#### Syntax for YAML configuration scripts
If you are using EC2Launch v2 to run scripts, you can use the YAML format. To view configuration tasks, details, and examples for EC2Launch v2, see [EC2Launch v2 task configuration](ec2launch-v2-settings.md#ec2launch-v2-task-configuration).
Specify a YAML script with the `executeScript` task.
**Example YAML syntax to run a PowerShell script**
```
version: 1.0
tasks:
- task: executeScript
inputs:
- frequency: always
type: powershell
runAs: localSystem
content: |-
$file = $env:SystemRoot + "\Temp\" + (Get-Date).ToString("MM-dd-yy-hh-mm")
New-Item $file -ItemType file
```
**Example YAML syntax to run a batch script**
```
version: 1.1
tasks:
- task: executeScript
inputs:
- frequency: always
type: batch
runAs: localSystem
content: |-
echo Current date and time >> %SystemRoot%\Temp\test.log
echo %DATE% %TIME% >> %SystemRoot%\Temp\test.log
```
#### Base64 encoding
If you're using the Amazon EC2 API or a tool that does not perform base64 encoding of the user data, you must encode the user data yourself. If not, an error is logged about being unable to find `script` or `powershell` tags to run. The following is an example that encodes using Windows PowerShell.
```
$UserData = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($Script))
```
The following is an example that decodes using PowerShell.
```
$Script = [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String($UserData))
```
For more information about base64 encoding, see [https://www.ietf.org/rfc/rfc4648.txt](https://www.ietf.org/rfc/rfc4648.txt).
### Compressed user data
EC2Launch v2 supports zipped user data as a method to submit user data that's larger than the 16 KB limit imposed by IMDS. To use this feature, compress your user data script into a `.zip` archive and pass it to your EC2 instance. When EC2Launch v2 detects compressed user data, it automatically unzips the compressed user data script and runs it.
As with standard user data, if you're using the Amazon EC2 API or a tool that does not perform base64 encoding of the user data, you must encode the compressed user data yourself. For more information about the user data size limit and base64 encoding, see [Access instance metadata for an EC2 instance](instancedata-data-retrieval.md).
### User data execution
By default, all AWS Windows AMIs have user data execution enabled for the initial launch. You can specify that user data scripts are run the next time the instance reboots or restarts. Alternatively, you can specify that user data scripts are run every time the instance reboots or restarts.
**Note**
User data is not enabled to run by default after the initial launch. To enable user data to run when you reboot or start the instance, see [Run scripts during subsequent reboots or starts](#user-data-scripts-subsequent).
User data scripts are run from the local administrator account when a random password is generated. Otherwise, user data scripts are run from the System account.
#### Instance launch scripts
Scripts in the instance user data are run during the initial launch of the instance. If the `persist` tag is found, user data execution is enabled for subsequent reboots or starts. The log files for EC2Launch v2, EC2Launch, and EC2Config contain the output from the standard output and standard error streams.
**EC2Launch v2**
The log file for EC2Launch v2 is `C:\ProgramData\Amazon\EC2Launch\log\agent.log`.
**Note**
The `C:\ProgramData` folder might be hidden. To view the folder, you must show hidden files and folders.
The following information is logged when the user data is run:
+ `Info: Converting user-data to yaml format` – If the user data was provided in XML format
+ `Info: Initialize user-data state` – The start of user data execution
+ `Info: Frequency is: always` – If the user data task is running on every boot
+ `Info: Frequency is: once` – If the user data task is running just once
+ `Stage: postReadyUserData execution completed` – The end of user data execution
**EC2Launch**
The log file for EC2Launch is `C:\ProgramData\Amazon\EC2-Windows\Launch\Log\UserdataExecution.log`.
The `C:\ProgramData` folder might be hidden. To view the folder, you must show hidden files and folders.
The following information is logged when the user data is run:
+ `Userdata execution begins` – The start of user data execution
+ ` tag was provided: true` – If the persist tag is found
+ `Running userdata on every boot` – If the persist tag is found
+ ` tag was provided.. running powershell content` – If the powershell tag is found
+ `