.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "MIGRATE-EBS-IMAGE 1p"
.TH MIGRATE-EBS-IMAGE 1p "2016-06-04" "perl v5.22.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
migrate\-ebs\-image \- Copy an EBS\-backed Amazon Image from one region to another
.SH "SYNOPSYS"
.IX Header "SYNOPSYS"
.Vb 1
\&  % migrate\-ebs\-image \-\-from us\-east\-1 \-\-to ap\-southeast\-1 ami\-123456
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This script copies an EBS-backed Unix/Linux/windows \s-1AMI\s0 located in the
\&\s-1EC2\s0 region indicated by \-\-from to the region indicated by \-\-to. All
associated volume snapshots, including \s-1LVM\s0 and \s-1RAID\s0 volumes, are
migrated as well.
.PP
If \-\-from is omitted, then the source region is derived from the
endpoint \s-1URL\s0 contained in the \s-1EC2_URL\s0 environment variable. The \-\-to
option is required.
.PP
This script works with any \s-1EBS\s0 backed image, including Linux \s-1PVM,\s0
Linux \s-1HVM \s0(cluster) and Windows images. It will \fBnot\fR work with any
instance-store backed image. To migrate such instances, please see one
of the recipes listed online, for example:
.PP
.Vb 1
\& http://www.dowdandassociates.com/content/howto\-move\-ec2\-instance\-store\-ami\-one\-region\-another
.Ve
.SH "COMMAND-LINE OPTIONS"
.IX Header "COMMAND-LINE OPTIONS"
Options can be abbreviated.  For example, you can use \-l for
\&\-\-list\-regions and \-b for \-\-block\-device\-mapping:
.PP
.Vb 11
\&      \-\-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
.Ve
.PP
The \-\-block\-device\-mapping (\-b) option is used to add ephemeral
storage to the destination image. Amazon's \s-1API\s0 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:
.PP
.Vb 3
\& migrate\-ebs\-image \-f us\-east\-1 \-t ap\-southeast\-1 \e
\&                      \-b /dev/sdy=ephemeral0 \e
\&                      ami\-123456
.Ve
.PP
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 \s-1ID\s0 in the destination region. Note that no
checking is performed that the values you provide are correct.
.SH "ENVIRONMENT VARIABLES"
.IX Header "ENVIRONMENT VARIABLES"
The following environment variables are used if the corresponding
options are not present:
.PP
.Vb 3
\& EC2_ACCESS_KEY     your access key
\& EC2_SECRET_KEY     your secret key
\& EC2_URL            the desired region endpoint
.Ve
.SH "INSTALLING THIS SCRIPT"
.IX Header "INSTALLING THIS SCRIPT"
This script is part of the Perl \s-1VM::EC2\s0 package. To install from the
command line:
.PP
.Vb 2
\& % perl \-MCPAN \-e \*(Aqinstall VM::EC2\*(Aq
\& % migrate\-ebs\-image \-\-from us\-east\-1 \-\-to ap\-southeast\-1 ami\-123456
.Ve
.SH "IMPORTANT CAVEATS"
.IX Header "IMPORTANT CAVEATS"
This script launches two \*(L"m1.small\*(R" 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 \s-1EBS\s0 snapshots associated
with the image. Running it will incur charges for instance run time
and data storage.
.PP
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 \s-1RAID\s0 or \s-1LVM\s0 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!
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1VM::EC2\s0, VM::EC2::Staging::Manager
.SH "AUTHOR"
.IX Header "AUTHOR"
Lincoln Stein, lincoln.stein@gmail.com
.PP
Copyright (c) 2012 Ontario Institute for Cancer Research
.PP
This package and its accompanying libraries is free software; you can
redistribute it and/or modify it under the terms of the \s-1GPL \s0(either
version 1, or at your option, any later version) or the Artistic
License 2.0.  Refer to \s-1LICENSE\s0 for the full license text. In addition,
please see \s-1DISCLAIMER\s0.txt for disclaimers of warranty.