SETUP-INTERFACES(8)

📦 version 3.22.0, in alpine 3.24

💅 SETUP-INTERFACES(8) — the Alpine Linux network glow-up guide ✨

okay bestie, so this is a page from the System Manager's Manual, and it's literally all about setup-interfaces. buckle up 🎀

🌸 NAME 🌸

setup-interfaces — configure Alpine Linux network interfaces

🦋 SYNOPSIS 🦋

setup-interfaces [-abhir] [-p ROOT] [-w FILE]

✨ DESCRIPTION ✨

So setup-interfaces configures network interfaces for Alpine Linux. it's giving guided tour energy 💫 — it runs an interactive walk-through that sniffs out unconfigured interfaces and then prompts you for addressing, bridges, bonding, VLANs, and wireless credentials.

It writes the network configuration under the target root, and if you want, it also sets up wpa_supplicant(8) for wireless networks. 🫶

and like, quick little flex: when you run it in a Xen Dom0, bridging is offered by default. no cap. 👑

💅 OPTIONS 💅

  • -a — set up the first available interface with DHCP and dip out, no prompts shown. all available interfaces get brought up and polled simultaneously; the first one whose link state becomes "up" (within a total timeout of roughly 1.1 seconds) gets configured, and the rest are taken down. bye besties 👋
  • -b — prompts for bridging of each interface during interactive setup. enabled by default in Xen Dom0.
  • -h — display usage information and exit. classic.
  • -i — read new contents of /etc/network/interfaces from stdin and write them to the file. no interactive prompts, none, zero. when combined with -a, -i takes precedence (it said what it said 💁‍♀️).
  • -p ROOT — operate on the system tree at ROOT instead of "/". network and imported wireless configuration are written under ROOT.
  • -r — restart the networking service after configuration. refresh era 🔄
  • -w FILE — import FILE as /etc/wpa_supplicant/wpa_supplicant.conf and enable the wpa_supplicant service at boot. can be combined with other modes to set up wireless credentials alongside the interface configuration. multitasking icon 💅

🌈 INTERACTIVE MODE 🌈

When invoked without -a or -i, setup-interfaces enters interactive mode. this is the main character era of the script 💖

🧚 Interface selection

The script scans for unconfigured interfaces — that's physical network devices that aren't already set up in /etc/network/interfaces. note that loopback and docker0 are skipped (docker0 we love you but not today 🙈).

For each detected interface, you get prompted to assign it an address, add it to a bridge or bond, or mark it as a VLAN raw device.

The following interface types can be entered at the prompt:

  • br[0-9]+ (e.g. br0) — bridge interface. the script prompts for which unconfigured physical ports to add as bridge ports. 🌉
  • bridge[0-9]+ (e.g. bridge0) — synonym for a bridge interface. same vibe, different name.
  • virbr[0-9]+ (e.g. virbr0) — bridge interface.
  • bond[0-9]+ (e.g. bond32) — bonded (aggregated) interface. the script prompts for which unconfigured physical interfaces to add as bond slaves. squad goals fr fr 🫂
  • bond[0-9]+.[0-9]+ (e.g. bond0.371) — VLAN on top of a bonded interface. layers, literally.
  • vlan[0-9]+ (e.g. vlan371) — VLAN interface. the script prompts for the raw device.
  • IFACE.[0-9]+ (e.g. eth0.371) — VLAN on a physical interface.

⭐ Addressing

For each interface, these address types are supported:

  • dhcp — configure the interface with DHCP. easy mode, we stan.
  • static — enter a static IPv4 address. a prompt for netmask (default 255.255.255.0) and gateway (default none) follows. you got this 💪
  • none — do not assign an address. an "up" entry is written to the config so the interface is brought up at boot.
ok so tiny detail that's lowkey iconic: when a static address is entered with a /mask suffix (e.g. 192.168.1.1/24), the netmask is extracted automatically and the netmask prompt is skipped. the script ate that one 🔥

🩵 Wireless

If the interface is a wireless device (it has a phy80211 directory under /sys/class/net/), the script scans for visible access points and prompts for the SSID. for WPA-PSK networks, a password is prompted. the configuration gets written via wpa_passphrase(8) to /etc/wpa_supplicant/wpa_supplicant.conf, and the wpa_supplicant service is enabled and started. 🦋📶

the iw and wpa_supplicant packages are installed on demand — no need to pre-install, it'll just handle it.

🌉 Bridge, bond, and VLAN details

Bridges and bonds collect ports from the pool of unconfigured physical interfaces. once a port is assigned to a bridge or bond, it's removed from the unconfigured pool and is not prompted for individually. teamwork makes the dream work 💜

VLAN interfaces (e.g. eth0.371) require a raw device; that raw device must itself be unconfigured or a bond master. important detail, don't skip it ✨

🎀 Final steps

After all interfaces are configured, you get an opportunity to edit the generated configuration manually. if packages for bridging (bridge), bonding (bonding), or VLANs (vlan) are needed, they're installed. then the configuration is copied to /etc/network/interfaces. and that's the whole glow-up, periodt. 💅

👑 EXIT STATUS 👑

  • 0 — success. slay.
  • non-zero — an error occurred. 😭 (it happens to the best of us)

🔥 ENVIRONMENT 🔥

  • SETUP_INTERFACES_LINK_WAIT_MAX — maximum number of retries (at 0.1-second intervals) when waiting for a link to come up in -a mode. defaults to 11 (approximately 1.1 seconds total). tune it if you're feeling spicy 🌶️

🍓 FILES 🍓

  • /etc/network/interfaces — the generated network interface configuration file. the main event 💖
  • /etc/wpa_supplicant/wpa_supplicant.conf — wpa_supplicant configuration written when wireless networks are configured. 📡

💫 SEE ALSO 💫

wpa_supplicant(8), wpa_passphrase(8), setup-alpine(8), setup-disk(8)

iykyk — go read those next, bestie 🫶

🌟 AUTHORS 🌟

Natanael Copa <ncopa@alpinelinux.org> and others 🫡

so yeah, that's the whole page — brought to you by Alpine Linux, dated 2026-06-09, version-locked and iconic. now go configure something and make it cute 💅✨🎀

📦 where this page comes from