.\" 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::NetworkInterface 3pm"
.TH VM::EC2::NetworkInterface 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::NetworkInterface \- Object describing an Amazon Elastic Network Interface (ENI)
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 9
\&  use VM::EC2;
\&  my $ec2 = VM::EC2\->new(...);
\&  my $interface = $ec2\->describe_network_interfaces(\*(Aqeni\-12345\*(Aq);
\&  print $interface\->subNetId,"\en",
\&        $interface\->description,"\en",
\&        $interface\->vpcId,"\en",
\&        $interface\->status,"\en",
\&        $interface\->privateIpAddress,"\en",
\&        $interface\->macAddress,"\en";
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This object provides access to information about Amazon Elastic
Network Interface objects, which are used in conjunction with virtual
private cloud (\s-1VPC\s0) instances to create multi-homed web servers,
routers, firewalls, and so forth.
.PP
Please see VM::EC2::Generic for methods shared by all \s-1VM::EC2\s0
objects.
.SH "METHODS"
.IX Header "METHODS"
These object methods are supported:
.PP
.Vb 10
\& networkInterfaceId       \-\- The ID of this ENI
\& subnetId                 \-\- The ID of the subnet this ENI belongs to
\& vpcId                    \-\- The ID of the VPC this ENI belongs to
\& ownerId                  \-\- Owner of the ENI
\& status                   \-\- ENI status, one of "available" or "in\-use"
\& privateIpAddress         \-\- Primary private IP address of the ENI
\& privateDnsName           \-\- Primary private DNS name of the ENI
\&                             as a set of VM::EC2::Group objects.
\& attachment               \-\- Information about the attachment of this ENI to
\&                             an instance, as a VM::EC2::NetworkInterface::Attachment
\&                             object.
\& association              \-\- Information about the association of this ENI with
\&                             an elastic public IP address.
\& privateIpAddresses       \-\- List of private IP addresses assigned to this ENI,
\&                             as a list of VM::EC2::NetworkInterface::PrivateIpAddress
\&                             objects.
\& availabilityZone         \-\- Availability zone for this ENI as a VM::EC2::AvailabilityZone
\&                             object.
\& macAddress               \-\- MAC address for this interface.
.Ve
.PP
In addition, this object supports the following convenience methods:
.PP
.Vb 2
\& resetAttributes()          \-\- Return attributes to their default states. Currently only
\&                               sets the SourceDestCheck value to true.
\&
\& description([$new_value])  \-\- Description of the ENI. Pass a single argument to set a new
\&                               description
\&
\& sourceDestCheck([$boolean])\-\- Boolean value. If true, prevent this ENI from
\&                               forwarding packets between subnets. Value can optionally
\&                               be set
\&
\& security_groups([@new_groups]) \-\- List of security groups this ENI belongs to. Pass a
\&                               list of new security groups to change this value.
\&
\& delete_on_termination([$boolean])
\&                            \-\- Whether the deleteOnTermination flag is set for the current
\&                               attachment. Pass a boolean value to change the value.
.Ve
.SH "Attaching to an instance"
.IX Header "Attaching to an instance"
The following methods allow the interface to be attached to, and
detached from, instances.
.ie n .SS "$attachment_id = $interface\->attach($instance_id => $device)"
.el .SS "\f(CW$attachment_id\fP = \f(CW$interface\fP\->attach($instance_id => \f(CW$device\fP)"
.IX Subsection "$attachment_id = $interface->attach($instance_id => $device)"
.ie n .SS "$attachment_id = $interfacee\->attach(\-instance_id    => $id, \-device_index   => $device)"
.el .SS "\f(CW$attachment_id\fP = \f(CW$interfacee\fP\->attach(\-instance_id    => \f(CW$id\fP, \-device_index   => \f(CW$device\fP)"
.IX Subsection "$attachment_id = $interfacee->attach(-instance_id => $id, -device_index => $device)"
This method attaches the network interface an instance using the the
indicated device index. You can provide either an instance \s-1ID,\s0 or a
VM::EC2::Instance 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
\& \-instance_id          ID of the instance to attach to.
\& \-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 = $interface\->detach([$force])"
.el .SS "\f(CW$boolean\fP = \f(CW$interface\fP\->detach([$force])"
.IX Subsection "$boolean = $interface->detach([$force])"
This method detaches the network interface from whatever instance it
is currently attached to. If a true 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 "Adding IP addresses"
.IX Header "Adding IP addresses"
.ie n .SS "$result = $interface\->assign_private_ip_addresses(@addresses)"
.el .SS "\f(CW$result\fP = \f(CW$interface\fP\->assign_private_ip_addresses(@addresses)"
.IX Subsection "$result = $interface->assign_private_ip_addresses(@addresses)"
.ie n .SS "$result = $interface\->assign_private_ip_addresses(%args)"
.el .SS "\f(CW$result\fP = \f(CW$interface\fP\->assign_private_ip_addresses(%args)"
.IX Subsection "$result = $interface->assign_private_ip_addresses(%args)"
Assign one or more secondary private \s-1IP\s0 addresses to the network
interface. You can either set the addresses explicitly, or provide a
count of secondary addresses, and let Amazon select them for you.
.PP
In the list argument form, pass a list of desired \s-1IP\s0 addresses, or a
count of the number of addresses to select for you:
.PP
.Vb 2
\& $interface\->assign_private_ip_addresses(3);  # three automatic addresses
\& $interface\->assign_private_ip_addresses(\*(Aq192.168.0.10\*(Aq,\*(Aq192.168.0.11\*(Aq);
.Ve
.PP
Required arguments:
.PP
.Vb 2
\& \-private_ip_address      One or more secondary IP addresses, as a scalar string
\& \-private_ip_addresses    or array reference. (The two arguments are equivalent).
.Ve
.PP
Optional arguments:
.PP
.Vb 2
\& \-allow_reassignment      If true, allow assignment of an IP address is already in
\&                          use by another network interface or instance.
.Ve
.PP
The following are valid arguments to \-private_ip_address:
.PP
.Vb 3
\& \-private_ip_address => \*(Aq192.168.0.12\*(Aq                    # single address
\& \-private_ip_address => [\*(Aq192.168.0.12\*(Aq,\*(Aq192.168.0.13]    # multiple addresses
\& \-private_ip_address => 3                                 # autoselect three addresses
.Ve
.PP
The mixed form of address, such as ['192.168.0.12','auto'] is not allowed in this call.
.PP
On success, this method returns true.
.ie n .SS "$result = $interface\->unassign_private_ip_addresses(@addresses)"
.el .SS "\f(CW$result\fP = \f(CW$interface\fP\->unassign_private_ip_addresses(@addresses)"
.IX Subsection "$result = $interface->unassign_private_ip_addresses(@addresses)"
.ie n .SS "$result = $interface\->unassign_private_ip_addresses(\-private_ip_address => \e@addresses)"
.el .SS "\f(CW$result\fP = \f(CW$interface\fP\->unassign_private_ip_addresses(\-private_ip_address => \e@addresses)"
.IX Subsection "$result = $interface->unassign_private_ip_addresses(-private_ip_address => @addresses)"
Unassign one or more secondary private \s-1IP\s0 addresses from the network
interface.
.PP
In the list argument form, pass a list of desired \s-1IP\s0 addresses to unassign.
.PP
.Vb 1
\& $interface\->assign_private_ip_addresses(\*(Aq192.168.0.10\*(Aq,\*(Aq192.168.0.11\*(Aq);
.Ve
.PP
In the named argument form, use:
.PP
.Vb 2
\& \-private_ip_address      One or more secondary IP addresses, as a scalar string
\& \-private_ip_addresses    or array reference. (The two arguments are equivalent).
.Ve
.PP
The following are valid arguments to \-private_ip_address:
.PP
.Vb 2
\& \-private_ip_address => \*(Aq192.168.0.12\*(Aq                    # single address
\& \-private_ip_address => [\*(Aq192.168.0.12\*(Aq,\*(Aq192.168.0.13]    # multiple addresses
.Ve
.PP
On success, this method returns true.
.SH "STRING OVERLOADING"
.IX Header "STRING OVERLOADING"
When used in a string context, this object will be interpolated as the
networkInterfaceId
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1VM::EC2\s0
VM::EC2::Generic
VM::EC2::NetworkInterface
VM::EC2::NetworkInterface::Attachment
VM::EC2::NetworkInterface::Association
.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.