ifupdown-ng for system administrators

ifupdown-ng is a network device manager which is backwards compatible with traditional ifup and ifdown as used on Debian and Alpine systems, while solving many design deficits with the original approach through robust error handling and the use of a dependency-solver to determine interface bring-up order.

This guide is intended to walk users through using the ifupdown-ng system without any assumption of familiarity with the legacy ifupdown system.

Important Filesystem Paths

The ifupdown-ng system uses the following paths, ranked in order of importance:

/etc/network/interfaces: the interface configuration database, which contains information about what interfaces should be configured.
/run/ifstate: the interface state file, which denotes what physical interfaces are configured, and what interface definition they are configured as.
/usr/libexec/ifupdown-ng: this directory contains the native ifupdown-ng executors, which are run as necessary to configure an interface. See the ifupdown-executor(7) manual page for more information on how these programs are written.
/etc/network/if-{up|down|pre-up|post-down}.d: these directories contain scripts that are run when an interface is brought up or down. In general, they follow the same contract described in ifupdown-executor(7).

All configuration examples in this guide concern the /etc/network/interfaces file.

Basic Configuration

To begin with, lets look at a basic configuration for a desktop computer. This scenario involves using the DHCP helper to learn an IPv4 address dynamically.

In this case, the /etc/network/interfaces file would look like:

auto eth0
iface eth0
    use dhcp

These configuration statements do two things: designate that eth0 should be started automatically with the auto keyword, and designate that the dhcp executor should be used to configure the interface.

As a more detailed explanation, here is a commented version:

# Start eth0 automatically.
auto eth0

# Begin an interface definition for eth0.
iface eth0

    # Use the dhcp executor to configure eth0.
    use dhcp

IPv6 RA Configuration

With IPv6, stateless auto-configuration is typically used to configure network interfaces. If you are not interested in using IPv4 at all, you can simply use the ipv6-ra executor to ensure that an interface is configured to accept IPv6 RA advertisements:

auto eth0
iface eth0
    use ipv6-ra

Static Configuration

We can use the static executor to configure static IPv4 and IPv6 addresses. If you use the address keyword, the static executor will automatically be used to configure the interface:

auto eth0
iface eth0
    address 203.0.113.2/24
    gateway 203.0.113.1

Multi-homing

A typical scenario on servers is multi-homing, where a server has multiple IP addresses on a single interface. In this case you simply add additional address lines like this:

auto eth0
iface eth0
    address 203.0.113.2/24
    address 203.0.113.3/24
    address 203.0.113.4/24
    gateway 203.0.113.1

Dual-stack configurations

Another typical scenario for servers is to run a dual-stack configuration, where interfaces have both an IPv4 and an IPv6 address. This is accomplished in a similar way as multi-homing. You specify the IPv4 and IPv6 addresses you want, followed by gateways for each:

auto eth0
iface eth0
    address 203.0.113.2/24
    address 203.0.113.3/24
    address 203.0.113.4/24
    gateway 203.0.113.1

    address 2001:db8:1000:2::2/64
    address 2001:db8:1000:2::3/64
    address 2001:db8:1000:2::4/64
    gateway 2001:db8:1000:2::1

Questions

If you have further questions about how to use ifupdown-ng to configure a specific scenario, drop by the ifupdown-ng IRC channel.

3.8 KiB Raw Blame History