NAME

       migrate-ebs-image - Copy an EBS-backed Amazon Image from one region to another

SYNOPSYS

         % migrate-ebs-image --from us-east-1 --to ap-southeast-1 ami-123456

DESCRIPTION

       This script copies an EBS-backed Unix/Linux/windows AMI located in the EC2 region
       indicated by --from to the region indicated by --to. All associated volume snapshots,
       including LVM and RAID volumes, are migrated as well.

       If --from is omitted, then the source region is derived from the endpoint URL contained in
       the EC2_URL environment variable. The --to option is required.

       This script works with any EBS backed image, including Linux PVM, Linux HVM (cluster) and
       Windows images. It will not work with any instance-store backed image. To migrate such
       instances, please see one of the recipes listed online, for example:

        http://www.dowdandassociates.com/content/howto-move-ec2-instance-store-ami-one-region-another

COMMAND-LINE OPTIONS

       Options can be abbreviated.  For example, you can use -l for --list-regions and -b for
       --block-device-mapping:

             --from         Region in which the AMI is currently located (e.g. "us-east-1")
             --to           Region to which the AMI is to be copied (e.g. "us-west-1") REQUIRED
             --access_key   EC2 access key
             --secret_key   EC2 secret key
             --block_device_mapping
                            Add additional block devices to the image.
             --endpoint     EC2 URL (defaults to http://ec2.amazonaws.com/)
             --kernel       Force assignment of kernel in destination image.
             --ramdisk      Force assignment of ramdisk in destination image.
             --quiet        Quench status messages
             --list_regions List the EC2 regions

       The --block-device-mapping (-b) option is used to add ephemeral storage to the destination
       image. Amazon's API doesn't describe ephemeral volumes that are associated with images,
       and so this information is not copied from the source to the destination image, requiring
       you to add it back manually. The value of the argument is a block device mapping string in
       the same format as described for the command line program ec2-register:

        migrate-ebs-image -f us-east-1 -t ap-southeast-1 \
                             -b /dev/sdy=ephemeral0 \
                             ami-123456

       Ordinarily the script attempts to guess the correct matching kernel and ramdisk for the
       destination image based on approximate string matching. You can override these values by
       manually specifying the kernel and/or ramdisk ID in the destination region. Note that no
       checking is performed that the values you provide are correct.

ENVIRONMENT VARIABLES

       The following environment variables are used if the corresponding options are not present:

        EC2_ACCESS_KEY     your access key
        EC2_SECRET_KEY     your secret key
        EC2_URL            the desired region endpoint

INSTALLING THIS SCRIPT

       This script is part of the Perl VM::EC2 package. To install from the command line:

        % perl -MCPAN -e 'install VM::EC2'
        % migrate-ebs-image --from us-east-1 --to ap-southeast-1 ami-123456

IMPORTANT CAVEATS

       This script launches two "m1.small" instances, one each in the source and destination
       regions. It also creates transient volumes in both regions to hold the root volume and all
       other EBS snapshots associated with the image. Running it will incur charges for instance
       run time and data storage.

       In addition, this script will transfer data from one region to another across the
       internet, incurring internet data out fees on the source side, and internet data in fees
       on the destination side. Volumes that contain a filesystem, such as ext4 or ntfs, are
       copied from source to destination using rsync. Volumes that are part of a RAID or LVM
       volume are copied at the block level using gzip and dd via the secure shell. In general,
       rsync will be much faster and parsimonious of network bandwidth than block copying!

SEE ALSO

       VM::EC2, VM::EC2::Staging::Manager

AUTHOR

       Lincoln Stein, lincoln.stein@gmail.com

       Copyright (c) 2012 Ontario Institute for Cancer Research

       This package and its accompanying libraries is free software; you can redistribute it
       and/or modify it under the terms of the GPL (either version 1, or at your option, any
       later version) or the Artistic License 2.0.  Refer to LICENSE for the full license text.
       In addition, please see DISCLAIMER.txt for disclaimers of warranty.