Netplan does not support the traditional Linux "label" syntax (like eth0:1) because it manages network interfaces at a higher abstraction level than the kernel's interface naming convention. To achieve the functional equivalent of labeling or aliasing, you must add multiple IP addresses to the same network interface definition within your Netplan YAML configuration file. This approach creates secondary IPs that behave exactly like labeled aliases while remaining fully managed by the Netplan renderer.
Understanding Netplan Interface Abstraction
In traditional sysvinit or systemd-networkd configurations, administrators often used labels such as
eth0:1 to distinguish between primary and secondary addresses on a single physical port. Netplan abstracts this concept entirely. It treats an interface as a logical entity defined in YAML, where all properties—including multiple IPv4 or IPv6 addresses—are applied simultaneously to that logical interface. Consequently, there is no direct mapping for "labels" in Netplan documentation because the label concept is obsolete in modern declarative network management. Instead, the solution lies in structuring your YAML to include a list of addresses under a single
addresses key.
When you define an interface in Netplan, you specify its type (such as
ethernet,
wifi, or
bridge) and then provide the parameters that should be active on that interface. The renderer, which could be NetworkManager, systemd-networkd, or others depending on your distribution, interprets these instructions. By listing multiple IP addresses in the configuration, the underlying renderer applies them all to the specified device. This results in the same behavior as adding a label: the system responds to traffic destined for any of those IPs on that interface.
Configuring Secondary IPs via YAML
The core of the solution involves editing the appropriate Netplan configuration file, typically located in
/etc/netplan/. You will need root privileges to modify these files. Open your preferred text editor with the file corresponding to your network setup. For example, if your file is named
01-netcfg.yaml, you would run
sudo nano /etc/netplan/01-netcfg.yaml.
Inside the YAML structure, locate the interface you wish to modify. Under the
network: root key, you will find
version: 2 and
ethernets:. Within the specific interface block, you will see the
addresses field. This field accepts a list of strings. To add a secondary IP, simply append it to this list alongside your existing primary address.
Here is a concrete example of what the configuration should look like. Note the indentation, which is critical for YAML parsing:
network:
version: 2
ethernets:
eth0:
dhcp4: false
addresses:
- 192.168.1.10/24
- 192.168.1.11/24
routes:
- to: default
via: 192.168.1.1
nameservers:
addresses:
- 8.8.8.8
- 8.8.4.4
In this snippet, both
192.168.1.10 and
192.168.1.11 are assigned to
eth0. The subnet mask (
/24) must be specified for each address individually. Unlike older methods where you might have created a virtual interface, here both IPs share the same hardware queue and MAC address. This is functionally identical to having a label on the interface.
Applying the Configuration
Once you have saved the changes to your YAML file, you must apply the new configuration. Netplan provides a command-line tool to validate and apply settings. Run the following command to dry-run the configuration and check for syntax errors:
sudo netplan try
This command applies the configuration but reverts it after a timeout period (usually 120 seconds) if you do not confirm it. If your network connectivity drops unexpectedly during this window, the system automatically rolls back to the previous working state, preventing lockouts. If the connection remains stable, press Enter to confirm the changes permanently. Alternatively, you can apply the configuration immediately without the safety timeout using:
sudo netplan apply
After applying, verify that the secondary IP is active by running
ip addr show eth0. You should see both IP addresses listed under the interface.
Managing Labels via Sysfs (Advanced)
If your specific application strictly requires a kernel-level label name (for example, some legacy monitoring tools might parse
/proc/net/if_inet6 or expect specific interface naming conventions), Netplan alone cannot create these names. However, you can use udev rules to assign a symbolic link or alias that acts as a label. This is rarely necessary for standard IP routing but may be required for complex scripting environments.
Create a udev rule in
/etc/udev/rules.d/99-netplan-labels.rules. You can create a symlink from the physical interface to a custom name. For instance:
SUBSYSTEM=="net", ACTION=="add", ATTR{address}=="xx:xx:xx:xx:xx:xx", SYMLINK+="eth0_alias"
Replace the MAC address with your actual interface identifier. This creates a persistent alias. While this doesn't change the IP assignment mechanism (which remains in Netplan), it provides the "named" reference point some users seek when asking about labels.
For more details on managing multiple IPv6 addresses, which often accompany secondary IP setups, refer to our guide on
Configuring Two ULA Addresses on One Interface: A Guide to IPv6 Networking in Linux. Additionally, understanding how your public IP is perceived versus local configuration can help troubleshoot visibility issues, as discussed in
Why is my public IPv6 address different from the one listed in Linux?.
Common Pitfalls and Verification
A frequent error when adding secondary IPs is forgetting to update firewall rules. Your firewall (ufw, firewalld, or iptables) may only allow traffic on the primary IP. Ensure that your firewall policies apply to the entire interface or explicitly permit the new IP range. Another issue arises with DHCP; if you enable DHCP on the interface, the DHCP server might overwrite static entries if not configured correctly. It is best practice to disable DHCP for the interface when assigning static secondary IPs manually.
Always verify routing tables after applying changes. Use
ip route show to ensure that packets destined for the secondary IP are routed correctly through the default gateway. In most cases, the kernel handles this automatically, but asymmetric routing scenarios may require manual route adjustments.
Frequently Asked Questions
Can I remove a secondary IP without removing the primary one?
Yes, simply edit the YAML file and delete the specific IP line from the
addresses list. Then run
sudo netplan apply. The primary IP remains untouched as long as it stays in the list.
Does adding a secondary IP increase my bandwidth?
No. Secondary IPs are logical constructs that share the same physical bandwidth and network interface card capabilities. They are useful for hosting multiple services or identifying traffic sources, not for increasing throughput.
How do I assign a specific label name like eth0:1 in Netplan?
Netplan does not support traditional alias labels. You must use multiple entries in the
addresses list. If you absolutely need a named interface for scripts, use udev rules to create symlinks, but note that this is separate from IP assignment.
What happens to the secondary IP if the interface goes down?
All IPs assigned to the interface are removed when the interface is brought down. When the interface comes back up, Netplan reapplies all addresses defined in the YAML file, restoring both primary and secondary IPs automatically.
Can I use different subnets for secondary IPs on the same interface?
Yes, you can assign IPs from different subnets to the same interface. However, ensure that your router or upstream network knows how to route traffic for those subnets back to your machine, otherwise, return traffic may be dropped.