Menu
Amazon Elastic Compute Cloud
User Guide for Linux Instances

Setting Up the AMI Tools

You can use the AMI tools to create and manage instance store-backed Linux AMIs. To use the tools, you must install them on your Linux instance. The AMI tools are available as both an RPM and as a .zip file for Linux distributions that don't support RPM. For more information, see Amazon EC2 AMI Tools.

Note

The AMI tools are supported on instance store-backed Linux instances only. To create an Amazon EBS-backed AMI, use the create-image AWS CLI command instead. To create an instance store-backed Windows AMI, see Creating an Instance Store-Backed Windows AMI.

To set up the AMI tools using the RPM

  1. Install Ruby using the package manager for your Linux distribution, such as yum. For example:

    Copy to clipboard
    $ sudo yum install -y ruby
  2. Download the RPM file using a tool such as wget or curl. For example:

    Copy to clipboard
    $ sudo wget http://s3.amazonaws.com/ec2-downloads/ec2-ami-tools.noarch.rpm
  3. Install the RPM using the following command.

    Copy to clipboard
    $ sudo yum install ec2-ami-tools.noarch.rpm
  4. Verify your AMI tools installation with the following command.

    Copy to clipboard
    $ ec2-ami-tools-version

    Note

    If you receive a load error such as cannot load such file -- ec2/amitools/version (LoadError), complete the next step to add the location of your AMI tools installation to your RUBYLIB path.

  5. (Optional) If you received an error in the previous step, add the location of your AMI tools installation to your RUBYLIB path.

    1. Run the following command to determine the paths to add.

      Copy to clipboard
      $ rpm -qil ec2-ami-tools | grep ec2/amitools/version /usr/lib/ruby/site_ruby/ec2/amitools/version.rb /usr/lib64/ruby/site_ruby/ec2/amitools/version.rb
      In the above example, the missing file from the previous load error is located at /usr/lib/ruby/site_ruby and /usr/lib64/ruby/site_ruby.

    2. Add the locations from the previous step to your RUBYLIB path.

      Copy to clipboard
      $ export RUBYLIB=$RUBYLIB:/usr/lib/ruby/site_ruby:/usr/lib64/ruby/site_ruby

    3. Verify your AMI tools installation with the following command.

      Copy to clipboard
      $ ec2-ami-tools-version

To set up the AMI tools using the .zip file

  1. Install Ruby and unzip using the package manager for your Linux distribution, such as apt-get. For example:

    Copy to clipboard
    $ sudo apt-get update -y && sudo apt-get install -y ruby unzip
  2. Download the .zip file using a tool such as wget or curl. For example:

    Copy to clipboard
    $ wget http://s3.amazonaws.com/ec2-downloads/ec2-ami-tools.zip
  3. Unzip the files into a suitable installation directory, such as /usr/local/ec2.

    Copy to clipboard
    $ sudo mkdir -p /usr/local/ec2 $ sudo unzip ec2-ami-tools.zip -d /usr/local/ec2

    Notice that the .zip file contains a folder ec2-ami-tools-x.x.x, where x.x.x is the version number of the tools (for example, ec2-ami-tools-1.5.7).

  4. Set the EC2_AMITOOL_HOME environment variable to the installation directory for the tools. For example:

    Copy to clipboard
    $ export EC2_AMITOOL_HOME=/usr/local/ec2/ec2-ami-tools-x.x.x
  5. Add the tools to your PATH environment variable. For example:

    Copy to clipboard
    $ export PATH=$EC2_AMITOOL_HOME/bin:$PATH
  6. You can verify your AMI tools installation with the following command.

    Copy to clipboard
    $ ec2-ami-tools-version

AMI Tool Commands

You can use the following commands with the AMI tools to create and manage instance store-backed Linux AMIs. To set up the tools, see Setting Up the AMI Tools.

ec2-ami-tools-version

Description

Describes the version of the AMI tools.

Syntax

ec2-ami-tools-version

Options

This command has no parameters.

Output

The version information.

Example

This example command displays the version information for the AMI tools that you're using.

Copy to clipboard
$ ec2-ami-tools-version 1.5.2 20071010

ec2-bundle-image

Description

Creates an instance store-backed Linux AMI from an operating system image created in a loopback file.

Syntax

ec2-bundle-image -c path -k path -u account -i path [-d path] [--ec2cert path] [-r architecture] [--productcodes code1,code2,...] [-B mapping] [-p prefix]

Options

Option Description

-c, --cert path

The user's PEM encoded RSA public key certificate file.

Required: Yes

Example: -c cert-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem

-k, --privatekey path

The path to a PEM-encoded RSA key file. You'll need to specify this key to unbundle this bundle, so keep it in a safe place. Note that the key doesn't have to be registered to your AWS account.

Required: Yes

Example: -k pk-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem

-u, --user account

The user's AWS account ID without dashes.

Required: Yes

Example: -u 111122223333

-i, --image path

The path to the image to bundle.

Required: Yes

Example: -i /var/spool/my-image/version-2/debian.img

-d, --destination path

The directory in which to create the bundle.

Default: /tmp

Required: No

