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, go to 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 the ec2-register-image action to create an EBS-backed AMI from a snapshot of a root device volume. For more information, go to 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 S3 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.

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

Name Description Required

manifest

Full path to your AMI manifest in Amazon S3 storage.

Type: String

Default: None

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

Example: mybucket/image.manifest.xml

Conditional

-n, --name name

A name for your AMI.

Type: String

Default: None

Constraints: 3-128 alphanumeric characters, parenthesis (()), commas (,), slashes (/), dashes (-), or underscores(_)

Example: -n "Standard Web Server"

Yes

-d, --description description

The description of the AMI.

Type: String

Default: None

Constraints: Up to 255 characters.

Example: -d "Standard Web Server AMI"

No

-a, --architecture architecture

The architecture of the image.

Type: String

Valid Values: i386 | x86_64

Default: None

Example: -a i386

No

--kernel

The ID of the kernel associated with the image.

Type: String

Default: None

Example: --kernel aki-ba3adfd3

No

--ramdisk

The ID of the RAM disk to associate with the image. Some kernels require additional drivers at launch. Check the kernel requirements for information on whether you need to specify a RAM disk. To find kernel requirements, refer to the Resource Center and search for the kernel ID.

Type: String

Default: None

Example: --ramdisk ari-badbad00

No

--root-device-name name

The root device name (e.g., /dev/sda1, or xvda).

Type: String

Default: /dev/sda1

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

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

No

-b, --block-device-mapping mapping

Defines a block device mapping for the instance. This argument is passed in the form of <devicename>=<blockdevice>. The devicename is the device name of the physical device on the instance to map. The blockdevice can be one of the following values:

none - specifies that the existing mapping on the specified image for this device should be suppressed. For example: /dev/sdc=none
ephemeral[0..3] - indicates that an instance local storage device should be mapped to this device. Example: /dev/sdc=ephemeral0
[snapshot-id]:[size]:[delete-on-termination (true|false)] - this value can be used to map a device to an existing EBS-backed volume by specifying an existing volume name. You can specify a new EBS-backed volume by skipping the snapshot ID and passing in a volume size instead; for example: /dev/sdb=:20. You can also specify whether the Amazon EBS volume should be deleted on termination; this value is true by default.

	Note
	The `devicemapping` argument must be surrounded by double quotes on Windows systems.

You may specify multiple blockdevicemapping arguments in one call.

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

Type: String

Default: None

Condition: If registering an Amazon EBS-backed AMI from a snapshot, you must at least specify this parameter with the root device name (e.g., /dev/sda1, or xvda), and the snapshot ID.

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

Conditional

-s, --snapshot snapshot

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

Type: String

Default: None

Example: -s snap-78a54011

No

Common Options

Option	Description
`--region` `REGION`	Overrides the Region specified in the `EC2_URL` environment variable and the URL specified by the `-U` option. Default: The `EC2_URL` environment variable, or `us-east-1` if the environment variable is not set. Example: `--region eu-west-1`
`-U, --url` `URL`	`URL` is the uniform resource locator of the Amazon EC2 web service entry point. Default: The `EC2_URL` environment variable, or https://ec2.amazonaws.com if the environment variable is not set. Example: `-U https://ec2.amazonaws.com`
`-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-HKZYKTAIG2ECMXYIBH3HXV4ZBZQ55CLO.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-HKZYKTAIG2ECMXYIBH3HXV4ZBZQ55CLO.pem`
`--connection-timeout` `TIMEOUT`	Specifies a connection timeout (in seconds). Example: --connection-timeout 30
`--request-timeout` `TIMEOUT`	Specifies a request timeout (in seconds). Example: --request-timeout 45
`-v, --verbose`	Displays verbose output by showing the SOAP request and response on the command line. This is particularly useful if you are building tools to talk directly to our SOAP API.
`-H, --headers`	Displays column headers in the output.
`--show-empty-fields`	Shows empty columns as `(nil)`.
`--hide-tags`	Do not display tags for tagged resources.
`--debug`	Prints internal debugging information. This is useful to assist us when troubleshooting problems.
`-?, --help, -h`	Displays Help.
`-`	If `-` is specified as an argument to one of the parameters, a list of arguments is read from standard input. This is useful for piping the output of one command into the input of another. Example: `ec2-describe-instances \| grep stopped \| cut -f 2 \| ec2-start-instances -`

Output

The command returns a table that contains the following information:

IMAGE identifier
Unique 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 mybucket.

PROMPT> ec2-register mybucket/image.manifest.xml -n MyImage
IMAGE ami-78a54011

Example Request

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

PROMPT> ec2-register -n MyImage -s snap-65e34ab22
IMAGE ami-78a54023

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-6e3ad879 -b /dev/sdb=snap-823ea6df -b /dev/sdc=:100
IMAGE ami-78a54043

Description

Syntax

Options

Common Options

Output

Examples

Example Request

Example Request

Example Request

Related Operations