how to create an eni, how to attach an eni, how to configure an eni, how to use an eni for public and private network communication - Elastic Compute Service

Create an ENI

Console

In the ECS console, go to the ENIs page and click Create an ENI.
Configure the following key parameters and keep the defaults for the rest:
- VPC and vSwitch: The network where the ENI resides.
  The ENI and instance must be in the same VPC and vSwitch.
- Security Group: Associate one or more security groups to control inbound and outbound traffic.

API

Call CreateNetworkInterface to create an ENI.

Attach an ENI to an ECS instance

When you create an instance, you can specify an existing ENI as the primary or secondary ENI. The instance inherits the ENI's network configuration, such as its IP address, routes, MAC address, and security groups.

When you attach an ENI to an existing instance, it can only be a secondary ENI. This expands the instance's networking capabilities, such as traffic isolation or additional IP addresses.

The number of ENIs that can be attached to an instance varies by instance family.

Prerequisites

The ENI and instance are in the same VPC and vSwitch.

Some instance types require stopping the instance before attaching an ENI.

ECS instance types that do not support the hot swapping feature of secondary ENIs

Instance family	Instance type
s6, shared standard instance family	ecs.s6-c1m1.small, ecs.s6-c1m2.large, ecs.s6-c1m2.small, ecs.s6-c1m4.large, and ecs.s6-c1m4.small
e, economy instance family	ecs.e-c1m1.large, ecs.e-c1m2.large, ecs.e-c1m4.large, ecs.e-c4m1.large, and ecs.e-c2m1.large
t6, burstable instance family	ecs.t6-c1m1.large, ecs.t6-c1m2.large, ecs.t6-c1m4.large, ecs.t6-c2m1.large, and ecs.t6-c4m1.large
t5, burstable instance family	ecs.t5-c1m1.large, ecs.t5-c1m2.large, ecs.t5-c1m4.large, ecs.t5-lc1m1.small, ecs.t5-lc1m2.large, ecs.t5-lc1m2.small, ecs.t5-lc1m4.large, and ecs.t5-lc2m1.nano
xn4, n4, mn4, and e4, previous-generation shared instance families	ecs.xn4.small ecs.n4.small and ecs.n4.large ecs.mn4.small and ecs.mn4.large ecs.e4.small and ecs.e4.large

Attach an ENI when creating an instance

Console

Important

If you select an existing security group or create a new one, the system creates a new primary ENI automatically. You cannot attach an existing ENI in this case.

Go to the Custom Launch page in the ECS console.
Select a Network and Zone, go to the Network and Security Group section, and in the ENIs section, select Existing ENI for the Primary ENI or a Secondary ENIs.

API

Call RunInstances. In the NetworkInterface parameter, use NetworkInterfaceId to specify the ENI and InstanceType to define it as primary or secondary.

Attach an ENI to an existing instance

Console

Go to the Instances page in the ECS console and click the target instance ID.
Click the ENIs tab, then click Bind Secondary ENI.
Select the target ENI and click OK.

API

Call AttachNetworkInterface to attach an ENI to an existing instance.

Configure the ENI in the OS

The primary ENI is configured automatically. When you attach secondary ENIs, verify that they are recognized and active in the operating system (OS).

Step 1: Verify that the ENI is active in the instance

Warning

If a secondary ENI is not correctly configured in the OS, it cannot communicate. Follow these steps to verify the ENI status.

Linux instance

Example OS: Alibaba Cloud Linux 3.2.

Connect to the Linux instance.
See Log on to a Linux instance using the SSH tool in Workbench.
Confirm the ENI information:
```
ip a
```
The output shows the ENI information:
- ENI identifier: eth0, eth1. In this example, the instance has a primary ENI (eth0) and a secondary ENI (eth1).
- ENI status: state UP indicates the ENI is active.
  Important
  If you see state DOWN as shown below, the interface has not loaded and cannot be used. Configure the Linux OS to recognize the ENI to activate it.