Example: -d /media/ephemeral0

--ec2cert path

The path to the Amazon EC2 X.509 public key certificate used to encrypt the image manifest.

The us-gov-west-1 and cn-north-1 regions use a non-default public key certificate and the path to that certificate must be specified with this option. The path to the certificate varies based on the installation method of the AMI tools. For Amazon Linux, the certificates are located at /opt/aws/amitools/ec2/etc/ec2/amitools/. If you installed the AMI tools from the RPM or ZIP file in Setting Up the AMI Tools, the certificates are located at $EC2_AMITOOL_HOME/etc/ec2/amitools/.

Default: varies, depending on the tools

Required: Only for the us-gov-west-1 and cn-north-1 regions.

Example: --ec2cert $EC2_AMITOOL_HOME/etc/ec2/amitools/cert-ec2.pem

-r, --arch architecture

Image architecture. If you don't provide the architecture on the command line, you'll be prompted for it when bundling starts.

Valid values: i386 | x86_64

Required: No

Example: -r x86_64

--productcodes code1,code2,...

Product codes to attach to the image at registration time, separated by commas.

Required: No

Example: --productcodes 1234abcd

-B, --block-device-mapping mapping

Defines how block devices are exposed to an instance of this AMI if its instance type supports the specified device.

Specify a comma-separated list of key-value pairs, where each key is a virtual name and each value is the corresponding device name. Virtual names include the following:

  • ami—The root file system device, as seen by the instance

  • root—The root file system device, as seen by the kernel

  • swap—The swap device, as seen by the instance

  • ephemeralN—The Nth instance store volume

Required: No

Example: --block-device-mapping ami=sda1,root=/dev/sda1,ephemeral0=sda2,swap=sda3

Example: --block-device-mapping ami=0,root=/dev/dsk/c0d0s0,ephemeral0=1

-p, --prefix prefix

The filename prefix for bundled AMI files.

Default: The name of the image file. For example, if the image path is /var/spool/my-image/version-2/debian.img, then the default prefix is debian.img.

Required: No

Example: -p my-image-is-special

--kernel kernel_id

Deprecated. Use register-image to set the kernel.

Required: No

Example: --kernel aki-ba3adfd3

--ramdisk ramdisk_id

Deprecated. Use register-image to set the RAM disk if required.

Required: No

Example: --ramdisk ari-badbad00

Common options

For options common to most of the AMI Tools, see Common Options for AMI Tools.

Output

Status messages describing the stages and status of the bundling process.

Example

This example creates a bundled AMI from an operating system image that was created in a loopback file.

Copy to clipboard
$ ec2-bundle-image -k pk-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem -c cert-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem -u 111122223333 -i image.img -d bundled/ -r x86_64 Please specify a value for arch [i386]: Bundling image file... Splitting bundled/image.gz.crypt... Created image.part.00 Created image.part.01 Created image.part.02 Created image.part.03 Created image.part.04 Created image.part.05 Created image.part.06 Created image.part.07 Created image.part.08 Created image.part.09 Created image.part.10 Created image.part.11 Created image.part.12 Created image.part.13 Created image.part.14 Generating digests for each part... Digests generated. Creating bundle manifest... ec2-bundle-image complete.

ec2-bundle-vol

Description

Creates an instance store-backed Linux AMI by compressing, encrypting, and signing a copy of the root device volume for the instance.

Amazon EC2 attempts to inherit product codes, kernel settings, RAM disk settings, and block device mappings from the instance.

By default, the bundle process excludes files that might contain sensitive information. These files include *.sw, *.swo, *.swp, *.pem, *.priv, *id_rsa*, *id_dsa* *.gpg, *.jks, */.ssh/authorized_keys, and */.bash_history. To include all of these files, use the --no-filter option. To include some of these files, use the --include option.

For more information, see Creating an Instance Store-Backed Linux AMI.

Syntax

ec2-bundle-vol -c path -k path -u account [-d path] [--ec2cert path] [-r architecture] [--productcodes code1,code2,...] [-B mapping] [--all] [-e directory1,directory2,...] [-i file1,file2,...] [--no-filter] [-p prefix] [-s size] [--[no-]inherit] [-v volume] [-P type] [-S script] [--fstab path] [--generate-fstab] [--grub-config path]

Options

Option Description

-c, --cert path

The user's PEM encoded RSA public key certificate file.

Required: Yes

Example: -c cert-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem

-k, --privatekey path

The path to the user's PEM-encoded RSA key file.

Required: Yes

Example: -k pk-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem

-u, --user account

The user's AWS account ID without dashes.

Required: Yes

Example: -u 111122223333

-d, --destination destination

The directory in which to create the bundle.

Default: /tmp

Required: No

Example: -d /var/run/my-bundle

--ec2cert path

The path to the Amazon EC2 X.509 public key certificate used to encrypt the image manifest.

The us-gov-west-1 and cn-north-1 regions use a non-default public key certificate and the path to that certificate must be specified with this option. The path to the certificate varies based on the installation method of the AMI tools. For Amazon Linux, the certificates are located at /opt/aws/amitools/ec2/etc/ec2/amitools/. If you installed the AMI tools from the RPM or ZIP file in Setting Up the AMI Tools, the certificates are located at $EC2_AMITOOL_HOME/etc/ec2/amitools/.

