Menu
Amazon Elastic Compute Cloud
CLI Reference (API Version 2015-10-01)

ec2-register

Description

Registers an AMI. When you're creating an AMI, this is the final step you must complete before you can launch an instance from the AMI. For more information, see Creating Your Own AMIs in the Amazon EC2 User Guide for Linux Instances.

Note

The ec2-create-image command creates and registers the AMI in a single request, so you don't have to register the AMI yourself.

You can also use ec2-register to create an Amazon EBS-backed Linux AMI from a snapshot of a root device volume. For more information, see Launching an Instance from a Snapshot in the Amazon EC2 User Guide for Linux Instances.

Important

Some Linux distributions, such as Red Hat Enterprise Linux (RHEL) and SUSE Linux Enterprise Server (SLES), use the EC2 billingProduct code associated with an AMI to verify subscription status for package updates. Creating an AMI from an EBS snapshot does not maintain this billing code, and subsequent instances launched from such an AMI will not be able to connect to package update infrastructure.

Similarly, although you can create a Windows AMI from a snapshot, you can't successfully launch an instance from the AMI.

To create Windows AMIs or to create AMIs for Linux operating systems that must retain AMI billing codes to work properly, see ec2-create-image.

If needed, you can deregister an AMI at any time. Any modifications you make to an AMI backed by instance storage invalidates its registration. If you make changes to an image, deregister the previous image and register the new image.

Note

You can't register an image if a secondary (non-root) snapshot has AWS Marketplace product codes.

The short version of this command is ec2reg.

Tip

If you are using the AWS CLI, see register-image instead.

Syntax

ec2-register { [manifest] -n name [-d description] [-a architecture] [-s snapshot_id] [--root-device-name name] [-b mapping [...]] [--kernel kernel_id] [--ramdisk ramdisk_id] [--virtualization-type virtualization_type] [--sriov sriov]}

Options

NameDescription

manifest

The full path to your AMI manifest in Amazon S3 storage.

Type: String

Default: None

Required: Conditional

Condition: Required if registering an instance store-backed AMI.

Example: myawsbucket/image.manifest.xml

-n, --name name

A name for your AMI.

Type: String

Default: None

