NETWORK-CONFIG(5)

📦 version 3.4.1, in alpine 3.24

🦋 NETWORK-CONFIG(5) 🦋

okay bestie, welcome to network-config(5) from the File Formats Manual — yes it's a section 5 page, yes it's a whole vibe ✨

💖 NAME 💖

network-config — the tiny-cloud-supported NoCloud network configuration format, and honestly? she's tiny, she's specific, she's iconic 💅

🌸 DESCRIPTION 🌸

network-config describes the subsets of the cloud-init network configuration versions 1 and 2 that tiny-cloud's NoCloud provider supports. not all of it, just the subsets — read the fine print, bestie, it matters 🫶

This document is supplied as the separate NoCloud network-config file. Important: it does not have a top-level network key. and #network-config user-data? not yet supported. nope. not today. 🚫

✨ VERSION 1 ✨

Version 1 documents contain a config list, like so:

version: 1
config:
  - type: physical
    name: eth0
    subnets:
      - type: dhcp4

The supported physical keys are name, mac_address, mtu, accept-ra, and subnets. The interface name is required — no name, no deal 🙈. When a MAC address is supplied, tiny-cloud verifies an existing interface of that name or arranges a rename when necessary.

The supported subnet types are:

  • static and static6
  • dhcp and dhcp4
  • dhcp6 and ipv6_dhcpv6-stateful
  • ipv6_dhcpv6-stateless
  • ipv6_slaac

Static subnets support address, IPv4 netmask, and gateway. DHCP subnets support metric. Subnets may also contain dns_nameservers and dns_search lists. Multiple physical entries and multiple supported subnets are emitted — yes, all of them, we're not playing favorites 💖

IPv4 dotted netmasks are converted to CIDR prefixes for ifupdown-ng. This includes /32 provider addressing with an explicitly supplied gateway. lowkey a flex, ngl.

A type: nameserver entry supports global address and search lists. Unsupported entry and subnet types are warned about and skipped, which lets the supported siblings get applied. so like, one flop doesn't ruin the whole group chat 😌

🎀 VERSION 2 🎀

Version 2 documents contain an ethernets mapping:

version: 2
ethernets:
  eth0:
    dhcp4: true

The supported keys are:

  • ethernets
  • dhcp4 and dhcp6
  • accept-ra
  • mtu
  • match.macaddress
  • set-name
  • addresses
  • gateway4 and gateway6
  • nameservers.addresses and nameservers.search
  • dhcp4-overrides.route-metric
  • dhcp6-overrides.route-metric

All entries in an addresses list are emitted — every single one, no skips, periodt 🔥. Addresses must use the CIDR notation expected by network-config version 2. that's the rule, don't fight it 💅

🧚 INTERFACE RENAMING 🧚

Version 1 uses name with mac_address. A rename is required only when the requested interface name is not already present. Version 2 requests a rename with match.macaddress and set-name.

For a required rename, tiny-cloud applies the new name before networking and makes it persistent using the detected init system. here's the tea ☕:

  • On OpenRC, tiny-cloud writes /etc/tiny-cloud/iftab, configures /etc/conf.d/macifrename to use it, and enables and starts the macifrename service.
  • On systemd, tiny-cloud writes native .link files under /etc/systemd/network and reloads systemd-udevd.
The affected entry is skipped when the required rename mechanism is unavailable. no mechanism, no rename, moving on 💀

🌈 DHCP 🌈

Ordinary DHCPv4 uses the default ifupdown-ng DHCP client. DHCPv6 and DHCP route metrics require dhcpcd.

If dhcpcd is unavailable, tiny-cloud warns and ignores only the unsupported DHCPv6 or metric setting. Other usable configuration on the interface — like DHCPv4, static addresses, or IPv6 router advertisements — is preserved 🫶 we do not throw the whole interface away, we are not messy.

👑 PRECEDENCE AND FALLBACK 👑

When PRESERVE_NETWORK_INTERFACES=1 and /etc/network/interfaces already exists, tiny-cloud preserves that file. If no interfaces file exists, normal processing continues. simple as that ✨

A nonempty separate NoCloud network-config file takes precedence over legacy meta-data/network-interfaces and an existing /etc/network/interfaces. A valid, usable version 1 or version 2 document is rendered and replaces the interfaces file atomically. no half-written files, we don't do that here 💅

When the separate network-config file is absent or empty, tiny-cloud uses legacy meta-data/network-interfaces when available. Otherwise, an existing interfaces file is preserved. If neither exists, normal tiny-cloud network fallback generates loopback and DHCP configuration for a detected interface.

⚠️ A present but malformed, unsupported, or unusable network-config does not fall through to legacy meta-data/network-interfaces. An existing interfaces file is preserved; if none exists, normal tiny-cloud network fallback applies. so yes — a broken doc has consequences, ok?? 😭

Rendering is atomic. Failed rendering does not replace an existing interfaces file or apply DNS settings from the rejected document. rejected doc = rejected DNS, that's the rule 🚫

🍓 FILES 🍓

  • /var/lib/cloud/network-config NoCloud network configuration input.
  • /etc/network/interfaces Generated ifupdown-ng configuration.
  • /etc/tiny-cloud/iftab Persistent MAC-to-interface-name mappings generated by tiny-cloud.
  • /etc/systemd/network/10-tiny-cloud-N.link Persistent systemd interface rename policy generated by tiny-cloud.
  • /etc/conf.d/macifrename OpenRC configuration selecting tiny-cloud's interface mapping file.

⭐ SEE ALSO ⭐

tiny-cloud.conf(5), tiny-cloud(8), interfaces(5) — go read those too, they're the supporting cast and they ate 💅

and that's the whole page bestie 🎀 this version is dated 2026-08-24 and it's NETWORK-CONFIG(5) all the way down — go configure something iconic 💜

📦 where this page comes from