HOSTNAME.IF(5)

✨ NAME ✨

hostname.if — the interface-specific configuration files, aka the lil per-interface cheat sheets 💅

okay so real talk, this is hostname.if(5), and if you've ever wondered how your OpenBSD-ish box knows what to do with a network card the second it boots — this is it, bestie 🫶

---

🌸 DESCRIPTION 🌸

The hostname.* files contain all the info about how each network interface gets configured. Interfaces get referenced by name and unit, like hostname.fxp0 — super straightforward, iykyk.

But here's the plot twist 👀: on some machines, autoconfiguration makes this system inconsistent, so you can alternatively reference interfaces by their link layer address (lladdr), like hostname.00:00:5e:00:53:af. And the priority tea ☕: configuration by interface lladdr wins over name/unit. Periodt.

Oh and also — you do not need a configuration file for lo0. She's built different, she doesn't need one 💁‍♀️

The configuration info is expressed in a line-by-line packed format, which makes the most common cases simpler; those dense formats are described below. Any lines that don't match these packed formats get passed directly to ifconfig(8). The packed formats are converted using a somewhat inflexible parser, and the administrator should not expect magic — if in doubt, go study ifconfig(8) and the per-driver manual pages to see what arguments are permitted 🔍

Arguments containing either whitespace or single quote characters must be double quoted. For example:

inet 10.0.0.1 255.255.255.0 10.0.0.255 description "Bob's uplink"

Every line is processed separately and in order. For example:

join mynwid wpakey mywpakey
inet6 autoconf
inet autoconf

would run ifconfig three times to add a wireless network using WPA to the join list and enable dynamic address configuration for IPv6 and IPv4. three whole runs, she's booked and busy 💀

---

🎀 STATIC ADDRESS CONFIGURATION 🎀

The following packed formats are valid for configuring network interfaces with static addresses ✨

Regular IPv4 network setup:

inet [alias] addr netmask broadcast_addr options
dest dest_addr

Regular IPv6 network setup:

inet6 [alias] addr prefixlen options
dest dest_addr

Other network setup:

addr_family options

A typical file contains only one line, but more extensive files are possible, for example:

media 100baseTX description Uplink
inet 10.0.1.12 255.255.255.0 10.0.1.255
inet alias 10.0.1.13 255.255.255.255 10.0.1.13
inet alias 10.0.1.14 255.255.255.255 NONE
inet alias 10.0.1.15 255.255.255.255
inet alias 10.0.1.16 0xffffffff
# This is an example comment line.
inet6 alias fec0::1 64
inet6 alias fec0::2 64 anycast
!route add 65.65.65.65 10.0.1.13
up

The above formats have the following field values 👇

• addr_family — the address family of the interface, generally inet or inet6.
• alias — the literal string alias, if this is an additional network address for the interface.
• addr — the optional address that belongs to the interface, such as 190.191.192.1 or fe80:2::1. It is also feasible to use a hostname as specified in /etc/hosts. It is recommended that an address be used instead of symbolic information, since the latter might activate resolver library routines. If no address is specified, the netmask, broadcast_addr, dest, and dest_addr options are invalid and will be ignored. lowkey important, don't skip this one 🫶
• netmask — the optional network mask for the interface, e.g., 255.255.255.0. If addr is specified but netmask is not, the classful mask based on addr is used.
• broadcast_addr — the optional broadcast address for the interface, e.g., 190.191.192.255. The word NONE can also be specified in order to configure the broadcast address based on the netmask. The netmask option must be present in order to use this option.
• options — miscellaneous options to set on the interface, e.g., media 100baseTX mediaopt full-duplex. Valid options for a particular interface type can be found in ifconfig(8). When used, the netmask and broadcast_addr options must also be present.
• dest — if the interface needs a destination address set, this is the literal text dest. As shown in the example, this declaration should start on a separate line.
• dest_addr — the destination address to be set on the interface, such as 190.191.192.2. It is also feasible to use a hostname as specified in /etc/hosts. It is recommended that an address be used instead of symbolic information which might activate resolver library routines.
• prefixlen — the prefixlen number, or number of bits in the netmask, to be set on the interface, such as 64.
• # — comments are allowed! Anything following a comment character is treated as a comment. go off, annotate your config 💬
• !command — arbitrary shell commands can be executed using this directive, as long as they are available in the single-user environment (for instance, /bin or /sbin). Useful for doing interface-specific configuration such as setting up custom routes or default source IP address using route(8) or establishing tunnels using ifconfig(8). It is worth noting that \$if in a command line will be replaced by the interface name.

For example, to set 192.0.2.1 and 2001:db8::1 as source IP addresses for outgoing connections:

inet 192.0.2.1/32
inet6 2001:db8::1/128
up
!route sourceaddr -ifp \$if

---

🦋 DYNAMIC ADDRESS CONFIGURATION 🦋

IPv4 dynamic addressing via DHCP is requested using inet autoconf, followed by any options to be passed to ifconfig(8).

inet autoconf [ifconfig_options]

The token dhcp on its own line without any options is short for inet autoconf. tiny shorthand, big slay ✨

IPv6 stateless address autoconfiguration is requested using the literal string inet6 autoconf, followed by any options to be passed to ifconfig(8).

inet6 autoconf [ifconfig_options]

The autoconf configurations will communicate learned DNS information to resolvd(8). sharing is caring, fr fr 💖

---

🍓 FILES 🍓

• /etc/hostname.XXX — interface-specific configuration files.

---

🌈 SEE ALSO 🌈

hosts(5), ifconfig(8), netstart(8), rc(8), slaacd(8)

---

bestie reminder: this page is from the Debian edition, dated December 16, 2022 — so if your man page says something wilder, check the date before you come for me 🙈

ok that's the whole vibe, go configure something iconic 💅👑