Constraints: 3-128 alphanumeric characters, parentheses (()), square brackets ([]), periods (.), slashes (/), dashes (-), single quotes ('), at-signs (@), or underscores(_). Allows spaces if the name is enclosed in quotation marks.

Required: Yes

Example: -n "Standard Web Server"

-d, --description description

A description for your AMI.

Type: String

Default: None

Constraints: Up to 255 characters.

Required: No

Example: -d "Standard Web Server AMI"

-a, --architecture architecture

The architecture of the AMI.

Type: String

Valid values: i386 | x86_64

Default: None

Required: No

Example: -a i386

-s, --snapshot snapshot

The ID of the Amazon EBS snapshot to be used as the root device.

Type: String

Default: None

Required: No

Example: -s snap-78a54011

--root-device-name name

The name of the root device (for example, /dev/sda1 or xvda).

Type: String

Default: /dev/sda1

Required: No

Example: --root-device-name /dev/sda1

-b, --block-device-mapping mapping

An entry for the block device mapping for the instance. You can specify multiple --block-device-mapping options in one call. For more information, see Block Device Mapping in the Amazon EC2 User Guide for Linux Instances.

Each entry is passed in the form <devicename>=<blockdevice>. The devicename is the device name of the physical device on the instance to map, and blockdevice can be one of the following values:

  • none – Suppresses an existing mapping of the device from the AMI used to launch the instance. For example: "/dev/sdc=none".

  • ephemeraln – An instance store volume to be mapped to the device. Instance store volumes are numbered starting from 0. An instance type with 2 available instance store volumes can specify mappings for ephemeral0 and ephemeral1. For example: "/dev/sdc=ephemeral0".

  • [snapshot-id]:[volume-size]:[delete-on-termination]:[volume-type[:iops]]:[encrypted] – An Amazon EBS volume to map to the device.

    [snapshot-id]

    To create a volume from a snapshot, specify the snapshot ID.

    [volume-size]

    To create an empty Amazon EBS volume, omit the snapshot ID and specify a volume size instead. For example: "/dev/sdh=:20".

    [delete-on-termination]

    To prevent deletion on instance termination, specify false. The default for the root volume is true and the default for other volumes is false. For more information, see Preserving Amazon EBS Volumes on Instance Termination in the Amazon EC2 User Guide for Linux Instances.

    [volume-type]

    The default volume type is standard. To create a General Purpose SSD volume, specify gp2. To create a Provisioned IOPS SSD volume, specify io1. If the volume type is io1, you must also specify the number of IOPS that the volume should support. For more information, see Amazon EBS Volume Types in the Amazon EC2 User Guide for Linux Instances.

    [iops]

    The number of provisioned IOPS that the volume supports (this option is only valid with io1 volume types).

    [encrypted]

    To encrypt the volume, specify true. Volumes created from encrypted snapshots are automatically encrypted. An encrypted Amazon EBS volume must be attached to an instance that supports Amazon EBS encryption. If your AMI uses an encrypted volume, you must launch it using a supported instance type. For more information, see Amazon EBS Encryption in the Amazon EC2 User Guide for Linux Instances.

Type: String

Default: None

Required: No

Example: -b "/dev/sdc=snap-7eb96d16:100:false:io1:500"

Note

On Windows, the mapping argument must be enclosed in double quotes, as shown in the example.

Note

For M3 instances, you must specify instance store volumes in the block device mapping for the instance. When you launch an M3 instance, we ignore any instance store volumes specified in the block device mapping for the AMI.

--kernel kernel_id

The ID of the kernel associated with the image.

Important

We recommend that you use PV-GRUB instead of kernels and RAM disks. For more information, see PV-GRUB in the Amazon EC2 User Guide for Linux Instances.

Type: String

Default: None

Required: No

Example: --kernel aki-ba3adfd3

--ramdisk ramdisk_id

The ID of the RAM disk to associate with the image.

Important

We recommend that you use PV-GRUB instead of kernels and RAM disks. For more information, see PV-GRUB in the Amazon EC2 User Guide for Linux Instances.

Type: String

Default: None

Required: No

Example: --ramdisk ari-badbad00

--virtualization-type virtualization_type

The type of virtualization for the AMI you are registering. This option is required to register HVM images; see the example below.

Type: String

Valid values: paravirtual | hvm

Default: paravirtual

Required: No

Example: --virtualization-type hvm

--sriov sriov

Set to simple to enable enhanced networking for the AMI and any instances that you launch from the AMI. There is no way to disable enhanced networking at this time. For more information, see Enabling Enhanced Networking on Linux Instances in the Amazon EC2 User Guide for Linux Instances or Enabling Enhanced Networking on Windows Instances in the Amazon EC2 User Guide for Microsoft Windows Instances.

Warning

This option is supported only for HVM AMIs. Specifying this option with a PV AMI can make instances launched from the AMI unreachable.

Type: String

Valid values: simple

Default: None

Required: No

Example: --sriov simple

Common Options

OptionDescription

--region region

The region. Overrides the default region, the region specified by the EC2_URL environment variable, and the URL specified by the -U option.

Default: The region specified by the EC2_URL environment variable, or us-east-1 if EC2_URL isn't set.

-U, --url url

The uniform resource locator (URL) of the Amazon EC2 web service entry point.

Default: The endpoint specified by the EC2_URL environment variable, or https://ec2.amazonaws.com if EC2_URL isn't set.

-O, --aws-access-key aws_access_key_id

Your access key ID. For more information, see Tell the Tools Who You Are.

Default: The value of the AWS_ACCESS_KEY environment variable. If AWS_ACCESS_KEY isn't set, you must specify this option.

Example: -O AKIAIOSFODNN7EXAMPLE

-W, --aws-secret-key aws_secret_access_key

Your secret access key.

Default: The value of the AWS_SECRET_KEY environment variable. If AWS_SECRET_KEY isn't set, you must specify this option.

Example: -W wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

-T, --security-token delegation_token

The delegation token to pass along to the AWS request. This is only required when you are using temporary security credentials. For more information, see Using Temporary Security Credentials.

Default: The value of the AWS_DELEGATION_TOKEN environment variable (if set).

Example: -T AQoDYXdzEJr...<remainder of security token>

--connection-timeout timeout

The connection timeout, in seconds.

Example: --connection-timeout 30

--request-timeout timeout

The request timeout, in seconds.

Example: --request-timeout 45

-H, --headers

Includes column headers in the command output.

--show-empty-fields

Shows empty columns as (nil).

--hide-tags

Omits tags for tagged resources.

--debug

Displays internal debugging information. This can assist us when helping you troubleshooting problems.

-D, --auth-dry-run

Checks whether you have the required permissions for the command, without actually running the command. If you have the required permissions, the command returns DryRunOperation; otherwise, it returns UnauthorizedOperation.

-v, --verbose

Displays verbose output, including the API request and response on the command line. This is useful if you are building tools to talk directly to the Query API.

-

Reads arguments from standard input. This is useful when piping the output from one command to the input of another.

Example: ec2-describe-instances | grep stopped | cut -f 2 | ec2-start-instances -

-?, --help, -h

Displays usage information for the command.

Deprecated Options

We have deprecated the SOAP API for Amazon EC2. For more information, see SOAP Requests. From version 1.6.14.0 onwards of the Amazon EC2 CLI tools, the private key (-K, --private-key) and X.509 certificate (-C, --cert) options are not supported. Use your access key ID (-O, --aws-access-key) and secret access key (-W, --aws-secret-key) instead. For more information, see Setting Up the Amazon EC2 CLI and AMI Tools.

OptionDescription

-K, --private-key ec2_private_key

The private key to use when constructing requests to Amazon EC2.

Default: The value of the EC2_PRIVATE_KEY environment variable.

Example: -K pk-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem

-C, --cert ec2_cert

The X.509 certificate to use when constructing requests to Amazon EC2.

Default: The value of the EC2_CERT environment variable.

Example: -C cert-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem

Output

This command returns a table that contains the following information:

  • The IMAGE identifier

  • The ID of the newly registered machine image

Amazon EC2 command line tools display errors on stderr.

Examples

Example 1

This example command registers an AMI using the specified image.manifest.xml manifest file, located in the bucket named myawsbucket.

PROMPT> ec2-register myawsbucket/image.manifest.xml -n MyImage
IMAGE	ami-1a2b3c4d

Example 2

When you register an Amazon EBS-backed AMI from a snapshot, at a minimum you must specify a snapshot or a block device mapping for the root device. This example command specifies a snapshot for the root device. By default, the root device is /dev/sda1.

PROMPT> ec2-register -n MyImage -s snap-1a2b3c4d
IMAGE	ami-1a2b3c4d

Example 3

This example command registers an AMI with a block device mapping for three Amazon EBS volumes. The first volume is the root device volume based on an Amazon EBS snapshot. The second volume is a volume based on another snapshot. The third volume is an empty 100 GiB volume.

PROMPT> ec2-register -n MyImage -b "/dev/sda1=snap-1a2b3c4d" -b "/dev/sdb=snap-2a3b4c5d" -b "/dev/sdc=:100"
IMAGE	ami-1a2b3c4d

Example 4

This example command registers an AMI with two volumes. The first volume is the root volume based on an Amazon EBS snapshot. The DeleteOnTermination flag of the root volume is set to false. The second volume is an instance store volume, ephemeral0.

PROMPT> ec2-register -n MyImage -b "/dev/sda1=snap-1a2b3c4d:80:false" -b "/dev/sdc=ephemeral0"
IMAGE	ami-1a2b3c4d

Related Topics

Setting Up

IAM Policies

You can create an IAM policy to grant users permission to use this command. For more information, see IAM Policies for Amazon EC2 in the Amazon EC2 User Guide for Linux Instances.

Related Action