AWS Snowball Edge is no longer available to new customers. New customers should explore [AWS DataSync](https://aws.amazon.com/datasync/) for online transfers, [AWS Data Transfer Terminal](https://aws.amazon.com/data-transfer-terminal/) for secure physical transfers, or AWS Partner solutions. For edge computing, explore [AWS Outposts](https://aws.amazon.com/outposts/). 

# Using Instance Metadata Service for Snow with Amazon EC2-compatible instances on a Snowball Edge
<a name="imds"></a>

IMDS for Snow provides Instance Metadata Service (IMDS) for Amazon EC2-compatible instances on Snow. Instance metadata is categories of information about instances. It includes categories such as *host name*, *events*, and *security groups*. Using IMDS for Snow, you can use instance metadata to access user data that you specified when launching your Amazon EC2-compatible instance. For example, you can use IMDS for Snow to specify parameters for configuring your instance, or include these parameters in a simple script. You can build generic AMIs and use user data to modify the configuration files supplied at launch time.

To learn about instance metadata and user data and Snow EC2-compatible instances, see [Supported Instance Metadata and User Data](https://docs.aws.amazon.com/snowball/latest/developer-guide/edge-compute-instance-metadata.html) in this guide.

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

**Note**  
The examples in this section use the IPv4 address of the instance metadata service: 169.254.169.254. We do not support the retrieval of instance metadata using the link-local IPv6 address.

**Topics**
+ [IMDS versions on a Snowball Edge](imds-versions.md)
+ [Examples of retrieving instance metadata using IMDSv1 and IMDSv2 on a Snowball Edge](imds-code-examples.md)

# IMDS versions on a Snowball Edge
<a name="imds-versions"></a>

You can access instance metadata from a running instance using IMDS version 2 or IMDS version 1:
+ Instance Metadata Service version 2 (IMDSv2), a session‐oriented method
+ Instance Metadata Service version 1 (IMDSv1), a request‐response method

Depending on the version of your Snow software, you can use IMDSv1, IMDSv2, or both. This also depends on the type of AMI running in the EC2-compatible instance. Some AMIs, such as those running Ubuntu 20.04, require IMDSv2. The instance metadata service distinguishes between IMDSv1 and IMDSv2 requests based on the presence of `PUT` or `GET` headers. IMDSv2 uses both of these headers. IMDSv1 uses only the `GET` header.

AWS encourages the use of IMDSv2 rather than IMDSv1 because IMDSv2 includes higher security. For more information, 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/).

## IMDSv2 on a Snowball Edge
<a name="imdsv2"></a>

When you use IMDSv2 to request instance metadata, the request must follow these rules:

1. Use a `PUT` request to initiate a session to the instance metadata service. The `PUT` request returns a session token that must be included in subsequent `GET` requests to the instance metadata service. The session token that defines the session duration. Session duration can be a minimum of one second and a maximum of six hours. During this duration, you can use the same session token for subsequent requests. After this duration expires, you must create a new session token for future requests. The token is required to access metadata using IMDSv2.

1. Include the token in all `GET` requests to the instance metadata service.

   1. The token is an instance‐specific key. The token is not valid on other EC2-compatible instances and will be rejected if you attempt to use it outside of the instance on which it was generated.

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

   1. After a token expires, to continue accessing instance metadata, you must create a new session using another `PUT` request.

   1. 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 instance metadata service. 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.

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. IMDS for Snow does not have ability to modify the hop limit on `PUT` responses.

The following example uses a Linux shell script and IMDSv2 to retrieve the top‐level instance metadata items. This example:

1. Creates a session token lasting six hours (21,600 seconds) using the `PUT` request.

1. Stores the session token header in a variable named `TOKEN`.

1. Requests the top‐level metadata items using the token.

Use two commands to generate the EC2-compatible token. You can run the commands seperately or as one command.

First, generate a token using the following command.

**Note**  
`X-aws-ec2-metadata-token-ttl-seconds` is a required header. If this header is not included, you will receive an **400 - Missing or Invalid Parameters** error code.

```
    [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" -v http://169.254.169.254/latest/meta-data/
```

**Note**  
If there is an error in creating the token, an error message is stored in the variable instead of a valid token and the command will not work.

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

**Example of combined commands**  

```
    [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" -v http://169.254.169.254/latest/meta-data/
```

After you've created a token, you can reuse it until it expires. The following example command gets the ID of the AMI used to launch the instance and stores it in the `$TOKEN` created in the previous example.

**Example of reusing a token**  

```
    [ec2-user ~]$ curl -H "X-aws-ec2-metadata-token: $TOKEN" -v http://169.254.169.254/latest/meta-data/ami-id                        
```

## IMDSv1 on a Snowball Edge
<a name="imdsv1"></a>

IMDSv1 uses the request‐response model. To request instance metadata, you send a `GET` request to the instance metadata service.

```
    [ec2-user ~]$ curl http://169.254.169.254/latest/meta-data/                   
```

Your instance metadata is available from your running instance, so you do not need to use Amazon EC2 console or the AWS CLI to access it. 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. Instance metadata is divided into categories. For a description of each instance metadata category, see [Supported Instance Metadata and User Data](https://docs.aws.amazon.com/snowball/latest/developer-guide/edge-compute-instance-metadata.html) in this guide. 

To view all categories of instance metadata from within a running instance, use the following IPv4 URI:

```
    http://169.254.169.254/latest/meta-data/
```

The IP addresses are link-local addresses and are valid only from the instance. For more information, see [Link-local address](https://en.wikipedia.org/wiki/Link-local_address) on Wikipedia.

All instance metadata is returned as text (HTTP content type `text/plain`).

A request for a specific metadata resource returns the appropriate value, or an **404 - Not Found** HTTP error code, if the resource is not available.

A request for a general metadata resource (when the URI ends with a `/` character) returns a list of available resources, or an **404 - Not Found** HTTP error code if there is no such resource. The list items are on separate lines, terminated by line feeds (ASCII character code 10).

For requests made using IMDSv1, 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 instance metadata service is turned off.

# Examples of retrieving instance metadata using IMDSv1 and IMDSv2 on a Snowball Edge
<a name="imds-code-examples"></a>

The following examples provide commands that you can use on a Linux instance.

**Example of getting 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 earlier versions are available to you in case you have scripts that rely on the structure and information present in a previous version.  
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" -v http://169.254.169.254/
    % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current  Dload  Upload   Total   Spent    Left  Speed
    100        56         100      56      0       0       3733     0    --:--:-- --:--:-- --:--:--  3733
    *   Trying 169.254.169.254...
    * TCP_NODELAY set
    * Connected to 169.254.169.254 (169.254.169.254) port 80 (#0)
    > GET / HTTP/1.1
    > Host: 169.254.169.254
    > User-Agent: curl/7.61.1
    > Accept: */*
    > X-aws-ec2-metadata-token: MDAXcxNFLbAwJIYx8KzgNckcHTdxT4Tt69TzpKExlXKTULHIQnjEtXvD
    >
    * HTTP 1.0, assume close after body
    < HTTP/1.0 200 OK
    < Date: Mon, 12 Sep 2022 21:58:03 GMT
    < Content-Length: 274
    < Content-Type: text/plain
    < Server: EC2ws
    <
    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
    2016-06-30
    2016-09-02
    2018-03-28
    2018-08-17
    2018-09-24
    2019-10-01
    2020-10-27
    2021-01-03
    2021-03-23
    * Closing connection 0
```
IMDSv1  

```
    [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
    2016-06-30
    2016-09-02
    2018-03-28
    2018-08-17
    2018-09-24
    2019-10-01
    2020-10-27
    2021-01-03
    2021-03-23
    latest
```

**Example of getting the top‐level metadata items**  
This example gets the top‐level metadata items. For information on top‐level metadata items, see [Supported Instance Metadata and User Data](https://docs.aws.amazon.com/snowball/latest/developer-guide/edge-compute-instance-metadata.html) in this guide.  
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" -v http://169.254.169.254/latest/meta-data/ 
    ami-id
    hostname
    instance-id
    instance-type
    local-hostname
    local-ipv4
    mac
    network/
    reservation-id
    security-groups
```
IMDSv1  

```
    [ec2-user ~]$ curl http://169.254.169.254/latest/meta-data/ 
    ami-id
    hostname
    instance-id
    instance-type
    local-hostname
    local-ipv4
    mac
    network/
    reservation-id
    security-groups
```

**Example of getting values of top‐level metadata**  
The following examples get the values of some of the top‐level metadata items that were obtained in the preceding example. The IMDSv2 requests use the stored token that was created in the preceding example command, assuming it has not expired.  
`ami‐id` IMDSv2  

```
    curl -H "X-aws-ec2-metadata-token: $TOKEN" -v http://169.254.169.254/latest/meta-data/ami-id ami-0abcdef1234567890                    
```
`ami-id` IMDSv1  

```
    curl http://169.254.169.254/latest/meta-data/ami-id ami-0abcdef1234567890                    
```
`reservation-id` IMDSv2  

```
    [ec2-user ~]$ curl -H "X-aws-ec2-metadata-token: $TOKEN" -v http://169.254.169.254/latest/meta-data/reservation-id r-0efghijk987654321
```
`reservation-id` IMDSv1  

```
    [ec2-user ~]$ curl http://169.254.169.254/latest/meta-data/reservation-id \
    r-0efghijk987654321
```
`local-hostname` IMDSv2  

```
    [ec2-user ~]$ curl -H "X-aws-ec2-metadata-token: $TOKEN" -v http://169.254.169.254/latest/meta-data/local-hostname ip-00-000-00-00                    
```
`local-hostname` IMDSv1  

```
    [ec2-user ~]$ curl http://169.254.169.254/latest/meta-data/local-hostname ip-00-000-00-00
```