Amazon Elastic Compute Cloud
CLI Reference (API Version 2013-02-01)
AWS Documentation » Amazon EC2 » Command Line Reference » Commands (CLI Tools) » ec2-register
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Did this page help you?  Yes | No |  Tell us about it...

ec2-register

Description

Registers a new AMI with Amazon EC2. 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 about creating AMIs, see Creating Your Own AMIs in the Amazon Elastic Compute Cloud User Guide.

Note

For Amazon EBS-backed instances, 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 AMI from a snapshot of a root device volume. For more information, see Launching an Instance from a Snapshot in the Amazon Elastic Compute Cloud User Guide.

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

The short version of this command is ec2reg.

Note

You cannot register an image where a secondary (non-root) snapshot has AWS Marketplace product codes.

Syntax

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

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, parenthesis (()), commas (,), slashes (/), dashes (-), or underscores(_)

Required: Yes

Example: -n "Standard Web Server"

-d, --description description

The description of the 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 image.

Type: String

Valid values: i386 | x86_64

Default: None

Required: No

Example: -a i386

--kernel

The ID of the kernel associated with the image.

Type: String

Default: None

Required: No

Example: --kernel aki-ba3adfd3

--ramdisk

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

Note

It is recommended that PV-GRUB be used instead of kernels and RAM disks. For more information, go to PV-GRUB: A New Amazon Kernel Image in the Amazon Elastic Compute Cloud User Guide.

Type: String

Default: None

Required: No

Example: --ramdisk ari-badbad00

--root-device-name name

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

Type: String

Default: /dev/sda1

Condition: Required if registering an Amazon EBS-backed AMI.

Required: No

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

-b, --block-device-mapping mapping

The block device mapping for the instance. This argument is passed in the form of <devicename>=<blockdevice>. The devicename is the name of the device within Amazon EC2. The 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".

  • ephemeral[0..3] - An instance store volume to be mapped to the device. For example: "/dev/sdc=ephemeral0".

  • [snapshot-id]:[volume-size]:[true|false]:[standard|io1[:iops]] - An EBS volume to be mapped to the device. [snapshot-id] To create a volume from a snapshot, specify the snapshot ID. [volume-size] To create an empty EBS volume, omit the snapshot ID and specify a volume size instead. For example: "/dev/sdh=:20". [delete-on-termination] To prevent the volume from being deleted on termination of the instance, specify false. The default is true. [volume-type] To create a Provisioned IOPS volume, specify io1. The default volume type is standard. If the volume type is io1, you can also provision the number of IOPS that the volume supports. For example, "/dev/sdh=snap-7eb96d16::false:io1:500".

You can specify multiple block-device-mapping arguments in one call.

For more detailed information about block device mapping, see Block Device Mapping in the Amazon Elastic Compute Cloud User Guide.

Type: String

Default: None

Required: Conditional

Condition: If registering an Amazon EBS-backed AMI from a snapshot, at a minimum you must specify a block device mapping entry for the root device. Be sure to include the device name (/dev/sda1 or xvda) and the snapshot ID.

Example: -b "/dev/sda1=snap-7eb96d16"

Note

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

-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

Common Options

OptionDescription

--region REGION

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

Default: The value of the EC2_URL environment variable, or us-east-1 if EC2_URL isn't set.

Example: --region eu-west-1

-U, --url URL

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

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

Example: -U https://ec2.amazonaws.com

-K, --private-key EC2-PRIVATE-KEY

The private key that identifies you to Amazon EC2. For more information, see Tell the Tools Who You Are.

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

Example: -K pk-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem

-C, --cert EC2-CERT

The X.509 certificate that identifies you to Amazon EC2.

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

Example: -C cert-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem

-O, --aws-access-key AWS_ACCESS_KEY

The access key ID associated with your AWS account. 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

Note

For more information, see the following section, Deprecated Options.

-W, --aws-secret-key AWS_SECRET_KEY

The secret access key associated with your AWS account.

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

Note

For more information, see the following section, Deprecated Options.

-T, --security-token TOKEN AWS_DELEGATION_TOKEN

The AWS delegation token.

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

--connection-timeout TIMEOUT

The connection timeout, in seconds.

Example: --connection-timeout 30

--request-timeout TIMEOUT

The request timeout, in seconds.

Example: --request-timeout 45

-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 our Query API.

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

-?, --help, -h

Displays usage information for the command.

-

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 -

Deprecated Options

For a limited time, you can still use the private key and X.509 certificate instead of your access key ID and secret access key. However, we recommend that you start using your access key ID (-O, --aws-access-key) and secret access key (-W, --aws-secret-key) now, as the private key (-K, --private-key) and X.509 certificate (-C, --cert) won't be supported after the transition period elapses. For more information, see Tell the Tools Who You Are.

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 Request

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

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

Example Request

This example registers an Amazon EBS snapshot to create an AMI backed by Amazon EBS.

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

Example Request

This example registers the AMI with an Amazon EBS snapshot as the root device, a separate snapshot as a secondary device, and an empty 100 GiB Amazon EBS volume as a storage device.

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

Related Topics

Download

Related Action

Document Conventions« PreviousNext »
Terms of UseDid this page help you?  Yes | No |  Tell us about it...