VM::EC...erface(3pm)

💖 NAME 💖

VM::EC2::REST::elastic_network_interface — bestie, this is the module where you create and manage Elastic Network Interfaces. Periodt. 🦋

---

✨ SYNOPSIS ✨

use VM::EC2 ':vpc';

---

🎀 METHODS 🎀

okay so these methods are the entire girlboss toolkit for creating and managing Elastic Network Interfaces (ENI). Once an ENI exists, it can be attached to instances and/or be associated with a public IP address. Huge caveat tho: ENIs can only be used in conjunction with VPC instances. That's the rule, no cap. 💅

Implemented:

• AttachNetworkInterface
• CreateNetworkInterface
• DeleteNetworkInterface
• DescribeNetworkInterfaceAttribute
• DescribeNetworkInterfaces
• DetachNetworkInterface
• ModifyNetworkInterfaceAttribute
• ResetNetworkInterfaceAttribute

Unimplemented:

• (none)

---

🌸 $interface = $ec2->create_network_interface($subnet_id)

🌸 $interface = $ec2->create_network_interface(%args)

This one creates an elastic network interface (ENI), iconic behaviour honestly. If you hand it just one single argument, it treats that as the ID of the VPC subnet to associate with the ENI. If you hand it multiple arguments, it treats them as -arg=>value parameter pairs. Pick your lane, both slay.

Arguments:

The -subnet_id argument is mandatory. Everything else is optional, do with that what you will. ✨

• -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 that 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. Scroll down for more info on this parameter, iykyk.
• -private_ip_addresses — Same as -private_ip_address, just for readability.
• -secondary_ip_address_count — An integer requesting this number of secondary IP addresses to be allocated automatically. If present, you cannot provide any secondary addresses explicitly. Choose one, bestie, not both.
• -description — Description of this ENI.
• -security_group_id — Array reference or scalar containing IDs of the security group(s) to assign to this interface.

You can assign multiple IP addresses to the interface explicitly, or you can let EC2 choose addresses within the designated subnet automatically. The following examples demonstrate the syntax:

# one primary address, chosen explicitly
-private_ip_address => '192.168.0.12'

# one primary address and two secondary addresses, chosen explicitly
-private_ip_address => ['192.168.0.12','192.168.0.200','192.168.0.201']

# one primary address chosen explicitly, and two secondaries chosen automatically
-private_ip_address => ['192.168.0.12','auto','auto']

# one primary address chosen explicitly, and two secondaries chosen automatically (another syntax)
-private_ip_address => ['192.168.0.12',2]

# one primary address chosen automatically, and two secondaries chosen automatically
-private_ip_address => [auto,2]

🚫 You cannot assign some secondary addresses explicitly and others automatically on the same ENI. Not allowed. Pick a vibe.

If you provide no -private_ip_address parameter at all, then a single private IP address will be chosen for you — same energy as -private_ip_address=>'auto'. 🫶

The return value is a VM::EC2::NetworkInterface object.

---

💫 $result = $ec2->delete_network_interface($network_interface_id);

💫 $result = $ec2->delete_network_interface(-network_interface_id => $id);

Deletes the specified network interface. Returns a boolean indicating success of the delete operation. Simple, clean, bye bye. 👋

---

🦋 @ifs = $ec2->describe_network_interfaces(@interface_ids)

🦋 @ifs = $ec2->describe_network_interfaces(\%filters)

🦋 @ifs = $ec2->describe_network_interfaces(-network_interface_id=>\@interface_ids,-filter=>\%filters)

Returns 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. Three doors, all valid. 💖

Optional arguments:

• -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.

The list of valid filters can be found at http://docs.amazonwebservices.com/AWSEC2/latest/APIReference/ApiReference-query-DescribeNetworkInterfaces.html.

---

🔥 @data = $ec2->describe_network_interface_attribute($network_id,$attribute)

This method returns network interface attributes. Only one attribute can be retrieved at a time — greedy behaviour not supported here. The following is the list of attributes that can be retrieved:

• description — hashref
• groupSet — hashref
• sourceDestCheck — hashref
• attachment — hashref

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. Just so you know. 🙈

---

💜 $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:

• -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.

---

🌈 $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 AWS documentation is not completely clear on this point, but it appears that the only attribute that can be reset using this method is:

• source_dest_check — Turns on source destination checking

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:

$ec2->reset_network_interface_atribute('eni-12345678' => 'source_dest_check');
$ec2->reset_network_interface_atribute('eni-12345678' => '-source_dest_check');
$ec2->reset_network_interface_atribute('eni-12345678' => sourceDestCheck);

---

⭐ $attachmentId = $ec2->attach_network_interface($network_interface_id,$instance_id,$device_index)

⭐ $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 "eth0", "eth1" etc. Whichever feels right. ✨

Required arguments:

• -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).

On success, this method returns the attachmentId of the new attachment (not a VM::EC2::NetworkInterface::Attachment object, due to an AWS API inconsistency). Blame AWS, not us. 💀

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:

$instance->attach_network_interface($interface=>'eth0');
$interface->attach($instance=>'eth0');

---

🍓 $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 $force flag is present, and true, then the detachment will be forced even if the interface is in use. Aggressive, but sometimes you gotta. 💅

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:

$instance->detach_network_interface($interface);
$interface->detach();

---

👑 SEE ALSO 👑

VM::EC2

---

🌸 AUTHOR 🌸

Lincoln Stein <lincoln.stein@gmail.com>.

Copyright (c) 2011 Ontario Institute for Cancer Research

This package and its accompanying libraries is free software; you can redistribute it and/or modify it under the terms of the GPL (either version 1, or at your option, any later version) or the Artistic License 2.0. Refer to LICENSE for the full license text. In addition, please see DISCLAIMER.txt for disclaimers of warranty.

---

okay that's the whole page bestie, no notes 🫶 — this was perl v5.38.2, dated 2024-08-10, and yeah the manpage name got squished to VM::EC...erface(3pm) up in the header. iconic. 💖