Default: varies, depending on the tools

Required: Only for the us-gov-west-1 and cn-north-1 regions.

Example: --ec2cert $EC2_AMITOOL_HOME/etc/ec2/amitools/cert-ec2.pem

-r, --arch architecture

The image architecture. If you don't provide this on the command line, you'll be prompted to provide it when the bundling starts.

Valid values: i386 | x86_64

Required: No

Example: -r x86_64

--productcodes code1,code2,...

Product codes to attach to the image at registration time, separated by commas.

Required: No

Example: --productcodes 1234abcd

-B, --block-device-mapping mapping

Defines how block devices are exposed to an instance of this AMI if its instance type supports the specified device.

Specify a comma-separated list of key-value pairs, where each key is a virtual name and each value is the corresponding device name. Virtual names include the following:

  • ami—The root file system device, as seen by the instance

  • root—The root file system device, as seen by the kernel

  • swap—The swap device, as seen by the instance

  • ephemeralN—The Nth instance store volume

Required: No

Example: --block-device-mapping ami=sda1,root=/dev/sda1,ephemeral0=sda2,swap=sda3

Example: --block-device-mapping ami=0,root=/dev/dsk/c0d0s0,ephemeral0=1

-a, --all

Bundle all directories, including those on remotely mounted file systems.

Required: No

Example: -a

-e, --exclude directory1,directory2,...

A list of absolute directory paths and files to exclude from the bundle operation. This parameter overrides the --all option. When exclude is specified, the directories and subdirectories listed with the parameter will not be bundled with the volume.

Required: No

Example: Assuming the mount point of the volume is -v /foo, and you want to exclude directories /foo/bar and /foo/baz, specify -e /bar,/baz.

-i, --include file1,file2,...

A list of files to include in the bundle operation. The specified files would otherwise be excluded from the AMI because they might contain sensitive information.

Required: No

Example: If the volume mount point is /mnt/myvol/ and you want to include the file /mnt/myvol/foo/bar.pem, specify -i /foo/bar.pem.

--no-filter

If specified, we won't exclude files from the AMI because they might contain sensitive information.

Required: No

Example: --no-filter

-p, --prefix prefix

The file name prefix for bundled AMI files.

Default: image

Required: No

Example: -p my-image-is-special

-s, --size size

The size, in MB (1024 * 1024 bytes), of the image file to create. The maximum size is 10240 MB.

Default: 10240

Required: No

Example: -s 2048

--[no-]inherit

Indicates whether the image should inherit the instance's metadata (the default is to inherit). Bundling fails if you enable --inherit but the instance metadata is not accessible.

Required: No

Example: --inherit

-v, --volume volume

The absolute path to the mounted volume from which to create the bundle.

Default: The root directory (/)

Required: No

Example: -v /mnt/my-customized-ami

-P, --partition type

Indicates whether the disk image should use a partition table. If you don't specify a partition table type, the default is the type used on the parent block device of the volume, if applicable, otherwise the default is gpt.

Valid values: mbr | gpt | none

Required: No

Example: --partition gpt

-S, --script script

A customization script to be run right before bundling. The script must expect a single argument, the mount point of the volume.

Required: No

--fstab path

The path to the fstab to bundle into the image. If this is not specified, Amazon EC2 bundles /etc/fstab.

Required: No

Example: --fstab /etc/fstab

--generate-fstab

Bundles the volume using an Amazon EC2-provided fstab.

Required: No

Example: --generate-fstab

--grub-config

The path to an alternate grub configuration file to bundle into the image. By default, ec2-bundle-vol expects either /boot/grub/menu.lst or /boot/grub/grub.conf to exist on the cloned image. This option allows you to specify a path to an alternative grub configuration file, which will then be copied over the defaults (if present).

Required: No

Example: --grub-config /path/to/grub.conf

--kernel kernel_id

Deprecated. Use register-image to set the kernel.

Required: No

Example: --kernel aki-ba3adfd3

--ramdisk ramdisk_id

Deprecated. Use register-image to set the RAM disk if required.

Required: No

Example: --ramdisk ari-badbad00

Common options

For options common to most of the AMI tools, see Common Options for AMI Tools.

Output

Status messages describing the stages and status of the bundling.

Example

This example creates a bundled AMI by compressing, encrypting and signing a snapshot of the local machine's root file system.

Copy to clipboard
$ ec2-bundle-vol -d /mnt -k pk-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem -c cert-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem -u 111122223333 -r x86_64 Copying / into the image file /mnt/image... Excluding: sys dev/shm proc dev/pts proc/sys/fs/binfmt_misc dev media mnt proc sys tmp/image mnt/img-mnt 1+0 records in 1+0 records out mke2fs 1.38 (30-Jun-2005) warning: 256 blocks unused. Splitting /mnt/image.gz.crypt... Created image.part.00 Created image.part.01 Created image.part.02 Created image.part.03 ... Created image.part.22 Created image.part.23 Generating digests for each part... Digests generated. Creating bundle manifest... Bundle Volume complete.

