interfaces(5)

📦

version 0.12.1 · 3 versions

0.12.1 · ubuntu resolute, ubuntu stonking (latest)
0.12.1 · ubuntu noble
0.12.1 · debian trixie, ubuntu questing

💖 interfaces(5) — the File Formats Manual one, bestie 💖

okay so this is the page for /etc/network/interfaces, from interfaces(5) in the File Formats Manual. buckle up, it's actually so good.

✨ NAME ✨

/etc/network/interfaces — the interface configuration database 🌸

🦋 DESCRIPTION 🦋

The /etc/network/interfaces file is the place where you tell the system how your network interfaces get configured. it's read and acted on by ifquery(8), ifup(8) and ifdown(8) — those three use it to peek at system state and to actually change it. so like, it's not decorative, it's doing real work 💅

ngl, in most cases syntax from legacy implementations is supported too?? but the manpage is like "we're not getting into that here," so we're not either. periodt.

🎀 FILE SYNTAX 🎀

The interface configuration database is made of a series of stanzas. hash symbols (#) mark comments, and the system just ignores those. 💜

A stanza is a collection of triples, and a triple is a key + value combo that's related to an object. triples that aren't associated with an object are considered part of the root of the configuration tree. it's giving tree structure, iykyk 🌳

⚠️ All keywords are case-sensitive and are expected to be lower-case. don't get cute with the capitals bestie, the parser will simply not know her.

here's a simple little baby stanza example:

auto eth0
iface eth0
    address 203.0.113.2/24
    gateway 203.0.113.1

so this stanza defines an interface named eth0, configured with an address of 203.0.113.2 and gateway of 203.0.113.1. iconic. 💖

✨ SUPPORTED KEYWORDS FOR UNASSOCIATED TRIPLES ✨

these are the ones that live at the root of the config tree, no object attached:

auto object — says that object should be automatically configured by the system when appropriate. very "handle it for me" of you 🫶
iface object — starts a brand new declaration for object. any child keyword associated with the declaration gets stored inside object. this is the main character keyword honestly 👑
source filename — includes the file filename as configuration data. shell wildcards can be used here! see wordexp(3). 🌈
source-directory directory — includes the files in directory as configuration data.
template object — starts a new declaration for object, just like iface does, EXCEPT that object is defined as a template. 🧚

💅 SUPPORTED KEYWORDS FOR OBJECT TRIPLES 💅

so technically any keyword may be used inside an interface declaration block?? but the system will only respond to certain keywords by default. here's the list, bestie:

address address — associates an IPv4 or IPv6 address in CIDR notation with the parent interface. if an IP address is given without a prefix length, a given netmask attribute is used if present. if neither a prefix length nor a netmask are given, a /24 or /64 prefix length is presumed for IPv4 / IPv6, as of compatibility reasons to classic ifupdown. 🍓
netmask netmask — associates a fallback netmask with the parent interface, for addresses that don't have a CIDR length set. this option is for backwards compatibility and should not be used in new deployments. girl it's legacy, let her rest 😭
point-to-point address — sets the given IPv4 address as the peer address on the interface. this setting only takes effect for the IPv4 address familiy and only makes sense in combination with a /32 netmask. for compatiblity with ifupdown and ifupdown2, pointopoint is an alias for this parameter.
gateway address — associates an IPv4 or IPv6 address with the parent interface for use as a default route (gateway). usually you give this once for IPv4 and once for IPv6 (in a Dual-Stack setup). ✨
link-type link-type — denotes the link-type of the interface. when set to dummy, the interface is created as a virtual dummy interfaces. when set to veth, the interface is created as virtual veth interface (pair).
veth-peer-name peer-name — denotes the name of the veth peer interfaces. if not set, the kernel will name the veth peer interface as vethN, with N being an integer number.
alias alias — sets the given alias on the interface.
requires interfaces... — designates one or more required interfaces that must be brought up before configuration of the parent interface. interfaces associated with the parent are taken down at the same time as the parent. it's giving "we come as a package" 🫶
inherit object — designates that the configured interface should inherit configuration data from object. normally object must be a template.
use executor — designates that an executor should be used. see the EXECUTORS section for more info on executors 👀
pre-down command — runs command before taking the interface down.
down command — runs command when the interface is taken down.
post-down command — runs command after taking the interface down.
pre-up command — runs command before bringing the interface up.
up command — runs command when the interface is brought up.
post-up command — runs command after bringing the interface up.

Additional packages, such as bonding, bridge, tunnel, vrf and vxlan, add additional keywords to this vocabulary. so if you installed extra stuff, expect extra vocabulary, bestie 🌈

🔥 EXECUTORS 🔥

The use keyword designates that an executor should be used. this whole system is extendable by additional packages, but the most common executors are:

batman — the interface is a B.A.T.M.A.N. adv. mesh interface. configuration of B.A.T.M.A.N. adv. interfaces requires the batctl untiliy to be installed.
bond — the interface is a bonded interface. configuration of bonded interfaces requires the bonding package to be installed.
bridge — the interface is an ethernet bridge. configuration of ethernet bridges requires the bridge package to be installed. 🌉
dhcp — use a DHCP client to learn the IPv4 address of an interface.
forward — configures forwarding settings on the interface.
loopback — designates the interface as a loopback device.
ppp — designates the interface as a PPP device. configuration of PPP interfaces require the ppp and probably the pppoe packages to be installed.
tunnel — the interface is a tunnel. configuration of tunnels requires the tunnel package to be installed on Alpine Linux.
vrf — the interface is a VRF. configuration of VRFs requires the vrf package to be installed.
vxlan — the interface is a Virtual Extensible LAN (VXLAN) tunnel endpoint.
wifi — the interface is a Wi-Fi (IEEE 802.11) client interface. configuration of the WiFi client interface requires the wireless-tools package to be installed. the wpa_supplicant package must also be installed to connect to hotspots using WPA-based security. 📶
wireguard — the interface is a Wireguard VPN tunnel endpoint.

Check interfaces-<executor>(5) for further informaton about a given executor and available configuration parameters. 👑

and!! if the auto_executor_selection ifupdown-ng.conf option is enabled, use statements will automatically be added for executors when their configuration statements are present in the interfaces file. that's the automation slay of it all 💅

🌟 EXAMPLES 🌟

Example one: configure a bridge interface br0 with bond0 attached to it, which is a failover between eth0 and eth1. this requires the bonding and bridge packages to be installed:

auto br0
iface br0
    use bridge
    requires bond0
    address 203.0.113.2/24
    gateway 203.0.113.1

iface bond0
    use bond
    requires eth0 eth1
    bond-mode 802.3ad
    bond-xmit-hash-policy layer2+3

Example two: configure a network interface to use DHCP to learn its IPv4 address:

auto eth0
iface eth0
    use dhcp

look at her go 😭💖

💜 AUTHORS 💜

Ariadne Conill <ariadne@dereferenced.org>
Maximilian Wilhelm <max@sdn.clinic>

and that's the whole page bestie!! this version of interfaces(5) is dated 2025-10-13, and yeah it's the same interfaces(5) from the File Formats Manual you started with. no cap, go configure something iconic 💅✨🎀

📦 where this page comes from

ubuntu resolute: ifupdown-ng 0.12.1-8 · MIT-like
ubuntu stonking: ifupdown-ng 0.12.1-8 · MIT-like
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms