.\" 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::Instance 3pm"
.TH VM::EC2::Instance 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::Instance \- Object describing an Amazon EC2 instance
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use VM::EC2;
\&
\&  $ec2      = VM::EC2\->new(...);
\&  $instance = $ec2\->describe_instances(\-instance_id=>\*(Aqi\-12345\*(Aq);
\&
\&  $instanceId    = $instance\->instanceId;
\&  $ownerId       = $instance\->ownerId;
\&  $reservationId = $instance\->reservationId;
\&  $imageId       = $instance\->imageId;
\&  $state         = $instance\->instanceState;
\&  @groups        = $instance\->groups;
\&  $private_ip    = $instance\->privateIpAddress;
\&  $public_ip     = $instance\->ipAddress;
\&  $private_dns   = $instance\->privateDnsName;
\&  $public_dns    = $instance\->dnsName;
\&  $time          = $instance\->launchTime;
\&  $status        = $instance\->current_status;
\&  $tags          = $instance\->tags;
\&
\&  $stateChange = $instance\->start();
\&  $stateChange = $instance\->stop();
\&  $stateChange = $instance\->reboot();
\&  $stateChange = $instance\->terminate();
\&
\&  $seconds       = $instance\->up_time;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This object represents an Amazon \s-1EC2\s0 instance, and is returned by
\&\s-1VM::EC2\-\s0>\fIdescribe_instances()\fR. In addition to methods to query the
instance's attributes, there are methods that allow you to manage the
instance's lifecycle, including start, stopping, and terminating it.
.PP
Note that the information about security groups and reservations that
is returned by \fIdescribe_instances()\fR is copied into each instance
before returning it, so there is no concept of a \*(L"reservation set\*(R" in
this interface.
.SH "METHODS"
.IX Header "METHODS"
These object methods are supported:
.PP
.Vb 1
\& instanceId     \-\- ID of this instance.
\&
\& imageId        \-\- ID of the image used to launch this instance.
\&
\& instanceState  \-\- The current state of the instance at the time
\&                   that describe_instances() was called, as a
\&                   VM::EC2::Instance::State object. Also
\&                   see the status() method, which re\-queries EC2 for
\&                   the current state of the instance. States are
\&                   represented in strings as  "terminated", "running", 
\&                   "stopped", "stopping",and "shutting\-down".
\&
\& privateDnsName \-\- The private DNS name assigned to the instance within
\&                   Amazon\*(Aqs EC2 network. This element is defined only
\&                   for running instances.
\&
\& dnsName        \-\- The public DNS name assigned to the instance, defined
\&                   only for running instances.
\&
\& reason         \-\- Reason for the most recent state transition, 
\&                   if applicable.
\&
\& keyName        \-\- Name of the associated key pair, if applicable.
\&
\& keyPair        \-\- The VM::EC2::KeyPair object, derived from the keyName
\&
\& amiLaunchIndex \-\- The AMI launch index, which can be used to find
\&                   this instance within the launch group.
\&
\& productCodes   \-\- A list of product codes that apply to this instance.
\&
\& instanceType   \-\- The instance type, such as "t1.micro". CHANGEABLE.
\&
\& launchTime     \-\- The time the instance launched.
\&
\& placement      \-\- The placement of the instance. Returns a
\&                   VM::EC2::Instance::Placement object, which when used
\&                   as a string is equal to the instance\*(Aqs
\&                   availability zone.
\&
\& availabilityZone \-\- Same as placement.
\&
\& kernelId       \-\- ID of the instance\*(Aqs kernel. CHANGEABLE.
\&
\& ramdiskId      \-\- ID of the instance\*(Aqs RAM disk. CHANGEABLE.
\&
\& platform       \-\- Platform of the instance, either "windows" or empty.
\&
\& monitoring     \-\- State of monitoring for the instance. One of 
\&                   "disabled", "enabled", or "pending". CHANGEABLE:
\&                   pass true or "enabled" to turn on monitoring. Pass
\&                   false or "disabled" to turn it off.
\&
\& subnetId       \-\- The Amazon VPC subnet ID in which the instance is 
\&                   running, for Virtual Private Cloud instances only.
\&
\& vpcId          \-\- The Virtual Private Cloud ID for VPC instances.
\&
\& privateIpAddress \-\- The private (internal Amazon) IP address assigned
\&                   to the instance.
\&
\& ipAddress      \-\- The public IP address of the instance.
\&
\& sourceDestCheck \-\- Whether source destination checking is enabled on
\&                   this instance. This returns a Perl boolean rather than
\&                   the string "true". This method is used in conjunction
\&                   with VPC NAT functionality. See the Amazon VPC User
\&                   Guide for details. CHANGEABLE.
\&
\& networkInterfaceSet \-\- Return list of VM::EC2::ElasticNetworkInterface objects
\&                   attached to this instance.
\&
\& iamInstanceProfile \-\- The IAM instance profile (IIP) associated with this instance.
\&
\& ebsOptimized       \-\- True if instance is optimized for EBS I/O.
\&
\& groupSet       \-\- List of VM::EC2::Group objects indicating the VPC
\&                   security groups in which this instance resides. Not to be
\&                   confused with groups(), which returns the security groups
\&                   of non\-VPC instances. 
\&
\& stateReason    \-\- A VM::EC2::Instance::State::Reason object which
\&                   indicates the reason for the instance\*(Aqs most recent
\&                   state change. See http://docs.amazonwebservices.com/AWSEC2/latest/APIReference/ApiReference\-ItemType\-StateReasonType.html
\&
\& architecture   \-\- The architecture of the image. Either "i386" or "x86_64".
\&
\& rootDeviceType \-\- The type of the root device used by the instance. One of "ebs"
\&                   or "instance\-store".
\&
\& rootDeviceName \-\- The name of the the device used by the instance, such as /dev/sda1.
\&                   CHANGEABLE.
\&
\& blockDeviceMapping \-\- The block device mappings for the instance, represented
\&                   as a list of L<VM::EC2::BlockDevice::Mapping> objects.
\&
\& instanceLifeCycle \-\- "spot" if this instance is a spot instance, otherwise empty.
\&
\& spotInstanceRequestId \-\- The ID of the spot instance request, if applicable.
\&
\& virtualizationType \-\- Either "paravirtual" or "hvm".
\&
\& clientToken    \-\- The idempotency token provided at the time of the AMI launch,
\&                   if any.
\&
\& hypervisor     \-\- The instance\*(Aqs hypervisor type, either "ovm" or "xen".
\&
\& userData       \-\- User data passed to instance at launch. CHANGEABLE.
\&
\& disableApiTermination \-\- True if the instance is protected from termination
\&                   via the console or command\-line APIs. CHANGEABLE.
\&
\& instanceInitiatedShutdownBehavior \-\- Action to take when the instance calls
\&                   shutdown or halt. One of "stop" or "terminate". CHANGEABLE.
\&
\& sriovNetSupport \-\- Specifies whether enhanced networking is enabled.  "simple" if so.
\&
\& tagSet         \-\- Tags for the instance as a hashref. CHANGEABLE via add_tags()
\&                   and delete_tags().
.Ve
.PP
The object also supports the \fItags()\fR method described in
VM::EC2::Generic:
.PP
.Vb 1
\& print "ready for production\en" if $image\->tags\->{Released};
.Ve
.PP
All methods return read-only values except for those marked \s-1CHANGEABLE\s0
in the list above. For these, you can change the instance attribute on
stopped instances by invoking the method with an appropriate new
value. For example, to change the instance type from \*(L"t1.micro\*(R" to
\&\*(L"m1.small\*(R", you can do this:
.PP
.Vb 5
\& my @tiny_instances = $ec2\->describe_instances(\-filter=>{\*(Aqinstance\-type\*(Aq=>\*(Aqt1.micro\*(Aq});
\& for my $i (@tiny_instances) {
\&    next unless $i\->instanceState eq \*(Aqstopped\*(Aq;
\&    $i\->instanceType(\*(Aqm1.small\*(Aq) or die $ec2\->error;
\& }
.Ve
.PP
When you attempt to change an attribute of an instance, the method
will return true on success, false on failure. On failure, the
detailed error messages can be recovered from the \s-1VM::EC2\s0 object's
\&\fIerror()\fR method.
.SH "LIFECYCLE METHODS"
.IX Header "LIFECYCLE METHODS"
In addition, the following convenience functions are provided
.ie n .SS "$state = $instance\->current_status"
.el .SS "\f(CW$state\fP = \f(CW$instance\fP\->current_status"
.IX Subsection "$state = $instance->current_status"
This method queries \s-1AWS\s0 for the instance's current state and returns
it as a VM::EC2::Instance::State object. This enables you to 
poll the instance until it is in the desired state:
.PP
.Vb 1
\& while ($instance\->current_status eq \*(Aqpending\*(Aq) { sleep 5 }
.Ve
.ie n .SS "$state = $instance\->current_state"
.el .SS "\f(CW$state\fP = \f(CW$instance\fP\->current_state"
.IX Subsection "$state = $instance->current_state"
An alias for \fIcurrent_status()\fR.
.ie n .SS "$state_change = $instance\->start([$wait])"
.el .SS "\f(CW$state_change\fP = \f(CW$instance\fP\->start([$wait])"
.IX Subsection "$state_change = $instance->start([$wait])"
This method will start the current instance and returns a
VM::EC2::Instance::State::Change object that can be used to
monitor the status of the instance. By default the method returns
immediately, but you can pass a true value as an argument in order to
pause execution until the instance is in the \*(L"running\*(R" state.
.PP
Here's a polling example:
.PP
.Vb 2
\&  $state = $instance\->start;
\&  while ($state\->status eq \*(Aqpending\*(Aq) { sleep 5 }
.Ve
.PP
Here's an example that will pause until the instance is running:
.PP
.Vb 1
\&  $instance\->start(1);
.Ve
.PP
Attempting to start an already running instance, or one that is
in transition, will throw a fatal error.
.ie n .SS "$state_change = $instance\->stop([$wait])"
.el .SS "\f(CW$state_change\fP = \f(CW$instance\fP\->stop([$wait])"
.IX Subsection "$state_change = $instance->stop([$wait])"
This method is similar to \fIstart()\fR, except that it can be used to
stop a running instance.
.ie n .SS "$state_change = $instance\->terminate([$wait])"
.el .SS "\f(CW$state_change\fP = \f(CW$instance\fP\->terminate([$wait])"
.IX Subsection "$state_change = $instance->terminate([$wait])"
This method is similar to \fIstart()\fR, except that it can be used to
terminate an instance. It can only be called on instances that
are either \*(L"running\*(R" or \*(L"stopped\*(R".
.ie n .SS "$state_change = $instance\->\fIreboot()\fP"
.el .SS "\f(CW$state_change\fP = \f(CW$instance\fP\->\fIreboot()\fP"
.IX Subsection "$state_change = $instance->reboot()"
Reboot the instance. Rebooting doesn't occur immediately; instead the
request is queued by the Amazon system and may be satisfied several
minutes later. For this reason, there is no \*(L"wait\*(R" argument.
.ie n .SS "$seconds = $instance\->\fIup_time()\fP"
.el .SS "\f(CW$seconds\fP = \f(CW$instance\fP\->\fIup_time()\fP"
.IX Subsection "$seconds = $instance->up_time()"
Return the number of seconds since the instance was launched. Note
that this includes time that the instance was either in the \*(L"running\*(R"
or \*(L"stopped\*(R" state.
.ie n .SS "$result = $instance\->associate_address($elastic_address)"
.el .SS "\f(CW$result\fP = \f(CW$instance\fP\->associate_address($elastic_address)"
.IX Subsection "$result = $instance->associate_address($elastic_address)"
Associate an elastic address with this instance. If you are
associating a \s-1VPC\s0 elastic \s-1IP\s0 address with the instance, the result
code will indicate the associationId. Otherwise it will be a simple
perl truth value (\*(L"1\*(R") if successful, undef if false.
.PP
In the case of an ordinary \s-1EC2\s0 Elastic \s-1IP\s0 address, the first argument may
either be an ordinary string (xx.xx.xx.xx format) or a
VM::EC2::ElasticAddress object. However, if it is a \s-1VPC\s0 elastic
\&\s-1IP\s0 address, then the argument must be a VM::EC2::ElasticAddress
as returned by \fIdescribe_addresses()\fR. The reason for this is that the
allocationId must be retrieved from the object in order to use in the
call.
.ie n .SS "$bool = $instance\->disassociate_address"
.el .SS "\f(CW$bool\fP = \f(CW$instance\fP\->disassociate_address"
.IX Subsection "$bool = $instance->disassociate_address"
Disassociate an elastic \s-1IP\s0 address from this instance. if any. The
result will be true if disassociation was successful. Note that for a
short period of time (up to a few minutes) after disassociation, the
instance will have no public \s-1IP\s0 address and will be unreachable from
the internet.
.ie n .SS "@list = $instance\->network_interfaces"
.el .SS "\f(CW@list\fP = \f(CW$instance\fP\->network_interfaces"
.IX Subsection "@list = $instance->network_interfaces"
Return the network interfaces attached to this instance as a set of
VM::EC2::NetworkInterface objects (\s-1VPC\s0 only).
.ie n .SS "$instance\->refresh"
.el .SS "\f(CW$instance\fP\->refresh"
.IX Subsection "$instance->refresh"
This method will refresh the object from \s-1AWS,\s0 updating all values to
their current ones. You can call it after starting an instance in
order to get its \s-1IP\s0 address. Note that \fIrefresh()\fR is called
automatically for you if you call \fIstart()\fR, \fIstop()\fR or \fIterminate()\fR with
a true \f(CW$wait\fR argument.
.ie n .SS "$text = $instance\->console_output"
.el .SS "\f(CW$text\fP = \f(CW$instance\fP\->console_output"
.IX Subsection "$text = $instance->console_output"
Return the console output of the instance as a
VM::EC2::ConsoleOutput object. This object can be treated as a
string, or as an object with methods
.SH "CREATING IMAGES"
.IX Header "CREATING IMAGES"
The \fIcreate_image()\fR method provides a handy way of creating and
registering an \s-1AMI\s0 based on the current state of the instance. All
currently-associated block devices will be snapshotted and associated
with the image.
.PP
Note that this operation can take a long time to complete. You may
follow its progress by calling the returned image object's
\&\fIcurrent_status()\fR method.
.SS "create_image($name [,$description])"
.IX Subsection "create_image($name [,$description])"
\&\f(CW$imageId\fR = \f(CW$instance\fR\->create_image($name [,$description])
.SS "create_image(name,description,no_reboot)"
.IX Subsection "create_image(name,description,no_reboot)"
\&\f(CW$imageId\fR = \f(CW$instance\fR\->create_image(\-name=>$name,\-description=>$description,\-no_reboot=>$boolean)
.PP
Create an image from this instance and return a VM::EC2::Image object.
The instance must be in the \*(L"stopped\*(R" or \*(L"running\*(R" state. In the
latter case, Amazon will stop the instance, create the image, and then
restart it unless the \-no_reboot argument is provided.
.PP
Arguments:
.PP
.Vb 3
\& \-name           Name for the image that will be created. (required)
\& \-description    Description of the new image.
\& \-no_reboot      If true, don\*(Aqt reboot the instance.
.Ve
.PP
In the unnamed argument version you can provide the name and
optionally the description of the resulting image.
.ie n .SS "$boolean = $instance\->confirm_product_code($product_code)"
.el .SS "\f(CW$boolean\fP = \f(CW$instance\fP\->confirm_product_code($product_code)"
.IX Subsection "$boolean = $instance->confirm_product_code($product_code)"
Return true if this instance is associated with the given product code.
.SH "VOLUME MANAGEMENT"
.IX Header "VOLUME MANAGEMENT"
.ie n .SS "$attachment = $instance\->attach_volume($volume_id,$device)"
.el .SS "\f(CW$attachment\fP = \f(CW$instance\fP\->attach_volume($volume_id,$device)"
.IX Subsection "$attachment = $instance->attach_volume($volume_id,$device)"
.ie n .SS "$attachment = $instance\->attach_volume(\-volume_id=>$volume_id,\-device=>$device)"
.el .SS "\f(CW$attachment\fP = \f(CW$instance\fP\->attach_volume(\-volume_id=>$volume_id,\-device=>$device)"
.IX Subsection "$attachment = $instance->attach_volume(-volume_id=>$volume_id,-device=>$device)"
Attach volume \f(CW$volume_id\fR to this instance using virtual device
\&\f(CW$device\fR. Both arguments are required. The result is a
VM::EC2::BlockDevice::Attachment object which you can monitor by
calling \fIcurrent_status()\fR:
.PP
.Vb 5
\&    my $a = $instance\->attach_volume(\*(Aqvol\-12345\*(Aq=>\*(Aq/dev/sdg\*(Aq);
\&    while ($a\->current_status ne \*(Aqattached\*(Aq) {
\&       sleep 2;
\&    }
\&    print "volume is ready to go\en";
.Ve
.ie n .SS "$attachment = $instance\->detach_volume($vol_or_device)"
.el .SS "\f(CW$attachment\fP = \f(CW$instance\fP\->detach_volume($vol_or_device)"
.IX Subsection "$attachment = $instance->detach_volume($vol_or_device)"
.ie n .SS "$attachment = $instance\->detach_volume(\-volume_id => $volume_id \-device    => $device, \-force     => $force);"
.el .SS "\f(CW$attachment\fP = \f(CW$instance\fP\->detach_volume(\-volume_id => \f(CW$volume_id\fP \-device    => \f(CW$device\fP, \-force     => \f(CW$force\fP);"
.IX Subsection "$attachment = $instance->detach_volume(-volume_id => $volume_id -device => $device, -force => $force);"
Detaches the specified volume. In the single-argument form, you may
provide either a volume or a device name. In the named-argument form,
you may provide both the volume and the device as a check that you are
detaching exactly the volume you think you are.
.PP
Optional arguments:
.PP
.Vb 4
\& \-volume_id      \-\- ID of the instance to detach from.
\& \-device         \-\- How the device is exposed to the instance.
\& \-force          \-\- Force detachment, even if previous attempts were
\&                    unsuccessful.
.Ve
.PP
The result is a VM::EC2::BlockDevice::Attachment object which
you can monitor by calling \fIcurrent_status()\fR:
.PP
.Vb 5
\&    my $a = $instance\->detach_volume(\*(Aq/dev/sdg\*(Aq);
\&    while ($a\->current_status ne \*(Aqdetached\*(Aq) {
\&       sleep 2;
\&    }
\&    print "volume is ready to go\en";
.Ve
.SH "NETWORK INTERFACE MANAGEMENT"
.IX Header "NETWORK INTERFACE MANAGEMENT"
.ie n .SS "$attachment_id = $instance\->attach_network_interface($interface_id => $device)"
.el .SS "\f(CW$attachment_id\fP = \f(CW$instance\fP\->attach_network_interface($interface_id => \f(CW$device\fP)"
.IX Subsection "$attachment_id = $instance->attach_network_interface($interface_id => $device)"
.ie n .SS "$attachment_id = $instance\->attach_network_interface(\-network_interface_id=>$id, \-device_index   => $device)"
.el .SS "\f(CW$attachment_id\fP = \f(CW$instance\fP\->attach_network_interface(\-network_interface_id=>$id, \-device_index   => \f(CW$device\fP)"
.IX Subsection "$attachment_id = $instance->attach_network_interface(-network_interface_id=>$id, -device_index => $device)"
This method attaches a network interface to the current instance using
the indicated device index. You can use either an elastic network
interface \s-1ID,\s0 or a VM::EC2::NetworkInterface object. You may use an
integer for \-device_index, or use the strings \*(L"eth0\*(R", \*(L"eth1\*(R" etc.
.PP
Required arguments:
.PP
.Vb 2
\& \-network_interface_id ID of the network interface to attach.
\& \-device_index         Network device number to use (e.g. 0 for eth0).
.Ve
.PP
On success, this method returns the attachmentId of the new attachment
(not a VM::EC2::NetworkInterface::Attachment object, due to an \s-1AWS API\s0
inconsistency).
.ie n .SS "$boolean = $instance\->detach_network_interface($interface_id [,$force])"
.el .SS "\f(CW$boolean\fP = \f(CW$instance\fP\->detach_network_interface($interface_id [,$force])"
.IX Subsection "$boolean = $instance->detach_network_interface($interface_id [,$force])"
This method detaches a network interface from the current instance. If
a true second argument is provided, then the detachment will be
forced, even if the interface is in use.
.PP
On success, this method returns a true value.
.SH "ACCESSING INSTANCE METADATA"
.IX Header "ACCESSING INSTANCE METADATA"
.ie n .SS "$meta = $instance\->metadata"
.el .SS "\f(CW$meta\fP = \f(CW$instance\fP\->metadata"
.IX Subsection "$meta = $instance->metadata"
\&\fBFor use on running \s-1EC2\s0 instances only:\fR This method returns a
VM::EC2::Instance::Metadata object that will return information about
the currently running instance using the \s-1HTTP://\s0 metadata fields
described at
http://docs.amazonwebservices.com/AWSEC2/latest/UserGuide/index.html?instancedata\-data\-categories.html. This
is usually fastest way to get runtime information on the current
instance.
.SH "STRING OVERLOADING"
.IX Header "STRING OVERLOADING"
When used in a string context, this object will interpolate the
instanceId.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1VM::EC2\s0
VM::EC2::Generic
VM::EC2::BlockDevice
VM::EC2::Instance::State
VM::EC2::Instance::State::Reason
VM::EC2::Instance::Metadata
VM::EC2::Instance::Placement
VM::EC2::Tag
.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.