ec2-delete-bundle

Description

Deletes the specified bundle from Amazon S3 storage. After you delete a bundle, you can't launch instances from the corresponding AMI.

Syntax

ec2-delete-bundle -b bucket -a access_key_id -s secret_access_key [-t token] [--url url] [--region region] [--sigv version] [-m path] [-p prefix] [--clear] [--retry] [-y]

Options

Option Description

-b, --bucket bucket

The name of the Amazon S3 bucket containing the bundled AMI, followed by an optional '/'-delimited path prefix

Required: Yes

Example: -b myawsbucket/ami-001

-a, --access-key access_key_id

The AWS access key ID. Before you specify a value for this option, review and follow the guidance in Best Practices for Managing AWS Access Keys.

Required: Yes

Example: -a AKIAIOSFODNN7EXAMPLE

-s, --secret-key secret_access_key

The AWS secret access key. Before you specify a value for this option, review and follow the guidance in Best Practices for Managing AWS Access Keys.

Required: Yes

Example: -s wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

-t, --delegation-token token

The delegation token to pass along to the AWS request. For more information, see Using Temporary Security Credentials.

Required: Only when you are using temporary security credentials.

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

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

--region region

The region to use in the request signature.

Default: us-east-1

Required: Conditional

Condition: Required if using signature version 4

Example: --region eu-west-1

--sigv version

The signature version to use when signing the request.

Valid values: 2 | 4

Default: 4

Required: No

Example: --sigv 2

-m, --manifest path

The path to the manifest file.

Required: Conditional

Condition: You must specify --prefix or --manifest.

Example: -m /var/spool/my-first-bundle/image.manifest.xml

-p, --prefix prefix

The bundled AMI filename prefix. Provide the entire prefix. For example, if the prefix is image.img, use -p image.img and not -p image.

Required: Conditional

Condition: You must specify --prefix or --manifest.

Example: -p image.img

--clear

Deletes the Amazon S3 bucket if it's empty after deleting the specified bundle.

Required: No

Example: --clear

--retry

Automatically retries on all Amazon S3 errors, up to five times per operation.

Required: No

Example: --retry

-y, --yes

Automatically assumes the answer to all prompts is yes.

Required: No

Example: -y

Common options

For options common to most of the AMI tools, see Common Options for AMI Tools.

Output

Amazon EC2 displays status messages indicating the stages and status of the delete process.

Example

This example deletes a bundle from Amazon S3.

Copy to clipboard
$ ec2-delete-bundle -b myawsbucket -a your_access_key_id -s your_secret_access_key Deleting files: myawsbucket/image.manifest.xml myawsbucket/image.part.00 myawsbucket/image.part.01 myawsbucket/image.part.02 myawsbucket/image.part.03 myawsbucket/image.part.04 myawsbucket/image.part.05 myawsbucket/image.part.06 Continue? [y/n] y Deleted myawsbucket/image.manifest.xml Deleted myawsbucket/image.part.00 Deleted myawsbucket/image.part.01 Deleted myawsbucket/image.part.02 Deleted myawsbucket/image.part.03 Deleted myawsbucket/image.part.04 Deleted myawsbucket/image.part.05 Deleted myawsbucket/image.part.06 ec2-delete-bundle complete.

ec2-download-bundle

Description

Downloads the specified instance store-backed Linux AMIs from Amazon S3 storage.

Syntax

ec2-download-bundle -b bucket -a access_key_id -s secret_access_key -k path [--url url] [--region region] [--sigv version] [-m file] [-p prefix] [-d directory] [--retry]

Options

Option Description

-b, --bucket bucket

The name of the Amazon S3 bucket where the bundle is located, followed by an optional '/'-delimited path prefix.

Required: Yes

Example: -b myawsbucket/ami-001

-a, --access-key access_key_id

The AWS access key ID. Before you specify a value for this option, review and follow the guidance in Best Practices for Managing AWS Access Keys.

Required: Yes

Example: -a AKIAIOSFODNN7EXAMPLE

-s, --secret-key secret_access_key

The AWS secret access key. Before you specify a value for this option, review and follow the guidance in Best Practices for Managing AWS Access Keys.

Required: Yes

Example: -s wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

-k, --privatekey path

The private key used to decrypt the manifest.

Required: Yes

Example: -k pk-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem

--url url

The Amazon S3 service URL.

Default: https://s3.amazonaws.com

Required: No

Example: --url https://s3.example.com

--region region

The region to use in the request signature.

Default: us-east-1

Required: Conditional

Condition: Required if using signature version 4

Example: --region eu-west-1

--sigv version

The signature version to use when signing the request.

Valid values: 2 | 4

Default: 4

Required: No

Example: --sigv 2

-m, --manifest file

The name of the manifest file (without the path). We recommend that you specify either the manifest (-m) or a prefix (-p).

Required: No

Example: -m my-image.manifest.xml

-p, --prefix prefix

The filename prefix for the bundled AMI files.

Default: image

Required: No

Example: -p my-image

-d, --directory directory

