.\" 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::REST::elastic_network_interface 3pm"
.TH VM::EC2::REST::elastic_network_interface 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::REST::elastic_network_interface \- Create and manage Elastic Network Interfaces"
.IX Header "NAME VM::EC2::REST::elastic_network_interface - Create and manage Elastic Network Interfaces"
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use VM::EC2 \*(Aq:vpc\*(Aq;
.Ve
.SH "METHODS"
.IX Header "METHODS"
These methods create and manage Elastic Network Interfaces (\s-1ENI\s0). Once
created, an \s-1ENI\s0 can be attached to instances and/or be associated with
a public \s-1IP\s0 address. ENIs can only be used in conjunction with \s-1VPC\s0
instances.
.PP
Implemented:
 AttachNetworkInterface
 CreateNetworkInterface
 DeleteNetworkInterface
 DescribeNetworkInterfaceAttribute
 DescribeNetworkInterfaces
 DetachNetworkInterface
 ModifyNetworkInterfaceAttribute
 ResetNetworkInterfaceAttribute
.PP
Unimplemented:
 (none)
.ie n .SS "$interface = $ec2\->create_network_interface($subnet_id)"
.el .SS "\f(CW$interface\fP = \f(CW$ec2\fP\->create_network_interface($subnet_id)"
.IX Subsection "$interface = $ec2->create_network_interface($subnet_id)"
.ie n .SS "$interface = $ec2\->create_network_interface(%args)"
.el .SS "\f(CW$interface\fP = \f(CW$ec2\fP\->create_network_interface(%args)"
.IX Subsection "$interface = $ec2->create_network_interface(%args)"
This method creates an elastic network interface (\s-1ENI\s0). If only a
single argument is provided, it is treated as the \s-1ID\s0 of the \s-1VPC\s0 subnet
to associate with the \s-1ENI.\s0 If multiple arguments are provided, they
are treated as \-arg=>value parameter pairs.
.PP
Arguments:
.PP
The \-subnet_id argument is mandatory. Others are optional.
.PP
.Vb 2
\& \-subnet_id           \-\-  ID of the VPC subnet to associate with the network
\&                           interface (mandatory)
\&
\& \-private_ip_address  \-\-  The primary private IP address of the network interface,
\&                           or a reference to an array of private IP addresses. In the
\&                           latter case, the first element of the array becomes the
\&                           primary address, and the subsequent ones become secondary
\&                           addresses. If no private IP address is specified, one will
\&                           be chosen for you. See below for more information on this
\&                           parameter.
\&
\& \-private_ip_addresses \-\- Same as \-private_ip_address, for readability.
\&
\& \-secondary_ip_address_count \-\- An integer requesting this number of secondary IP
\&                          addresses to be allocated automatically. If present, 
\&                          cannot provide any secondary addresses explicitly.
\&
\& \-description          \-\- Description of this ENI.
\&
\& \-security_group_id    \-\- Array reference or scalar containing IDs of the security
\&                           group(s) to assign to this interface.
.Ve
.PP
You can assign multiple \s-1IP\s0 addresses to the interface explicitly, or
by allowing \s-1EC2\s0 to choose addresses within the designated subnet
automatically. The following examples demonstrate the syntax:
.PP
.Vb 2
\& # one primary address, chosen explicitly
\& \-private_ip_address => \*(Aq192.168.0.12\*(Aq
\&
\& # one primary address and two secondary addresses, chosen explicitly
\& \-private_ip_address => [\*(Aq192.168.0.12\*(Aq,\*(Aq192.168.0.200\*(Aq,\*(Aq192.168.0.201\*(Aq] 
\&
\& # one primary address chosen explicitly, and two secondaries chosen automatically
\& \-private_ip_address => [\*(Aq192.168.0.12\*(Aq,\*(Aqauto\*(Aq,\*(Aqauto\*(Aq]
\&
\& # one primary address chosen explicitly, and two secondaries chosen automatically (another syntax)
\& \-private_ip_address => [\*(Aq192.168.0.12\*(Aq,2]
\&
\& # one primary address chosen automatically, and two secondaries chosen automatically
\& \-private_ip_address => [auto,2]
.Ve
.PP
You cannot assign some secondary addresses explicitly and others
automatically on the same \s-1ENI.\s0 If you provide no \-private_ip_address
parameter at all, then a single private \s-1IP\s0 address will be chosen for
you (the same as \-private_ip_address=>'auto').
.PP
The return value is a VM::EC2::NetworkInterface object
.ie n .SS "$result = $ec2\->delete_network_interface($network_interface_id);"
.el .SS "\f(CW$result\fP = \f(CW$ec2\fP\->delete_network_interface($network_interface_id);"
.IX Subsection "$result = $ec2->delete_network_interface($network_interface_id);"
.ie n .SS "$result = $ec2\->delete_network_interface(\-network_interface_id => $id);"
.el .SS "\f(CW$result\fP = \f(CW$ec2\fP\->delete_network_interface(\-network_interface_id => \f(CW$id\fP);"
.IX Subsection "$result = $ec2->delete_network_interface(-network_interface_id => $id);"
Deletes the specified network interface. Returns a boolean indicating
success of the delete operation.
.ie n .SS "@ifs = $ec2\->describe_network_interfaces(@interface_ids)"
.el .SS "\f(CW@ifs\fP = \f(CW$ec2\fP\->describe_network_interfaces(@interface_ids)"
.IX Subsection "@ifs = $ec2->describe_network_interfaces(@interface_ids)"
.ie n .SS "@ifs = $ec2\->describe_network_interfaces(\e%filters)"
.el .SS "\f(CW@ifs\fP = \f(CW$ec2\fP\->describe_network_interfaces(\e%filters)"
.IX Subsection "@ifs = $ec2->describe_network_interfaces(%filters)"
.ie n .SS "@ifs = $ec2\->describe_network_interfaces(\-network_interface_id=>\e@interface_ids,\-filter=>\e%filters)"
.el .SS "\f(CW@ifs\fP = \f(CW$ec2\fP\->describe_network_interfaces(\-network_interface_id=>\e@interface_ids,\-filter=>\e%filters)"
.IX Subsection "@ifs = $ec2->describe_network_interfaces(-network_interface_id=>@interface_ids,-filter=>%filters)"
Return a list of elastic network interfaces as
VM::EC2::VPC::NetworkInterface objects. You may restrict the list by
passing a list of network interface IDs, a hashref of filters or by
using the full named-parameter form.
.PP
Optional arguments:
.PP
.Vb 2
\& \-network_interface_id    A single network interface ID or an arrayref to
\&                           a list of IDs.
\&
\& \-filter                  A hashref for filtering on tags and other attributes.
.Ve
.PP
The list of valid filters can be found at
http://docs.amazonwebservices.com/AWSEC2/latest/APIReference/ApiReference\-query\-DescribeNetworkInterfaces.html.
.ie n .SS "@data = $ec2\->describe_network_interface_attribute($network_id,$attribute)"
.el .SS "\f(CW@data\fP = \f(CW$ec2\fP\->describe_network_interface_attribute($network_id,$attribute)"
.IX Subsection "@data = $ec2->describe_network_interface_attribute($network_id,$attribute)"
This method returns network interface attributes. Only one attribute
can be retrieved at a time. The following is the list of attributes
that can be retrieved:
.PP
.Vb 4
\& description           \-\- hashref
\& groupSet              \-\- hashref
\& sourceDestCheck       \-\- hashref
\& attachment            \-\- hashref
.Ve
.PP
These values can be retrieved more conveniently from the
VM::EC2::NetworkInterface object, so there is no attempt to parse
the results of this call into Perl objects.
.ie n .SS "$boolean = $ec2\->modify_network_interface_attribute($interface_id,\-$attribute_name=>$value)"
.el .SS "\f(CW$boolean\fP = \f(CW$ec2\fP\->modify_network_interface_attribute($interface_id,\-$attribute_name=>$value)"
.IX Subsection "$boolean = $ec2->modify_network_interface_attribute($interface_id,-$attribute_name=>$value)"
This method changes network interface attributes. Only one attribute can be set per call
The following is the list of attributes that can be set:
.PP
.Vb 8
\& \-description             \-\- interface description
\& \-security_group_id       \-\- single security group ID or arrayref to a list of group ids
\& \-source_dest_check       \-\- boolean; if false enables packets to be forwarded, and is necessary
\&                               for NAT and other router tasks
\& \-delete_on_termination   \-\- [$attachment_id=>$delete_on_termination]; Pass this a two\-element
\&                               array reference consisting of the attachment ID and a boolean 
\&                               indicating whether deleteOnTermination should be enabled for
\&                               this attachment.
.Ve
.ie n .SS "$boolean = $ec2\->reset_network_interface_attribute($interface_id => $attribute_name)"
.el .SS "\f(CW$boolean\fP = \f(CW$ec2\fP\->reset_network_interface_attribute($interface_id => \f(CW$attribute_name\fP)"
.IX Subsection "$boolean = $ec2->reset_network_interface_attribute($interface_id => $attribute_name)"
This method resets the named network interface attribute to its
default value. Only one attribute can be reset per call. The \s-1AWS\s0
documentation is not completely clear on this point, but it appears
that the only attribute that can be reset using this method is:
.PP
.Vb 1
\& source_dest_check       \-\- Turns on source destination checking
.Ve
.PP
For consistency with modify_network_interface_attribute, you may
specify attribute names with or without a leading dash, and using
either under_score or mixedCase naming:
.PP
.Vb 3
\& $ec2\->reset_network_interface_atribute(\*(Aqeni\-12345678\*(Aq => \*(Aqsource_dest_check\*(Aq);
\& $ec2\->reset_network_interface_atribute(\*(Aqeni\-12345678\*(Aq => \*(Aq\-source_dest_check\*(Aq);
\& $ec2\->reset_network_interface_atribute(\*(Aqeni\-12345678\*(Aq => sourceDestCheck);
.Ve
.ie n .SS "$attachmentId = $ec2\->attach_network_interface($network_interface_id,$instance_id,$device_index)"
.el .SS "\f(CW$attachmentId\fP = \f(CW$ec2\fP\->attach_network_interface($network_interface_id,$instance_id,$device_index)"
.IX Subsection "$attachmentId = $ec2->attach_network_interface($network_interface_id,$instance_id,$device_index)"
.ie n .SS "$attachmentId = $ec2\->attach_network_interface(\-network_interface_id => $id, \-instance_id          => $id, \-device_index         => $index)"
.el .SS "\f(CW$attachmentId\fP = \f(CW$ec2\fP\->attach_network_interface(\-network_interface_id => \f(CW$id\fP, \-instance_id          => \f(CW$id\fP, \-device_index         => \f(CW$index\fP)"
.IX Subsection "$attachmentId = $ec2->attach_network_interface(-network_interface_id => $id, -instance_id => $id, -device_index => $index)"
This method attaches a network interface to an instance using the
indicated device index. You can use instance and network interface
IDs, or VM::EC2::Instance and VM::EC2::NetworkInterface objects. You
may use an integer for \-device_index, or use the strings \*(L"eth0\*(R",
\&\*(L"eth1\*(R" etc.
.PP
Required arguments:
.PP
.Vb 3
\& \-network_interface_id ID of the network interface to attach.
\& \-instance_id          ID of the instance to attach the interface 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).
.PP
Note that it may be more convenient to attach and detach network
interfaces via methods in the VM::EC2::Instance and
VM::EC2::NetworkInterface objects:
.PP
.Vb 2
\& $instance\->attach_network_interface($interface=>\*(Aqeth0\*(Aq);
\& $interface\->attach($instance=>\*(Aqeth0\*(Aq);
.Ve
.ie n .SS "$boolean = $ec2\->detach_network_interface($attachment_id [,$force])"
.el .SS "\f(CW$boolean\fP = \f(CW$ec2\fP\->detach_network_interface($attachment_id [,$force])"
.IX Subsection "$boolean = $ec2->detach_network_interface($attachment_id [,$force])"
This method detaches a network interface from an instance. Both the
network interface and instance are specified using their
attachmentId. If the \f(CW$force\fR flag is present, and true, then the
detachment will be forced even if the interface is in use.
.PP
Note that it may be more convenient to attach and detach network
interfaces via methods in the VM::EC2::Instance and
VM::EC2::NetworkInterface objects:
.PP
.Vb 2
\& $instance\->detach_network_interface($interface);
\& $interface\->detach();
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1VM::EC2\s0
.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.