- Primary private IP address: After an ENI becomes active, its primary private IP address is visible. See Primary private IP addresses.
  If a secondary private IP address assigned to the ENI is not recognized by the OS, see Configure the operating system to recognize a secondary private IP address.
View the routing information:
```
route -n
```
The system typically configures two routes for the secondary ENI (eth1):
- Route with a destination of 192.168.xx.xx: A subnet-specific route that enables direct communication with other hosts in the same subnet.
- Route with a destination of 0.0.0.0: The default route. When a packet's destination does not match a more specific route, the system forwards it to the next-hop Gateway through the interface specified by Iface.
  Important
  - When multiple default routes exist, the route with the lowest Metric value has the highest priority.
  - To ensure traffic returns through the same ENI that received it, configure a policy-based route for the ENI.
  Some older OS versions, such as Ubuntu 16, may not automatically configure a default route for the secondary ENI, as shown below. This can cause communication issues. Use a newer OS distribution, or configure it manually. See Configure a default route for an ENI.

Windows instance

Example OS: Windows Server 2022.

Connect to the Windows instance.
See Log on to a Windows instance using the RDP tool in Workbench.
Open the Network and Sharing Center.
Click Change adapter settings.
In this example, the instance has two ENIs (one primary and one secondary). If you see information similar to the following, the ENIs are active and no further configuration is needed.
If the secondary ENI is not recognized, you might see the following. See Troubleshoot ENI configuration failures on Windows instances.
View the ENI status and details:
1. Double-click the ENI name to view its status.
  For example, the primary ENI Ethernet:
2. Click Details to view the ENI properties.
  The dialog box shows the primary private IPv4 address, subnet mask, default gateway, and other ENI properties:
Open the Command Prompt.
Use the Win+R keyboard shortcut to open the Run dialog box. Enter cmd and click OK.
View the ENI routing information:

Step 2: Configure the Linux OS to recognize the ENI

If the ENI is not active, use one of the following methods to configure it in the OS.

Note

Most Windows OS versions automatically recognize ENIs. If an ENI is not active, see Troubleshoot ENI configuration failures on Windows instances.

Method 1: Automatic configuration with the multi-nic-util tool

Warning

Alibaba Cloud Linux 3, CentOS 8, or later use NetworkManager by default, which enables secondary ENIs automatically. This tool is not required.
The multi-nic-util tool supports Alibaba Cloud Linux 2, CentOS 6 (6.8+), CentOS 7 (7.3+), and Red Hat.
Do not use the multi-nic-util tool in Docker or other containerized environments.
Using the multi-nic-util tool will overwrite the existing network configuration of the ECS instance. Be aware of this risk.

If you cannot use this tool, see Method 2: Manual configuration using network configuration files.

Download and install the multi-nic-util tool (requires internet access):

wget https://image-offline.oss-cn-hangzhou.aliyuncs.com/multi-nic-util/multi-nic-util-0.6.tgz && \
tar -zxvf multi-nic-util-0.6.tgz && \
cd multi-nic-util-0.6 && \
bash install.sh

Restart the ENI service:
```
sudo systemctl restart eni.service
```
Verify the ENI status again to confirm it is active.

Method 2: Manual configuration using network configuration files

Network configuration files vary by Linux distribution, version, and network management tool.

Warning

Back up the original network configuration file before editing.
If you cannot connect using Workbench after modifying the file, connect using VNC to compare the changes and repair the file.
This example assumes DHCP is used for the primary private IP address. To configure a static IP address, see Configure the operating system to recognize a secondary private IP address.
Ensure that the IP address, MAC address, gateway, and other values in the configuration file match the actual settings. Incorrect configurations can cause communication failures.
After attaching or detaching an ENI, update the network configuration file to avoid connectivity issues or configuration conflicts.