The directory where the downloaded bundle is saved. The directory must exist.

Default: The current working directory.

Required: No

Example: -d /tmp/my-downloaded-bundle

--retry

Automatically retries on all Amazon S3 errors, up to five times per operation.

Required: No

Example: --retry

Common options

For options common to most of the AMI tools, see Common Options for AMI Tools.

Output

Status messages indicating the various stages of the download process are displayed.

Example

This example creates the bundled directory (using the Linux mkdir command) and downloads the bundle from the myawsbucket Amazon S3 bucket.

Copy to clipboard
$ mkdir bundled $ ec2-download-bundle -b myawsbucket/bundles/bundle_name -m image.manifest.xml -a your_access_key_id -s your_secret_access_key -k pk-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem -d mybundle Downloading manifest image.manifest.xml from myawsbucket to mybundle/image.manifest.xml ... Downloading part image.part.00 from myawsbucket/bundles/bundle_name to mybundle/image.part.00 ... Downloaded image.part.00 from myawsbucket Downloading part image.part.01 from myawsbucket/bundles/bundle_name to mybundle/image.part.01 ... Downloaded image.part.01 from myawsbucket Downloading part image.part.02 from myawsbucket/bundles/bundle_name to mybundle/image.part.02 ... Downloaded image.part.02 from myawsbucket Downloading part image.part.03 from myawsbucket/bundles/bundle_name to mybundle/image.part.03 ... Downloaded image.part.03 from myawsbucket Downloading part image.part.04 from myawsbucket/bundles/bundle_name to mybundle/image.part.04 ... Downloaded image.part.04 from myawsbucket Downloading part image.part.05 from myawsbucket/bundles/bundle_name to mybundle/image.part.05 ... Downloaded image.part.05 from myawsbucket Downloading part image.part.06 from myawsbucket/bundles/bundle_name to mybundle/image.part.06 ... Downloaded image.part.06 from myawsbucket

ec2-migrate-manifest

Description

Modifies an instance store-backed Linux AMI (for example, its certificate, kernel, and RAM disk) so that it supports a different region.

Syntax

ec2-migrate-manifest -c path -k path -m path {(-a access_key_id -s secret_access_key --region region) | (--no-mapping)} [--ec2cert ec2_cert_path] [--kernel kernel-id] [--ramdisk ramdisk_id]

Options

Option Description

-c, --cert path

The user's PEM encoded RSA public key certificate file.

Required: Yes

Example: -c cert-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem

-k, --privatekey path

The path to the user's PEM-encoded RSA key file.

Required: Yes

Example: -k pk-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem

--manifest path

The path to the manifest file.

Required: Yes

Example: --manifest my-ami.manifest.xml

-a, --access-key access_key_id

The AWS access key ID. Before you specify a value for this option, review and follow the guidance in Best Practices for Managing AWS Access Keys.

Required: Conditional

Condition: Required if using automatic mapping.

Example: -a AKIAIOSFODNN7EXAMPLE

-s, --secret-key secret_access_key

The AWS secret access key. Before you specify a value for this option, review and follow the guidance in Best Practices for Managing AWS Access Keys.

Required: Conditional

Condition: Required if using automatic mapping.

Example: -s wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

--region region

The region to look up in the mapping file.

Condition: Required if using automatic mapping.

Required: Conditional

Example: --region eu-west-1

--no-mapping

Disables automatic mapping of kernels and RAM disks.

During migration, Amazon EC2 replaces the kernel and RAM disk in the manifest file with a kernel and RAM disk designed for the destination region. Unless the --no-mapping parameter is given, ec2-migrate-bundle might use the DescribeRegions and DescribeImages operations to perform automated mappings.

Required: Conditional

Condition: Required if you're not providing the -a, -s, and --region options (which are used for automatic mapping).

--ec2cert path

The path to the Amazon EC2 X.509 public key certificate used to encrypt the image manifest.

The us-gov-west-1 and cn-north-1 regions use a non-default public key certificate and the path to that certificate must be specified with this option. The path to the certificate varies based on the installation method of the AMI tools. For Amazon Linux, the certificates are located at /opt/aws/amitools/ec2/etc/ec2/amitools/. If you installed the AMI tools from the ZIP file in Setting Up the AMI Tools, the certificates are located at $EC2_AMITOOL_HOME/etc/ec2/amitools/.

Default: varies, depending on the tools

Required: Only for the us-gov-west-1 and cn-north-1 regions.

Example: --ec2cert $EC2_AMITOOL_HOME/etc/ec2/amitools/cert-ec2.pem

--kernel kernel_id

The ID of the kernel to select.

Important

We recommend that you use PV-GRUB instead of kernels and RAM disks. For more information, see PV-GRUB.

Required: No

Example: --kernel aki-ba3adfd3

--ramdisk ramdisk_id

The ID of the RAM disk to select.

Important

We recommend that you use PV-GRUB instead of kernels and RAM disks. For more information, see PV-GRUB.

Required: No

Example: --ramdisk ari-badbad00

Common options

For options common to most of the AMI tools, see Common Options for AMI Tools.

Output

