This directory contains community-contributed networking examples for rpi-image-gen.
These examples are intended for evaluation, adaptation, and testing. As with other content under contrib, they are provided on a best-effort basis and may require updates as upstream layers evolve.
The examples demonstrate three common Linux networking approaches on Debian-based images:
- deb-interfaces using ifupdown-style configuration in /etc/network/interfaces
- deb-netplan using Netplan YAML in /etc/netplan/00-installer.yaml
- deb13-systemd-resolved using systemd-networkd units in /etc/systemd/network/01-eth0.network
Choose one primary network stack per image when possible. Mixing multiple configuration stacks in the same image can produce ordering conflicts, duplicate state, and hard-to-diagnose behavior.
The checked-in /etc paths under each example directory are intentional reference examples. They are provided to help users identify which final filesystem paths are targeted by build-time verification checks.
| Stack | Headless | Server | Desktop | Notes |
|---|---|---|---|---|
| deb-interfaces (ifupdown) | Good fit | Good fit | Limited fit | Minimal and predictable; common for static server-style setups. |
| deb-netplan | Good fit | Good fit | Good fit | Flexible YAML model; commonly used where desktop integration tooling is expected. |
| deb13-systemd-resolved (systemd-networkd + resolved) | Good fit | Good fit | Conditional fit | Lightweight and service-oriented; desktop use may require coordination with NetworkManager policies. |
This folder follows the contrib/net purpose described in contrib/README.adoc:
- It provides networking-specific additions as optional examples.
- It is not required for core rpi-image-gen functionality.
- It should be treated as reference material that may lag mainline changes.
When contributing updates here, prefer small, reviewable changes and avoid embedding secrets or environment-specific credentials.
This contribution is contributed by devopsbob of Kranson Enterprises, Michigan, USA, for community review and upstream consideration.
Use the driver script to build each example layer independently and verify expected output files.
Command:
./run-example-layers.sh
The script runs three builds:
- deb-interfaces with v1-net-config
- deb-netplan with v2-net-config
- deb13-systemd-resolved with v3-net-config
Verification checks:
- v1 verifies /etc/network/interfaces contains iface eth0 inet static
- v2 verifies /etc/netplan/00-installer.yaml contains ethernets:
- v3 verifies /etc/systemd/network/01-eth0.network contains DHCP=no
These checks validate target paths in the generated image filesystem. The repository copies of files under each example's /etc tree are guidance artifacts for learning and comparison.
Exit codes:
- 0 means all builds and checks passed
- 1 means one or more builds or checks failed
These examples align with widely used Linux networking conventions and open-source tooling interfaces:
- ifupdown conventions for interface declarations in /etc/network/interfaces
- Netplan schema-driven YAML for network definitions
- systemd-networkd unit model via .network files
- resolver behavior managed through systemd-resolved where enabled
Operational guidance:
- Keep addressing, gateway, and DNS policy in a single authoritative stack.
- Use deterministic interface matching and explicit static settings for headless systems.
- Validate generated config with native tools before deployment.
- Document local overrides if combining stack components is unavoidable.
The same stack can be used in many places, but operational priorities differ by environment.
- Personal home: Prefer simple static or DHCP-centric layouts. Keep one clear DNS policy and document local router or resolver assumptions.
- Small business: Use explicit addressing plans, reproducible host naming, and clear rollback steps. Standardize one stack per device class.
- Large enterprise: Use declarative configuration with strict change control, inventory-driven addressing, and integration with central DNS/NTP/security controls.
After generating an image, validate with native tools:
- interfaces: ifquery --list and ifquery eth0
- netplan: netplan generate and netplan get
- systemd-networkd: networkctl status and systemd-analyze verify /etc/systemd/network/*.network
- resolver path: resolvectl status and ls -l /etc/resolv.conf
- contrib scope and support model: ../README.adoc
- interfaces format: man 5 interfaces
- Netplan format and behavior: https://netplan.readthedocs.io/
- systemd network units: man 5 systemd.network
- resolver service behavior: man 8 systemd-resolved and man 5 resolv.conf
- private IPv4 addressing: RFC 1918
- IPv6 SLAAC: RFC 4862
- unique local IPv6 addresses: RFC 4193