Connect to the ECS instance.
See Log on to a Linux instance using the SSH tool in Workbench.
Create and edit the network configuration file based on your Linux distribution and version.
The primary ENI configuration file is generated automatically. The following examples focus on configuring a secondary ENI.
RHEL/CentOS family
- Applicable operating systems: Alibaba Cloud Linux 2/3, CentOS 6/7/8, Red Hat 6/7/8/9, Anolis 7/8, Fedora 33/34/35, and more.
- Network interface configuration file: /etc/sysconfig/network-scripts/ifcfg-*
  Each network interface has a corresponding configuration file, such as ifcfg-eth0, ifcfg-eth1, or ifcfg-eth2.
- Example configuration: Create and edit the configuration file for the secondary ENI (eth1):
```
sudo vi /etc/sysconfig/network-scripts/ifcfg-eth1
```
```
DEVICE=eth1      
TYPE=Ethernet
BOOTPROTO=dhcp
ONBOOT=yes
DEFROUTE=no
```
  - DEVICE: The network interface identifier, such as eth1 or eth2.
  - TYPE: The network interface type. Ethernet indicates an Ethernet interface.
  - BOOTPROTO: The method for obtaining an IP address. dhcp obtains an IP address from a DHCP server. static requires manual IP address and subnet mask configuration.
  - ONBOOT: Whether to activate the interface at system startup. yes enables the interface automatically. no requires manual activation.
  - DEFROUTE: Whether to set this interface as the default route egress.
    For the primary ENI (eth0), this parameter is not required. The system generates a default route with the highest priority for the primary ENI automatically.
    Do not set the secondary ENI as the default route — eth1 might replace eth0, causing primary ENI communication failures. In a multi-ENI environment, configure a policy-based route to control traffic forwarding paths.
Ubuntu 18 and later
Netplan is the default network configuration framework since Ubuntu 18.04 LTS.
- Applicable operating systems: Ubuntu 18/20/22/24
- Network interface configuration file: /etc/netplan/*.yaml
  - The system recognizes YAML files in /etc/netplan. You can create a separate YAML file for each network interface.
  - The default network configuration file for the primary ENI, 50-cloud-init.yaml, is automatically generated by cloud-init at system startup.
- Example configuration: Create and edit the configuration file for the secondary ENI (eth1):
```
sudo vi /etc/netplan/eth1-netcfg.yaml
```
  Note
  The primary ENI configuration file already exists. To ensure correct YAML format, run cp 50-cloud-init.yaml ethX-netcfg.yaml to create the secondary ENI configuration file, then modify it as shown below.
```
network:
    version: 2
    ethernets:
        eth1:
            dhcp4: true
            match:
                 macaddress: 00:16:3e:xx:xx:xx 
            set-name: eth1
```
  - dhcp4: Whether to enable DHCP for IPv4. Valid values: true, false.
  - match: Matches network interface properties, such as its MAC address.
    View the ENI MAC address in the console or by calling an API operation.
Traditional Debian-based Linux (early Ubuntu)
- Applicable operating systems: Debian, early versions of Ubuntu such as Ubuntu 14/16, Debian 8/9/10, and more.
- Network interface configuration file: /etc/network/interfaces
  - Configure IP address, subnet mask, gateway, DNS, and other settings manually, with static IP or DHCP modes.
  - This method has been gradually replaced by Systemd network management tools in newer distributions.
- Configuration items: Interface type, IP address, subnet mask, gateway, and DNS.
- Example configuration: Edit the network configuration file:
```
sudo vi /etc/network/interfaces
```
  Note
  The primary ENI (eth0) and secondary ENI (eth1) configurations are in the same file. Do not omit the primary ENI information.
```
auto lo
iface lo inet loopback

auto eth0
iface eth0 inet dhcp

auto eth1  # Indicates the newly configured network interface.
iface eth1 inet dhcp
```
  - auto <interface>: Automatically activates the network interface at system startup.
  - iface <interface> inet <method>: Defines the interface configuration method.
  - inet: Specifies IPv4 configuration.
  - method: The IP address assignment method. dhcp obtains IP address, subnet mask, default gateway, and DNS from a DHCP server. static requires manual configuration.
SLES family
- Applicable operating systems: SUSE Linux 11/12/15, OpenSUSE 15, and more.
- Network interface configuration file: /etc/sysconfig/network/ifcfg-*
  Each network interface has a corresponding configuration file, such as ifcfg-eth0, ifcfg-eth1, or ifcfg-eth2.
- Example configuration: Create and edit the configuration file for the secondary ENI (eth1):
```
sudo vi /etc/sysconfig/network/ifcfg-eth1
```
```
BOOTPROTO='dhcp'
STARTMODE='auto'
```
  - BOOTPROTO: The IP address assignment method. dhcp obtains IP address and related configuration from a DHCP server.
  - STARTMODE: How the interface is handled at startup. 'auto' activates the interface if detected at startup.

Restart the network service:

Restart the network service for the configuration to take effect.

Operating system	Restart command
Alibaba Cloud Linux 2 CentOS 7 Red Hat 7 Anolis 7 SUSE Linux 11/12/15 OpenSUSE 15/42	`sudo service network restart` or `sudo systemctl restart network`
CentOS 6 Red Hat 6	`sudo service network restart`
Alibaba Cloud Linux 3 CentOS 8 Red Hat 8 Anolis 8 Fedora 33/34/35	`sudo systemctl restart NetworkManager` or `sudo reboot`
Ubuntu 18/20/22 Debian 12	`sudo netplan apply`
Ubuntu 14/16 Debian 8/9/10/11	`sudo systemctl restart networking` or `sudo reboot`

Return to Step 1: Verify that the ENI is active in the instance to confirm the ENI is active.

Assign a private IP address for internal communication

When an ENI is created in a VPC and vSwitch, it receives a primary private IPv4 address from the vSwitch's CIDR block for internal communication.

To support multi-application hosting, failover, or load balancing, assign secondary private IP addresses to the ENI. See Assign a secondary private IP address to an ENI.

Attach a public IP address for Internet communication

Single primary ENI scenario: Assign a static public IP address to the instance (primary ENI) for Internet communication.
Multiple ENIs or flexible management scenarios: Associate an Elastic IP Address (EIP) with an ENI for Internet communication. Unlike static public IP addresses, EIPs can be flexibly associated and disassociated.
You can also associate EIPs with multiple private IP addresses on ENIs to give an instance multiple public IP addresses. See Associate multiple EIPs with an ECS instance in NAT mode.
Important
- After associating an EIP with a secondary ENI, ensure the ENI is attached to an instance and active in the OS. See Configure the ENI in the OS.
- When using a secondary ENI with an EIP or a NAT Gateway, outbound traffic may not flow through the ENI configured with the public IP address, causing EIP communication to fail. Configure a policy-based route to force traffic to return through the same ENI that received it.
- If you still cannot ping the public IP address after correctly configuring the ENI and routes, check the security group and firewall. See Troubleshoot the issue of being unable to ping the public IP address of an ECS instance.

Associate an ENI with a security group

Security groups control inbound and outbound traffic at the network layer for each ENI.

An ECS instance's security group rules apply to its primary ENI. The primary ENI always belongs to the same security group as the instance. To change its security group, modify the instance's security group association.
A secondary ENI can be associated with any security group in the same VPC and zone, which can differ from the instance's security group. Specify the security group when you create the ENI, or change it afterward.
Secondary IPv4 or IPv6 addresses on an ENI are also protected by the ENI's security group rules. Configure precise rules based on source IP, protocol, port, and other criteria. See Manage security group rules.

Create an ENI

Console

API

Attach an ENI to an ECS instance

Prerequisites

Attach an ENI when creating an instance

Console

API

Attach an ENI to an existing instance

Console

API

Configure the ENI in the OS

Step 1: Verify that the ENI is active in the instance

Linux instance

Windows instance

Step 2: Configure the Linux OS to recognize the ENI

Method 1: Automatic configuration with the multi-nic-util tool

Method 2: Manual configuration using network configuration files

RHEL/CentOS family

Ubuntu 18 and later

Traditional Debian-based Linux (early Ubuntu)

SLES family

Assign a private IP address for internal communication

Attach a public IP address for Internet communication

Associate an ENI with a security group