Status messages describing the stages and status of the bundling process.

Example

This example copies the AMI specified in the my-ami.manifest.xml manifest from the US to the EU.

Copy to clipboard
$ ec2-migrate-manifest --manifest my-ami.manifest.xml --cert cert-HKZYKTAIG2ECMXYIBH3HXV4ZBZQ55CLO.pem --privatekey pk-HKZYKTAIG2ECMXYIBH3HXV4ZBZQ55CLO.pem --region eu-west-1 Backing up manifest... Successfully migrated my-ami.manifest.xml It is now suitable for use in eu-west-1.

ec2-unbundle

Description

Re-creates the bundle from an instance store-backed Linux AMI.

Syntax

ec2-unbundle -k path -m path [-s source_directory] [-d destination_directory]

Options

Option Description

-k, --privatekey path

The path to your PEM-encoded RSA key file.

Required: Yes

Example: -k $HOME/pk-234242example.pem

-m, --manifest path

The path to the manifest file.

Required: Yes

Example: -m /var/spool/my-first-bundle/Manifest

-s, --source source_directory

The directory containing the bundle.

Default: The current directory.

Required: No

Example: -s /tmp/my-bundled-image

-d, --destination destination_directory

The directory in which to unbundle the AMI. The destination directory must exist.

Default: The current directory.

Required: No

Example: -d /tmp/my-image

Common options

For options common to most of the AMI tools, see Common Options for AMI Tools.

Example

This Linux and UNIX example unbundles the AMI specified in the image.manifest.xml file.

Copy to clipboard
$ mkdir unbundled $ ec2-unbundle -m mybundle/image.manifest.xml -k pk-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem -s mybundle -d unbundled $ ls -l unbundled total 1025008 -rw-r--r-- 1 root root 1048578048 Aug 25 23:46 image.img

Output

Status messages indicating the various stages of the unbundling process are displayed.

ec2-upload-bundle

Description

Uploads the bundle for an instance store-backed Linux AMI to Amazon S3 and sets the appropriate ACLs on the uploaded objects. For more information, see Creating an Instance Store-Backed Linux AMI.

Syntax

ec2-upload-bundle -b bucket -a access_key_id -s secret_access_key [-t token] -m path [--url url] [--region region] [--sigv version] [--acl acl] [-d directory] [--part part] [--retry] [--skipmanifest]

Options

Option Description

-b, --bucket bucket

The name of the Amazon S3 bucket in which to store the bundle, followed by an optional '/'-delimited path prefix. If the bucket doesn't exist, it's created if the bucket name is available.

Required: Yes

Example: -b myawsbucket/bundles/ami-001

-a, --access-key access_key_id

Your AWS access key ID. Before you specify a value for this option, review and follow the guidance in Best Practices for Managing AWS Access Keys.

Required: Yes

Example: -a AKIAIOSFODNN7EXAMPLE

-s, --secret-key secret_access_key

Your AWS secret access key. Before you specify a value for this option, review and follow the guidance in Best Practices for Managing AWS Access Keys.

Required: Yes

Example: -s wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

-t, --delegation-token token

The delegation token to pass along to the AWS request. For more information, see Using Temporary Security Credentials.

Required: Only when you are using temporary security credentials.

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

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

-m, --manifest path

The path to the manifest file. The manifest file is created during the bundling process and can be found in the directory containing the bundle.

Required: Yes

Example: -m image.manifest.xml

--url url

Deprecated. Use the --region option instead unless your bucket is constrained to the EU location (and not eu-west-1). The --location flag is the only way to target that specific location restraint.

The Amazon S3 endpoint service URL.

Default: https://s3.amazonaws.com

Required: No

Example: --url https://s3.example.com

--region region

The region to use in the request signature for the destination Amazon S3 bucket.

  • If the bucket doesn't exist and you don't specify a region, the tool creates the bucket without a location constraint (in us-east-1).

  • If the bucket doesn't exist and you specify a region, the tool creates the bucket in the specified region.

  • If the bucket exists and you don't specify a region, the tool uses the bucket's location.

  • If the bucket exists and you specify us-east-1 as the region, the tool uses the bucket's actual location without any error message, any existing matching files are over-written.

  • If the bucket exists and you specify a region (other than us-east-1) that doesn't match the bucket's actual location, the tool exits with an error.

If your bucket is constrained to the EU location (and not eu-west-1), use the --location flag instead. The --location flag is the only way to target that specific location restraint.

Default: us-east-1

Required: Conditional

Condition: Required if using signature version 4

Example: --region eu-west-1

--sigv version

The signature version to use when signing the request.

Valid values: 2 | 4

Default: 4

Required: No

Example: --sigv 2

--acl acl

The access control list policy of the bundled image.

Valid values: public-read | aws-exec-read

Default: aws-exec-read

Required: No

Example: --acl public-read

-d, --directory directory

The directory containing the bundled AMI parts.

Default: The directory containing the manifest file (see the -m option).

Required: No

Example: -d /var/run/my-bundle

--part part

Starts uploading the specified part and all subsequent parts.

Required: No

Example: --part 04

--retry

