--- name: "interfaces-ng" section: "5" platform: "linux" package: "ifupdown-ng" version: "0.12.1-7" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/interfaces-ng" --- # interfaces-ng(5) interface configuration database ## NAME **/etc/network/interfaces** - interface configuration database ## DESCRIPTION The **/etc/network/interfaces** file is used to specify how network interfaces are configured. The file is processed by [**ifquery**(8)](/ifquery/8.md), [**ifup**(8)](/ifup/8.md) and [**ifdown**(8)](/ifdown/8.md) to introspect and change system state. In most cases, syntax from legacy implementations is supported as well, but that syntax is not discussed in detail here. ## FILE SYNTAX The interface configuration database is composed of a series of stanzas. Hash symbols designate comments, which are ignored by the system. A stanza is a collection of triples, where a triple is a key and value combination that is related to an **object**. Triples which are not associated with an **object** are considered to be part of the root of the configuration tree. All keywords are case-sensitive and are expected to be lower-case. The following is a simple example of a stanza: ``` auto eth0 iface eth0 address 203.0.113.2/24 gateway 203.0.113.1 ``` This stanza defines an interface named **eth0** which is configured with an address of **203.0.113.2** and gateway of **203.0.113.1**. ## SUPPORTED KEYWORDS FOR UNASSOCIATED TRIPLES **auto** *object* Designates that *object* should be automatically configured by the system when appropriate. **iface** *object* Begins a new declaration for *object*. Any child keyword associated with the declaration will be stored inside *object*. **source** *filename* Includes the file *filename* as configuration data. Shell wildcards can be used. See [wordexp(3)](/wordexp/3.md). **source-directory** *directory* Includes the files in *directory* as configuration data. **template** *object* Begins a new declaration for *object*, like **iface**, except that *object* is defined as a **template**. ## SUPPORTED KEYWORDS FOR OBJECT TRIPLES Any keyword may be used inside an interface declaration block, but the system will only respond to certain keywords by default: **address** *address* Associates an IPv4 or IPv6 address in CIDR notation with the parent interface. If an IP address without a prefix length is given 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 which do not have a CIDR length set. This option is for backwards compatibility and should not be used in new deployments. **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). This usually is given 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. **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 *EXECUTORS* section for more information 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. ## EXECUTORS The **use** keyword designates that an *executor* should be used. This 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-\(5)** for further informaton about a given executor and available configuration parameters. 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. ## EXAMPLES 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 ``` Configure a network interface to use DHCP to learn its IPv4 address: ``` auto eth0 iface eth0 use dhcp ``` ## SEE ALSO [**ifstate**(5)](/ifstate/5.md) [**ifupdown-ng.conf**(5)](/ifupdown-ng.conf/5.md) [**ifup**(8)](/ifup/8.md) [**ifdown**(8)](/ifdown/8.md) [**ifquery**(8)](/ifquery/8.md) [**ifctrstat**(8)](/ifctrstat/8.md) [**interfaces-batman**(5)](/interfaces-batman/5.md) [**interfaces-bond**(5)](/interfaces-bond/5.md) [**interfaces-bridge**(5)](/interfaces-bridge/5.md) [**interfaces-forward**(5)](/interfaces-forward/5.md) **interfaces-mpls**(5) [**interfaces-ppp**(5)](/interfaces-ppp/5.md) [**interfaces-tunnel**(5)](/interfaces-tunnel/5.md) [**interfaces-vrf**(5)](/interfaces-vrf/5.md) [**interfaces-vxlan**(5)](/interfaces-vxlan/5.md) [**interfaces-wifi**(5)](/interfaces-wifi/5.md) [**interfaces-wireguard**(5)](/interfaces-wireguard/5.md) ## AUTHORS Ariadne Conill \\ Maximilian Wilhelm \