.\" 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 "VM::EC2::Snapshot 3pm"
.TH VM::EC2::Snapshot 3pm "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"
VM::EC2::Snapshot \- Object describing an Amazon EBS snapshot
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use VM::EC2;
\&
\&  $ec2       = VM::EC2\->new(...);
\&  @snap = $ec2\->describe_snapshots;
\&  for my $snap (@snapshots) {
\&      $id    = $snap\->snapshotId;
\&      $vol   = $snap\->volumeId;
\&      $state = $snap\->status;
\&      $time  = $snap\->startTime;
\&      $progress = $snap\->progress;
\&      $size  = $snap\->volumeSize;
\&      $description = $snap\->description;
\&      $tags  = $snap\->tags;
\&  }
\&
\& # use a snapshot as the root device for a new AMI
\& $ami = $snap\->register_image(\-name         => \*(AqMy new image\*(Aq,
\&                               \-kernel_id    => \*(Aqaki\-407d9529\*(Aq,
\&                               \-architecture => \*(Aqi386\*(Aq);
\&
\& #create a volume from the snapshot
\& $vol = $snap\->create_volume(\-zone => \*(Aqus\-east\-1a\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This object is used to describe an Amazon \s-1EBS\s0 snapshot.
.SH "METHODS"
.IX Header "METHODS"
The following object methods are supported:
.PP
.Vb 12
\& snapshotId       \-\- ID of this snapshot
\& ownerId          \-\- Owner of this snapshot
\& volumeId         \-\- ID of the volume snapshot was taken from
\& status           \-\- Snapshot state, one of "pending", "completed" or "error"
\& startTime        \-\- Timestamp for when snapshot was begun.
\& progress         \-\- The progress of the snapshot, in percent.
\& volumeSize       \-\- Size of the volume, in gigabytes.
\& description      \-\- Description of the snapshot
\& ownerAlias       \-\- AWS account alias, such as "self".
\& encrypted        \-\- True if snapshot is encrypted
\& tags             \-\- Hashref containing tags associated with this group.
\&                     See L<VM::EC2::Generic>.
.Ve
.PP
In addition, this class provides several convenience functions:
.ie n .SS "$vol = $snap\->from_volume"
.el .SS "\f(CW$vol\fP = \f(CW$snap\fP\->from_volume"
.IX Subsection "$vol = $snap->from_volume"
Returns the VM::EC2::Volume object that this snapshot was originally
derived from. If the original volume no longer exists because it has
been deleted, this will return undef; if \-raise_error was passed to
the \s-1VM::EC2\s0 object, this will raise an exception.
.ie n .SS "@vol = $snap\->to_volumes"
.el .SS "\f(CW@vol\fP = \f(CW$snap\fP\->to_volumes"
.IX Subsection "@vol = $snap->to_volumes"
Returns all VM::EC2::Volume objects that were derived from this
snapshot. If no volumes currently exist that satisfy this criteria,
returns an empty list, but will not raise an error.
.ie n .SS "$image = $snap\->register_image(%args)"
.el .SS "\f(CW$image\fP = \f(CW$snap\fP\->register_image(%args)"
.IX Subsection "$image = $snap->register_image(%args)"
Register a new \s-1AMI\s0 using this snapshot as the root device. By default,
the root device will be mapped to /dev/sda1 and will delete on
instance termination. You can modify this behavior and add additional
block devices.
.PP
Arguments:
.PP
.Vb 1
\& \-name                 Name for this image (required)
\&
\& \-description          Description of this image
\&
\& \-kernel_id            Kernel for this image (recommended)
\&
\& \-ramdisk_id           Ramdisk for this image
\&
\& \-architecture         Architecture ("i386" or "x86_64")
\&
\& \-root_device_name     Specify the root device based
\&                       on this snapshot (/dev/sda1).
\&
\& \-root_size            Size of the root volume (defaults
\&                       to size of the snapshot).
\&
\& \-root_delete_on_termination   True value (default) to delete
\&                       the root volume after the instance
\&                       terminates. False value to keep the
\&                       EBS volume available.
\&
\& \-block_device_mapping Additional block devices you wish to
\&                       incorporate into the image.
\&
\& \-block_devices        Same as above.
.Ve
.PP
See \s-1VM::EC2\s0 for information on the syntax of the
\&\-block_device_mapping argument. If the root device is explicitly
included in the block device mapping argument, then the arguments
specified in \-root_size, and \-root_delete_on_termination will be
ignored, and the current snapshot will not automatically be used as
the root device.
.PP
The return value is a VM::EC2::Image. You can call its
\&\fIcurrent_status()\fR method to poll its availability:
.PP
.Vb 6
\&  $snap = $ec2\->describe_snapshots(\*(Aqsnap\-123456\*(Aq);
\&  $ami = $snap\->register_image(\-name          => \*(AqMy new image\*(Aq,
\&                               \-kernel_id     => \*(Aqaki\-407d9529\*(Aq,
\&                               \-architecture  => \*(Aqi386\*(Aq,
\&                               \-block_devices => \*(Aq/dev/sdc=ephemeral0\*(Aq
\&  ) or die $ec2\->error_str;
\&
\&  while ($ami\->current_status eq \*(Aqpending\*(Aq) {
\&    print "$ami: ",$ami\->current_status,"\en"
\&    sleep 30;  # takes a long time to register some images
\&  }
\&
\&  print "$ami is ready to go\en";
.Ve
.ie n .SS "$volume = $snap\->create_volume(%args)"
.el .SS "\f(CW$volume\fP = \f(CW$snap\fP\->create_volume(%args)"
.IX Subsection "$volume = $snap->create_volume(%args)"
Create a new volume from this snapshot. Arguments are:
.PP
.Vb 2
\& \-availability_zone    \-\- An availability zone from
\&                          describe_availability_zones (required)
\&
\& \-size                 \-\- Size of the volume, in GB (between 1 and 1024).
.Ve
.PP
If \-size is not provided, then the new volume will have the same size as
the snapshot.
.PP
Optional Arguments:
.PP
.Vb 2
\& \-volume_type          \-\- The volume type.  standard or io1, default is
\&                          standard
\&
\& \-iops                 \-\- The number of I/O operations per second (IOPS) that
\&                          the volume supports.  Range is 100 to 4000.  Required
\&                          when volume type is io1.  IOPS must be 30\-to\-1 ratio
\&                          to size.  ie: 3000 IOPS volume must be at least 100GB.
.Ve
.PP
On success, the returned value is a VM::EC2::Volume object.
.ie n .SS "$status = $snap\->current_status"
.el .SS "\f(CW$status\fP = \f(CW$snap\fP\->current_status"
.IX Subsection "$status = $snap->current_status"
Refreshes the snapshot and returns its current status.
.ie n .SS "$boolean = $snapshot\->is_public"
.el .SS "\f(CW$boolean\fP = \f(CW$snapshot\fP\->is_public"
.IX Subsection "$boolean = $snapshot->is_public"
Return true if the snapshot's createVolume permissions allow the \*(L"all\*(R"
group to create volumes from the snapshot.
.ie n .SS "$boolean = $snapshot\->make_public($public)"
.el .SS "\f(CW$boolean\fP = \f(CW$snapshot\fP\->make_public($public)"
.IX Subsection "$boolean = $snapshot->make_public($public)"
Modify the createVolumePermission attribute to allow the \*(L"all\*(R" group
to create volumes from this snapshot. Provide a true value to make the
snapshot public, a false one to make it private.
.ie n .SS "@user_ids = $snap\->\fIcreateVolumePermissions()\fP"
.el .SS "\f(CW@user_ids\fP = \f(CW$snap\fP\->\fIcreateVolumePermissions()\fP"
.IX Subsection "@user_ids = $snap->createVolumePermissions()"
.ie n .SS "@user_ids = $snap\->authorized_users"
.el .SS "\f(CW@user_ids\fP = \f(CW$snap\fP\->authorized_users"
.IX Subsection "@user_ids = $snap->authorized_users"
Returns a list of user IDs with createVolume permissions for this
snapshot. The result is a list of VM::EC2::Snapshot::CreateVolumePermission
objects, which interpolate as strings corresponding to either the
user \s-1ID,\s0 or the group named \*(L"all.\*(R"
.PP
The two methods are aliases of each other.
.ie n .SS "$boolean = $snap\->add_authorized_users($id1,$id2,...)"
.el .SS "\f(CW$boolean\fP = \f(CW$snap\fP\->add_authorized_users($id1,$id2,...)"
.IX Subsection "$boolean = $snap->add_authorized_users($id1,$id2,...)"
.ie n .SS "$boolean = $snap\->remove_authorized_users($id1,$id2,...)"
.el .SS "\f(CW$boolean\fP = \f(CW$snap\fP\->remove_authorized_users($id1,$id2,...)"
.IX Subsection "$boolean = $snap->remove_authorized_users($id1,$id2,...)"
.ie n .SS "$boolean = $snap\->reset_authorized_users"
.el .SS "\f(CW$boolean\fP = \f(CW$snap\fP\->reset_authorized_users"
.IX Subsection "$boolean = $snap->reset_authorized_users"
These methods add and remove user accounts which have createVolume
permissions for the snapshot. The result code indicates whether the
list of user IDs were successfully added or removed. To add the \*(L"all\*(R"
group, use \fImake_public()\fR.
.PP
\&\fIreset_authorized_users()\fR resets the list users authored to create
volumes from this snapshot to empty, effectively granting volume
creation to the owner only.
.PP
See also \fIauthorized_users()\fR.
.ie n .SS "$size = $snap\->size"
.el .SS "\f(CW$size\fP = \f(CW$snap\fP\->size"
.IX Subsection "$size = $snap->size"
Alias to volumeSize, provided for consistency with
VM::EC2::Volume\->size.
.ie n .SS "$snap\->refresh"
.el .SS "\f(CW$snap\fP\->refresh"
.IX Subsection "$snap->refresh"
Refreshes the snapshot from information provided by \s-1AWS.\s0 Use before
checking progress or other changeable elements.
.ie n .SS "$snapshot_copy = $snapshot\->copy(\-region=>$dest_region, \-description=>$desc)"
.el .SS "\f(CW$snapshot_copy\fP = \f(CW$snapshot\fP\->copy(\-region=>$dest_region, \-description=>$desc)"
.IX Subsection "$snapshot_copy = $snapshot->copy(-region=>$dest_region, -description=>$desc)"
Copies the snapshot to the same or different region.
.PP
Required Argument:
 \-region        The region to copy the snapshot to
.PP
Optional Argument:
 \-description   Description of the new snapshot
.PP
Returns a VM::EC2::Snapshot object if successful.
.SH "STRING OVERLOADING"
.IX Header "STRING OVERLOADING"
When used in a string context, this object will interpolate the
snapshotId.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1VM::EC2\s0
VM::EC2::Generic
VM::EC2::Instance
VM::EC2::Volume
.SH "AUTHOR"
.IX Header "AUTHOR"
Lincoln Stein <lincoln.stein@gmail.com>.
.PP
Copyright (c) 2011 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.