Automatically retries on all Amazon S3 errors, up to five times per operation.

Required: No

Example: --retry

--skipmanifest

Does not upload the manifest.

Required: No

Example: --skipmanifest

--location location

Deprecated. Use the --region option instead, unless your bucket is constrained to the EU location (and not eu-west-1). The --location flag is the only way to target that specific location restraint.

The location constraint of the destination Amazon S3 bucket. If the bucket exists and you specify a location that doesn't match the bucket's actual location, the tool exits with an error. If the bucket exists and you don't specify a location, the tool uses the bucket's location. If the bucket doesn't exist and you specify a location, the tool creates the bucket in the specified location. If the bucket doesn't exist and you don't specify a location, the tool creates the bucket without a location constraint (in us-east-1).

Default: If --region is specified, the location is set to that specified region. If --region is not specified, the location defaults to us-east-1.

Required: No

Example: --location eu-west-1

Common options

For options common to most of the AMI tools, see Common Options for AMI Tools.

Output

Amazon EC2 displays status messages that indicate the stages and status of the upload process.

Example

This example uploads the bundle specified by the image.manifest.xml manifest.

Copy to clipboard
$ ec2-upload-bundle -b myawsbucket/bundles/bundle_name -m image.manifest.xml -a your_access_key_id -s your_secret_access_key Creating bucket... Uploading bundled image parts to the S3 bucket myawsbucket ... Uploaded image.part.00 Uploaded image.part.01 Uploaded image.part.02 Uploaded image.part.03 Uploaded image.part.04 Uploaded image.part.05 Uploaded image.part.06 Uploaded image.part.07 Uploaded image.part.08 Uploaded image.part.09 Uploaded image.part.10 Uploaded image.part.11 Uploaded image.part.12 Uploaded image.part.13 Uploaded image.part.14 Uploading manifest ... Uploaded manifest. Bundle upload completed.

Common Options for AMI Tools

Most of the commands described in this section accept the set of optional parameters described in the following table.

Option Description

--help, -h

Displays the help message.

--version

Displays the version and copyright notice.

--manual

Displays the manual entry.

--batch

Runs in batch mode, suppressing interactive prompts.

--debug

Displays debugging information that may be useful when troubleshooting problems.

Managing Signing Certificates

This section describes how to create and manage signing certificates; also known as X.509 certificates. These certificates are required for certain AMI tool commands.

Important

Amazon EC2 originally supported the SOAP protocol for making service calls, and SOAP-based calls use a signing certificate in order to digitally sign the requests. However, support for SOAP in Amazon EC2 is deprecated (see SOAP Requests), and you should use HTTP query requests instead. For more information, see Making API Requests.

Each user can have two certificates for the purposes of credential rotation.

Note

You can give your users permission to list and manage their own certificates. For more information, see Allow Users to Manage Their Own Passwords, Access Keys, and Signing Certificate in the IAM User Guide.

Creating a User Signing Certificate

If you need a signing certificate, you must first obtain one, and then upload it to AWS. There is no Amazon EC2 API action to create signing certificates, so you must use a third-party tool such as OpenSSL to create the user signing certificate.

Note

Although you can use the security credentials page in the AWS Management Console to create an X.509 certificate, that method is only for the AWS account root credentials. You can't upload a certificate generated using the console for individual Amazon EC2 users. Instead, use the process described in the next sections.

To create a signing certificate, you must do the following:

  • Install and configure OpenSSL.

  • Create a private key.

  • Generate a certificate using the private key.

  • Upload the certificate to AWS.

Install and Configure OpenSSL

Creating and uploading a certificate requires a tool that supports the SSL and TLS protocols. OpenSSL is an open-source tool that provides the basic cryptographic functions necessary to create an RSA token and sign it with your private key. If you don't already have OpenSSL installed, follow these instructions.

To install OpenSSL on Linux and UNIX

  1. Go to OpenSSL: Source, Tarballs (http://www.openssl.org/source/).

  2. Download the latest source and build the package.

To install OpenSSL on Windows

  1. Go to Binaries (https://wiki.openssl.org/index.php/Binaries).

  2. Choose the appropriate OpenSSL for Windows option.

    A new page displays with links to the Windows downloads.

  3. If it is not already installed on your system, select the Microsoft Visual C++ 2008 Redistributables link appropriate for your environment and click Download. Follow the instructions provided by the Microsoft Visual C++ 2008 Redistributable Setup Wizard.

    Note

    If you are not sure if the Microsoft Visual C++ 2008 Redistributable package is already installed on your system, you can try installing OpenSSL first. The OpenSSL installer displays an error if the Microsoft Visual C++ 2008 Redistributable package is not yet installed. Make sure you install the architecture (32-bit or 64-bit) that matches the version of OpenSSL that you install.

  4. After you have installed the Microsoft Visual C++ 2008 Redistributable package, select the appropriate version of the OpenSSL binaries for your environment and save the file locally. Launch the OpenSSL Setup Wizard.

  5. Follow the instructions described in the OpenSSL Setup Wizard.

Before you use OpenSSL commands, you must configure the operating system so that it has information about the location where OpenSSL is installed.

To configure OpenSSL on Linux or Unix

  1. At the command line, set the OpenSSL_HOME variable to the location of the OpenSSL installation:

    Copy to clipboard
    export OpenSSL_HOME=path_to_your_OpenSSL_installation
  2. Set the path to include the OpenSSL installation:

    Copy to clipboard
    export PATH=$PATH:$OpenSSL_HOME/bin

    Note

    Any changes you make to environment variables using the export command are valid only for the current session. You can make persistent changes to the environment variables by setting them using your shell configuration file. For more information, see the documentation for your operating system.

To configure OpenSSL on Windows

  1. Open a Command Prompt window.

  2. Set the OpenSSL_HOME variable to the location of the OpenSSL installation:

    Copy to clipboard
    set OpenSSL_HOME=path_to_your_OpenSSL_installation
  3. Set the OpenSSL_CONF variable to the location of the configuration file in your OpenSSL installation:

    Copy to clipboard
    set OpenSSL_CONF=path_to_your_OpenSSL_installation\bin\openssl.cfg
  4. Set the path to include the OpenSSL installation:

    Copy to clipboard
    set Path=%Path%;%OpenSSL_HOME%\bin

    Note

    Any changes you make to Windows environment variables in a Command Prompt window are valid only for the current command line session. You can make persistent changes to the environment variables by setting them as system properties. The exact procedures depends on what version of Windows you're using. For more information, see the Windows documentation.

Create a Private Key

You need a unique private key that you use when generating the user signing certificate.

To create a private key

  1. At the command line, use the openssl genrsa command with the following syntax:

    Copy to clipboard
    openssl genrsa 2048 > private-key.pem

    For private-key.pem, specify your own file name. In the example, 2048 represents 2048-bit encryption. AWS also supports 1024-bit and 4096-bit encryption. We recommend that you create a 2048-bit or 4096-bit RSA key.

  2. If you will be using the certificate to authenticate CLI commands for Auto Scaling, CloudWatch, or Elastic Load Balancing, generate the certificate in PKCS8 format using the following command:

    Copy to clipboard
    openssl pkcs8 -topk8 -nocrypt -inform PEM -in private-key.pem -out private-key-in-PKCS8-format.pem

Create the User Signing Certificate

You can now create a user signing certificate.

To create a user signing certificate

  • Use the openssl req command with the following syntax:

    Copy to clipboard
    openssl req -new -x509 -nodes -sha256 -days 365 -key private-key.pem -outform PEM -out certificate.pem

    For private-key.pem, use the .pem file that you generated in a previous procedure. For certificate.pem, use the name of a file into which you want the certificate to be generated. The certificate must be in .pem format. For security, we recommend using either SHA-256, as in this example, or SHA-512 as your hash algorithm.

    In this example, the -days 365 switch specifies that the certificate is good for 365 days. For information about the other switches, enter openssl req -h at the command line.

    OpenSSL displays a message similar to the following:

    Copy to clipboard
    You are about to be asked to enter information that will be incorporated into your certificate request. What you are about to enter is what is called a Distinguished Name or a DN. There are quite a few fields but you can leave some blank. For some fields there will be a default value. If you enter '.', the field will be left blank.

    Because you're creating a user signing certificate (not a server certificate), you can leave all the values blank when you're prompted. These values are used by the certificate authority (CA) to help authenticate the server certificate. However, because user signing certificates are uploaded in an authenticated session, AWS does not need any information in the certificate for further validation, and requires only the public-private key pair.

The .pem file contains the certificate value that you can copy and paste during the upload procedure that follows.

Upload the User Signing Certificate

You can upload a signing certificate using the upload-signing-certificate AWS CLI command. Specify the name of the user for which you want to upload the certificate, and the path to the .pem file that contains the certificate value.

Copy to clipboard
aws iam upload-signing-certificate --user-name user-name --certificate-body file://path/to/certificate.pem

Alternatively, use the UploadSigningCertificate IAM API action.

Note

Use a POST request when uploading a signing certificate because of the certificate's size.

Users cannot have more than two signing certificates.

Managing a User Signing Certificate

You can manage a signing certificate using the AWS CLI.

As with access keys, each certificate can have a status of either Active or Inactive. By default, the status is Active when you upload the certificate. When you upload the certificate, it returns a certificate ID that you can save for your records. You can list the IDs for the user's certificates. You can delete a certificate at any time.

To list the certificates for a user, use the list-signing-certificates AWS CLI command:

Copy to clipboard
aws iam list-signing-certificates --user-name user-name

To disable or re-enable a signing certificate for a user, use the update-signing-certificate AWS CLI command. The following command disables the certificate:

Copy to clipboard
aws iam update-signing-certificate --certificate-id OFHPLP4ZULTHYPMSYEX7O4BEXAMPLE --status Inactive --user-name user-name

To delete a certificate, use the delete-signing-certificate AWS CLI command:

Copy to clipboard
aws iam delete-signing-certificate --user-name user-name --certificate-id OFHPLP4ZULTHYPMSYEX7O4BEXAMPLE

Alternatively, you can use the following IAM API actions: