From 2c4010a8d477552dd62bc9f44879d569e34976de Mon Sep 17 00:00:00 2001 From: Bob Kranson Date: Mon, 8 Dec 2025 18:24:06 -0500 Subject: [PATCH 1/2] Distinguish net config approaches --- examples/example-networks/README.md | 14 +++++++ examples/example-networks/deb-interfaces.md | 28 +++++++++++++ .../deb-interfaces/etc/network/interfaces | 5 +++ .../deb-interfaces/etc/networks | 5 +++ .../deb-interfaces/layer/v0-net-config.yaml | 25 ++++++++++++ examples/example-networks/deb-netplan.md | 39 +++++++++++++++++++ .../deb-netplan/etc/netplan/00-installer.yaml | 24 ++++++++++++ .../etc/netplan/01-network-manager-all.yaml | 5 +++ .../example-networks/deb-netplan/etc/networks | 5 +++ .../deb-netplan/layer/v1-net-config.yaml | 34 ++++++++++++++++ .../example-networks/deb-systemd-resolved.md | 28 +++++++++++++ .../deb13-systemd-resolved/etc/networks | 5 +++ .../etc/systemd/network/01-eth0.network | 15 +++++++ .../layer/v2-net-config.yaml | 29 ++++++++++++++ 14 files changed, 261 insertions(+) create mode 100644 examples/example-networks/README.md create mode 100644 examples/example-networks/deb-interfaces.md create mode 100644 examples/example-networks/deb-interfaces/etc/network/interfaces create mode 100644 examples/example-networks/deb-interfaces/etc/networks create mode 100644 examples/example-networks/deb-interfaces/layer/v0-net-config.yaml create mode 100644 examples/example-networks/deb-netplan.md create mode 100644 examples/example-networks/deb-netplan/etc/netplan/00-installer.yaml create mode 100644 examples/example-networks/deb-netplan/etc/netplan/01-network-manager-all.yaml create mode 100644 examples/example-networks/deb-netplan/etc/networks create mode 100644 examples/example-networks/deb-netplan/layer/v1-net-config.yaml create mode 100644 examples/example-networks/deb-systemd-resolved.md create mode 100644 examples/example-networks/deb13-systemd-resolved/etc/networks create mode 100644 examples/example-networks/deb13-systemd-resolved/etc/systemd/network/01-eth0.network create mode 100644 examples/example-networks/deb13-systemd-resolved/layer/v2-net-config.yaml diff --git a/examples/example-networks/README.md b/examples/example-networks/README.md new file mode 100644 index 00000000..cf282759 --- /dev/null +++ b/examples/example-networks/README.md @@ -0,0 +1,14 @@ +# Example Networks + +This folder defines example network configurations for the rpi-image-gen tooling. + +It is provided to assist image builders with selecting and setting-up a given network scheme. + +Mixing network configurations can cause maintenance and management issues. Try to stick with one approach consistently. Mixing them has difficult to diagnose issues. You may find you need to add additional or secondary network configuration settings for specific software. Consider it a work-around and inquire or advise the software maker/provider. + +1. deb-interfaces is the original/oldest approach. The /etc/network/interfaces file can declare the network device configuration. +2. deb-netplan is the next developed approach. It utilizes YAML format for network definitions and description. It integrates to the NetworkManager (nmcli) graphical network management tool. +3. deb13-systemd-resolved is the newest approach covered here. It provides rules to the systemd-resolved daemon configuration. It generates (and overwrites!) the commonly known /etc/resolv.conf file. + +I named deb13-systemd-resolved differently as that is the choice I have made for my given build. You are free to choose the others or venture to verify mix/matching them. I found the most success with Debian 13 using systemd-resolved configuration. + diff --git a/examples/example-networks/deb-interfaces.md b/examples/example-networks/deb-interfaces.md new file mode 100644 index 00000000..8d19caa1 --- /dev/null +++ b/examples/example-networks/deb-interfaces.md @@ -0,0 +1,28 @@ +# Debian Interfaces Network + +The /etc/network/interfaces is the earliest networking configuration file setup. + +I will refer to this as version 0 (zero). + +You output the named file with the correct indentations and line endings. It will be read. + +It is important that you choose only 1 networking configuration approach and stick with it! Mixing configurations can cause thrashing and confusion to the resolver and network identification (as well as create maintenance headaches!). + +See the layer defition for sample mmdebstrap instruction as shown below: + + setup-hooks: + - | + # Default network parameters (can be overridden by caller environment) + NET_ADDR="192.168.0.72/24" + NET_GW="192.168.0.1" + NAMESERVER="127.0.0.1" + IPV6_ADDR="2001:678:e68:f000::72/64" + + install -d "$1/etc/network" + cat > "$1/etc/network/interfaces" <<-EOF + auto eth0 + iface eth0 inet static + address ${NET_ADDR} + gateway ${NET_GW} + dns-nameservers ${NAMESERVER} + EOF \ No newline at end of file diff --git a/examples/example-networks/deb-interfaces/etc/network/interfaces b/examples/example-networks/deb-interfaces/etc/network/interfaces new file mode 100644 index 00000000..94c8c74f --- /dev/null +++ b/examples/example-networks/deb-interfaces/etc/network/interfaces @@ -0,0 +1,5 @@ + auto eth0 + iface eth0 inet static + address 192.168.0.72/24 + gateway 192.168.0.1 + dns-nameservers 127.0.0.1 1.1.1.1 8.8.8.8 \ No newline at end of file diff --git a/examples/example-networks/deb-interfaces/etc/networks b/examples/example-networks/deb-interfaces/etc/networks new file mode 100644 index 00000000..0b7bb83c --- /dev/null +++ b/examples/example-networks/deb-interfaces/etc/networks @@ -0,0 +1,5 @@ +default 0.0.0.0 +loopback 127.0.0.0 +link-local 169.254.0.0 +lan 192.168.0.0 + diff --git a/examples/example-networks/deb-interfaces/layer/v0-net-config.yaml b/examples/example-networks/deb-interfaces/layer/v0-net-config.yaml new file mode 100644 index 00000000..56202ca9 --- /dev/null +++ b/examples/example-networks/deb-interfaces/layer/v0-net-config.yaml @@ -0,0 +1,25 @@ +# METABEGIN +# X-Env-Layer-Name: v0-net-config +# X-Env-Layer-Desc: Linux network configuration pre-systemd and pre-netplan +# X-Env-Layer-Version: 1.0.0 +# X-Env-Layer-Category: networking +# METAEND +mmdebstrap: + suite: trixie + variant: minbase + setup-hooks: + - | + # Default network parameters (can be overridden by caller environment) + NET_ADDR="192.168.0.72/24" + NET_GW="192.168.0.1" + NAMESERVER="127.0.0.1" + IPV6_ADDR="2001:678:e68:f000::72/64" + + install -d "$1/etc/network" + cat > "$1/etc/network/interfaces" <<-EOF + auto eth0 + iface eth0 inet static + address ${NET_ADDR} + gateway ${NET_GW} + dns-nameservers ${NAMESERVER} + EOF \ No newline at end of file diff --git a/examples/example-networks/deb-netplan.md b/examples/example-networks/deb-netplan.md new file mode 100644 index 00000000..3117eff0 --- /dev/null +++ b/examples/example-networks/deb-netplan.md @@ -0,0 +1,39 @@ +# Debian Netplan Network + +The /etc/netplan/<00-70>-filename.yaml is the next or first post-interfaces networking configuration file setup. + +I will refer to this as version 1 (one). It integrates with both Systemd-resolved and NetworkManager (nmcli). + +You output the named file with the correct indentations and line endings. It will be read in alphabetical ascending order. There are references to existing netplan layers which are numbered 70 and above, so it is required to use lower numbers to invoke customizations. + +The optional 'renderer' parameter determines whether systemd-resolved or NetworkManager domain name resolution is used. + +It is important that you choose only 1 networking configuration approach and stick with it! Mixing configurations can cause thrashing and confusion to the resolver and network identification (as well as create maintenance headaches!). + +See the layer defition for sample mmdebstrap instruction as shown below: + + setup-hooks: + - | + # Default network parameters (can be overridden by caller environment) + NET_ADDR="192.168.0.72/24" + NET_GW="192.168.0.1" + NAMESERVER="127.0.0.1" + IPV6_ADDR="2001:678:e68:f000::72/64" + + install -d "$1/etc/netplan" + cat > "$1/etc/netplan/00-installer.yaml" <<-EOF + network: + version: 2 + ethernets: + eth0: + dhcp4: no + dhcp6: no + addresses: + - ${NET_ADDR} + - ${IPV6_ADDR} + ipv6-privacy: true + ipv6-address-generation: stable-privacy + gateway4: ${NET_GW} + nameservers: + addresses: [${NAMESERVER}] + EOF \ No newline at end of file diff --git a/examples/example-networks/deb-netplan/etc/netplan/00-installer.yaml b/examples/example-networks/deb-netplan/etc/netplan/00-installer.yaml new file mode 100644 index 00000000..2ca3d3be --- /dev/null +++ b/examples/example-networks/deb-netplan/etc/netplan/00-installer.yaml @@ -0,0 +1,24 @@ +network: + version: 2 + renderer: networkd + ethernets: + eth0: + dhcp4: no + dhcp4-overrides: + use-dns: false + dhcp6: no + dhcp6-overrides: + use-dns: false + optional: true + addresses: + - 192.168.0.72/24 + - 2001:678:e68:f000::72/64 + # ipv6-privacy and ipv6-address-generation are primarily for SLAAC/autoconf + # and are unnecessary for explicitly assigned static IPv6 addresses. + gateway4: 192.168.0.1 + # gateway6: 2001:678:e68:f000::1 # set this if you need an IPv6 gateway + nameservers: + addresses: + - 127.0.0.1 + - 1.1.1.1 # your ISP upstream DNS1 or other DNS + - 8.8.8.8 # your ISP upstream DNS2 or other DNS diff --git a/examples/example-networks/deb-netplan/etc/netplan/01-network-manager-all.yaml b/examples/example-networks/deb-netplan/etc/netplan/01-network-manager-all.yaml new file mode 100644 index 00000000..fd8edcd1 --- /dev/null +++ b/examples/example-networks/deb-netplan/etc/netplan/01-network-manager-all.yaml @@ -0,0 +1,5 @@ +# Let NetworkManager manage all devices on this system. +# For more information, see netplan(5). +network: + version: 2 + renderer: NetworkManager \ No newline at end of file diff --git a/examples/example-networks/deb-netplan/etc/networks b/examples/example-networks/deb-netplan/etc/networks new file mode 100644 index 00000000..0b7bb83c --- /dev/null +++ b/examples/example-networks/deb-netplan/etc/networks @@ -0,0 +1,5 @@ +default 0.0.0.0 +loopback 127.0.0.0 +link-local 169.254.0.0 +lan 192.168.0.0 + diff --git a/examples/example-networks/deb-netplan/layer/v1-net-config.yaml b/examples/example-networks/deb-netplan/layer/v1-net-config.yaml new file mode 100644 index 00000000..6aeed5b0 --- /dev/null +++ b/examples/example-networks/deb-netplan/layer/v1-net-config.yaml @@ -0,0 +1,34 @@ +# METABEGIN +# X-Env-Layer-Name: v1-net-config +# X-Env-Layer-Desc: Linux network configuration using systemd-netplan +# X-Env-Layer-Version: 1.0.0 +# X-Env-Layer-Category: networking +# METAEND +mmdebstrap: + suite: trixie + variant: minbase + setup-hooks: + - | + # Default network parameters (can be overridden by caller environment) + NET_ADDR="192.168.0.72/24" + NET_GW="192.168.0.1" + NAMESERVER="127.0.0.1" + IPV6_ADDR="2001:678:e68:f000::72/64" + + install -d "$1/etc/netplan" + cat > "$1/etc/netplan/00-installer.yaml" <<-EOF + network: + version: 2 + ethernets: + eth0: + dhcp4: no + dhcp6: no + addresses: + - ${NET_ADDR} + - ${IPV6_ADDR} + ipv6-privacy: true + ipv6-address-generation: stable-privacy + gateway4: ${NET_GW} + nameservers: + addresses: [${NAMESERVER}] + EOF \ No newline at end of file diff --git a/examples/example-networks/deb-systemd-resolved.md b/examples/example-networks/deb-systemd-resolved.md new file mode 100644 index 00000000..4cfd5932 --- /dev/null +++ b/examples/example-networks/deb-systemd-resolved.md @@ -0,0 +1,28 @@ +# Debian SystemD-Resolved Network + +The /etc/resolv.conf file is now generated and linked to /run. This is the newest networking configuration. + +I will refer to this as version 2 (two). It integrates with both Systemd-resolved and NetworkManager (nmcli). + +You output the named file with the correct indentations and line endings. It will be read the special file name -.network. You may see interface name not guarenteed in the journalctl log as this approach uses a matching rule to link to the device and modify the internal networking configuration of systemd. It then creates the resolv.conf and linked stub-resolv.conf. + +It is important that you choose only 1 networking configuration approach and stick with it! Mixing configurations can cause thrashing and confusion to the resolver and network identification (as well as create maintenance headaches!). + +See the layer definition for sample mmdebstrap instruction as shown below: + + customize-hooks: + - | + install -d "$1/etc/systemd/network" + cat > "$1/etc/systemd/network/01-eth0.network" <<-EOF + [Match] + Name=eth0 + + [Network] + DHCP=no + Address=192.168.0.72/24 + Gateway=192.168.0.1 + DNS=127.0.0.1 + DNS=1.1.1.1 + DNS=8.8.8.8 + IPv6AcceptRA=no + LinkLocalAddressing=no \ No newline at end of file diff --git a/examples/example-networks/deb13-systemd-resolved/etc/networks b/examples/example-networks/deb13-systemd-resolved/etc/networks new file mode 100644 index 00000000..0b7bb83c --- /dev/null +++ b/examples/example-networks/deb13-systemd-resolved/etc/networks @@ -0,0 +1,5 @@ +default 0.0.0.0 +loopback 127.0.0.0 +link-local 169.254.0.0 +lan 192.168.0.0 + diff --git a/examples/example-networks/deb13-systemd-resolved/etc/systemd/network/01-eth0.network b/examples/example-networks/deb13-systemd-resolved/etc/systemd/network/01-eth0.network new file mode 100644 index 00000000..0139c949 --- /dev/null +++ b/examples/example-networks/deb13-systemd-resolved/etc/systemd/network/01-eth0.network @@ -0,0 +1,15 @@ +[Match] +Name=eth0 + +[Network] +DHCP=no +Address=192.168.0.72/24 +Gateway=192.168.0.1 +DNS=127.0.0.1 +DNS=1.1.1.1 # your ISP upstream DNS1 or other DNS +DNS=8.8.8.8 # your ISP upstream DNS2 or other DNS +IPv6AcceptRA=no +LinkLocalAddressing=no + +[Link] +RequiredForOnline=yes diff --git a/examples/example-networks/deb13-systemd-resolved/layer/v2-net-config.yaml b/examples/example-networks/deb13-systemd-resolved/layer/v2-net-config.yaml new file mode 100644 index 00000000..0b1833fb --- /dev/null +++ b/examples/example-networks/deb13-systemd-resolved/layer/v2-net-config.yaml @@ -0,0 +1,29 @@ +# METABEGIN +# X-Env-Layer-Name: v2-net-config +# X-Env-Layer-Desc: Linux network configuration using systemd-resolved +# X-Env-Layer-Version: 1.0.0 +# X-Env-Layer-Category: networking +# METAEND +mmdebstrap: + suite: trixie + variant: minbase + customize-hooks: + - | + install -d "$1/etc/systemd/network" + cat > "$1/etc/systemd/network/01-eth0.network" <<-EOF + [Match] + Name=eth0 + + [Network] + DHCP=no + Address=192.168.0.72/24 + Gateway=192.168.0.1 + DNS=127.0.0.1 + DNS=1.1.1.1 + DNS=8.8.8.8 + IPv6AcceptRA=no + LinkLocalAddressing=no + + [Link] + RequiredForOnline=yes + EOF \ No newline at end of file From 22cff295bba54ebd1ac47ac2b016f6c82cada357 Mon Sep 17 00:00:00 2001 From: Bob Kranson Date: Fri, 12 Dec 2025 19:31:02 -0500 Subject: [PATCH 2/2] Align version number to file property refs, remove first-person language --- examples/example-networks/README.md | 3 +- examples/example-networks/deb-interfaces.md | 6 +- .../layer/v1-net-config-meta.yaml | 51 +++++++++++++++ ...{v0-net-config.yaml => v1-net-config.yaml} | 2 +- examples/example-networks/deb-netplan.md | 8 ++- .../deb-netplan/layer/v2-net-config-meta.yaml | 63 +++++++++++++++++++ ...{v1-net-config.yaml => v2-net-config.yaml} | 2 +- .../example-networks/deb-systemd-resolved.md | 9 ++- .../layer/v3-net-config-meta.yaml | 61 ++++++++++++++++++ ...{v2-net-config.yaml => v3-net-config.yaml} | 2 +- 10 files changed, 195 insertions(+), 12 deletions(-) create mode 100644 examples/example-networks/deb-interfaces/layer/v1-net-config-meta.yaml rename examples/example-networks/deb-interfaces/layer/{v0-net-config.yaml => v1-net-config.yaml} (95%) create mode 100644 examples/example-networks/deb-netplan/layer/v2-net-config-meta.yaml rename examples/example-networks/deb-netplan/layer/{v1-net-config.yaml => v2-net-config.yaml} (96%) create mode 100644 examples/example-networks/deb13-systemd-resolved/layer/v3-net-config-meta.yaml rename examples/example-networks/deb13-systemd-resolved/layer/{v2-net-config.yaml => v3-net-config.yaml} (94%) diff --git a/examples/example-networks/README.md b/examples/example-networks/README.md index cf282759..2737c150 100644 --- a/examples/example-networks/README.md +++ b/examples/example-networks/README.md @@ -10,5 +10,6 @@ Mixing network configurations can cause maintenance and management issues. Try t 2. deb-netplan is the next developed approach. It utilizes YAML format for network definitions and description. It integrates to the NetworkManager (nmcli) graphical network management tool. 3. deb13-systemd-resolved is the newest approach covered here. It provides rules to the systemd-resolved daemon configuration. It generates (and overwrites!) the commonly known /etc/resolv.conf file. -I named deb13-systemd-resolved differently as that is the choice I have made for my given build. You are free to choose the others or venture to verify mix/matching them. I found the most success with Debian 13 using systemd-resolved configuration. +deb13-systemd-resolved is named differently as that is the most current choice. You are free to choose the others or venture to verify mix/matching them. NetPlan and NetworkManager are more often used for Desktop GUI integrations. The systemd-resolved was found to require the least additional resources for a headless server. +Additionally the /etc/networks file is provided in the example. It declares the 0.0 network name space for internal networking utilities. The example creates a 'lan' network name for the related configuration targeting the 192.168.0.1 gateway. It effectively names the local domain to 'lan' and gives the name 'lan' for domain name when queried by networking tools. \ No newline at end of file diff --git a/examples/example-networks/deb-interfaces.md b/examples/example-networks/deb-interfaces.md index 8d19caa1..c2462c36 100644 --- a/examples/example-networks/deb-interfaces.md +++ b/examples/example-networks/deb-interfaces.md @@ -2,7 +2,7 @@ The /etc/network/interfaces is the earliest networking configuration file setup. -I will refer to this as version 0 (zero). +I will refer to this as version 1 (one). You output the named file with the correct indentations and line endings. It will be read. @@ -25,4 +25,6 @@ See the layer defition for sample mmdebstrap instruction as shown below: address ${NET_ADDR} gateway ${NET_GW} dns-nameservers ${NAMESERVER} - EOF \ No newline at end of file + EOF + +Note: Addresses, Gateway and Nameserver values will be specific to your environment and network. The Nameserver is pointed to 127.0.0.1 (localhost) to support a local DNS server prior to reaching out to internet-based DNS server(s). \ No newline at end of file diff --git a/examples/example-networks/deb-interfaces/layer/v1-net-config-meta.yaml b/examples/example-networks/deb-interfaces/layer/v1-net-config-meta.yaml new file mode 100644 index 00000000..66cbee35 --- /dev/null +++ b/examples/example-networks/deb-interfaces/layer/v1-net-config-meta.yaml @@ -0,0 +1,51 @@ +# METABEGIN +# X-Env-Layer-Name: v1-net-config-meta +# X-Env-Layer-Desc: Linux network configuration pre-systemd and pre-netplan +# X-Env-Layer-Version: 1.0.0 +# X-Env-Layer-Category: networking +# X-Env-VarRequires: IGconf_network_ipaddress +# X-Env-VarRequires-Default: 192.168.0.72 +# X-Env-VarRequires: IGconf_network_ipnetmask +# X-Env-VarRequires-Default: 24 +# X-Env-VarRequires-Description: Default IP address for the network configuration +# X-Env-VarRequires: IGconf_network_netmask +# X-Env-VarRequires-Default: 255.255.255.0 +# X-Env-VarRequires-Description: Default netmask for the network configuration +# X-Env-VarRequires: IGconf_network_gateway +# X-Env-VarRequires-Default: 192.168.0.1 +# X-Env-VarRequires-Description: Default gateway for the network configuration +# X-Env-VarRequires: IGconf_network_dns0 +# X-Env-VarRequires-Default: 127.0.0.1 +# X-Env-VarRequires: IGconf_network_dns1 +# X-Env-VarRequires-Default: 1.1.1.1 +# X-Env-VarRequires: IGconf_network_dns2 +# X-Env-VarRequires-Default: 8.8.8.8 +# X-Env-VarRequires-Description: Default DNS server for the network configuration +# X-Env-VarRequires: IGconf_network_domain +# X-Env-VarRequires-Default: lan +# X-Env-VarRequires-Description: Default domain name for the network configuration +# METAEND +mmdebstrap: + suite: trixie + variant: minbase + customize-hooks: + - | + #!/bin/bash + # Set up network configuration based on environment variables + IP_ADDRESS=${IGconf_network_ipaddress:-192.168.0.53} + NETMASK=${IGconf_network_ipnetmask:-24} + GATEWAY=${IGconf_network_gateway:-192.168.0.1} + DNS0=${IGconf_network_dns0:-127.0.0.1} + DNS1=${IGconf_network_dns1:-8.8.8.8} + DNS2=${IGconf_network_dns2:-1.1.1.1} + DOMAIN=${IGconf_network_domain:-lan} + + # Default network parameters (can be overridden by caller environment) + install -d "$1/etc/network" + cat > "$1/etc/network/interfaces" <<-EOF + auto eth0 + iface eth0 inet static + address $IP_ADDRESS/$NETMASK + gateway $GATEWAY + dns-nameservers $DNS0 $DNS1 $DNS2 + EOF \ No newline at end of file diff --git a/examples/example-networks/deb-interfaces/layer/v0-net-config.yaml b/examples/example-networks/deb-interfaces/layer/v1-net-config.yaml similarity index 95% rename from examples/example-networks/deb-interfaces/layer/v0-net-config.yaml rename to examples/example-networks/deb-interfaces/layer/v1-net-config.yaml index 56202ca9..5ecdf447 100644 --- a/examples/example-networks/deb-interfaces/layer/v0-net-config.yaml +++ b/examples/example-networks/deb-interfaces/layer/v1-net-config.yaml @@ -1,5 +1,5 @@ # METABEGIN -# X-Env-Layer-Name: v0-net-config +# X-Env-Layer-Name: v1-net-config # X-Env-Layer-Desc: Linux network configuration pre-systemd and pre-netplan # X-Env-Layer-Version: 1.0.0 # X-Env-Layer-Category: networking diff --git a/examples/example-networks/deb-netplan.md b/examples/example-networks/deb-netplan.md index 3117eff0..42218d19 100644 --- a/examples/example-networks/deb-netplan.md +++ b/examples/example-networks/deb-netplan.md @@ -2,9 +2,9 @@ The /etc/netplan/<00-70>-filename.yaml is the next or first post-interfaces networking configuration file setup. -I will refer to this as version 1 (one). It integrates with both Systemd-resolved and NetworkManager (nmcli). +Refer to this as version 2 (two). It integrates with both Systemd-resolved and NetworkManager (nmcli). -You output the named file with the correct indentations and line endings. It will be read in alphabetical ascending order. There are references to existing netplan layers which are numbered 70 and above, so it is required to use lower numbers to invoke customizations. +Output the named file with the correct indentations and line endings. It will be read in alphabetical ascending order. There are references to existing netplan layers which are numbered 70 and above, so it is required to use lower numbers to invoke customizations. The optional 'renderer' parameter determines whether systemd-resolved or NetworkManager domain name resolution is used. @@ -36,4 +36,6 @@ See the layer defition for sample mmdebstrap instruction as shown below: gateway4: ${NET_GW} nameservers: addresses: [${NAMESERVER}] - EOF \ No newline at end of file + EOF + +Note: Addresses, Gateway and Nameserver values will be specific to your environment and network. The Nameserver is pointed to 127.0.0.1 (localhost) to support a local DNS server prior to reaching out to internet-based DNS server(s). \ No newline at end of file diff --git a/examples/example-networks/deb-netplan/layer/v2-net-config-meta.yaml b/examples/example-networks/deb-netplan/layer/v2-net-config-meta.yaml new file mode 100644 index 00000000..1f6ce764 --- /dev/null +++ b/examples/example-networks/deb-netplan/layer/v2-net-config-meta.yaml @@ -0,0 +1,63 @@ +# METABEGIN +# X-Env-Layer-Name: v2-net-config-meta +# X-Env-Layer-Desc: Linux network configuration using systemd-netplan +# X-Env-Layer-Version: 1.0.0 +# X-Env-Layer-Category: networking +# X-Env-VarRequires: IGconf_network_ipaddress +# X-Env-VarRequires-Default: 192.168.0.72 +# X-Env-VarRequires: IGconf_network_ipnetmask +# X-Env-VarRequires-Default: 24 +# X-Env-VarRequires-Description: Default IP address for the network configuration +# X-Env-VarRequires: IGconf_network_ipv6address +# X-Env-VarRequires-Default: 2001:678:e68:f000::72/64 +# X-Env-VarRequires-Description: Default IPv6 address for the network configuration +# X-Env-VarRequires: IGconf_network_netmask +# X-Env-VarRequires-Default: 255.255.255.0 +# X-Env-VarRequires-Description: Default netmask for the network configuration +# X-Env-VarRequires: IGconf_network_gateway +# X-Env-VarRequires-Default: 192.168.0.1 +# X-Env-VarRequires-Description: Default gateway for the network configuration +# X-Env-VarRequires: IGconf_network_dns0 +# X-Env-VarRequires-Default: 127.0.0.1 +# X-Env-VarRequires: IGconf_network_dns1 +# X-Env-VarRequires-Default: 1.1.1.1 +# X-Env-VarRequires: IGconf_network_dns2 +# X-Env-VarRequires-Default: 8.8.8.8 +# X-Env-VarRequires-Description: Default DNS server for the network configuration +# X-Env-VarRequires: IGconf_network_domain +# X-Env-VarRequires-Default: lan +# X-Env-VarRequires-Description: Default domain name for the network configuration +# METAEND +mmdebstrap: + suite: trixie + variant: minbase + setup-hooks: + - | + #!/bin/bash + # Set up network configuration based on environment variables + IP_ADDRESS=${IGconf_network_ipaddress:-192.168.0.53} + NETMASK=${IGconf_network_ipnetmask:-24} + GATEWAY=${IGconf_network_gateway:-192.168.0.1} + DNS0=${IGconf_network_dns0:-127.0.0.1} + DNS1=${IGconf_network_dns1:-8.8.8.8} + DNS2=${IGconf_network_dns2:-1.1.1.1} + DOMAIN=${IGconf_network_domain:-lan} + + # Default network parameters (can be overridden by caller environment) + install -d "$1/etc/netplan" + cat > "$1/etc/netplan/00-installer.yaml" <<-EOF + network: + version: 2 + ethernets: + eth0: + dhcp4: no + dhcp6: no + addresses: + - ${IP_ADDRESS}/${NETMASK} + - ${IGconf_network_ipv6address:-2001:678:e68:f000::72/64} + ipv6-privacy: true + ipv6-address-generation: stable-privacy + gateway4: ${GATEWAY} + nameservers: + addresses: [${DNS0}, ${DNS1}, ${DNS2}] + EOF \ No newline at end of file diff --git a/examples/example-networks/deb-netplan/layer/v1-net-config.yaml b/examples/example-networks/deb-netplan/layer/v2-net-config.yaml similarity index 96% rename from examples/example-networks/deb-netplan/layer/v1-net-config.yaml rename to examples/example-networks/deb-netplan/layer/v2-net-config.yaml index 6aeed5b0..47704506 100644 --- a/examples/example-networks/deb-netplan/layer/v1-net-config.yaml +++ b/examples/example-networks/deb-netplan/layer/v2-net-config.yaml @@ -1,5 +1,5 @@ # METABEGIN -# X-Env-Layer-Name: v1-net-config +# X-Env-Layer-Name: v2-net-config # X-Env-Layer-Desc: Linux network configuration using systemd-netplan # X-Env-Layer-Version: 1.0.0 # X-Env-Layer-Category: networking diff --git a/examples/example-networks/deb-systemd-resolved.md b/examples/example-networks/deb-systemd-resolved.md index 4cfd5932..cd187252 100644 --- a/examples/example-networks/deb-systemd-resolved.md +++ b/examples/example-networks/deb-systemd-resolved.md @@ -2,9 +2,9 @@ The /etc/resolv.conf file is now generated and linked to /run. This is the newest networking configuration. -I will refer to this as version 2 (two). It integrates with both Systemd-resolved and NetworkManager (nmcli). +Refer to this as version 3 (three). It integrates with both Systemd-resolved and NetworkManager (nmcli). -You output the named file with the correct indentations and line endings. It will be read the special file name -.network. You may see interface name not guarenteed in the journalctl log as this approach uses a matching rule to link to the device and modify the internal networking configuration of systemd. It then creates the resolv.conf and linked stub-resolv.conf. +Output the named file with the correct indentations and line endings. It will be read as a special file name -.network. Logs may reveal interface name not guarenteed in the journalctl log as this approach uses a matching rule to link to the device and modify the internal networking configuration of systemd. It then creates the resolv.conf and linked stub-resolv.conf. It is important that you choose only 1 networking configuration approach and stick with it! Mixing configurations can cause thrashing and confusion to the resolver and network identification (as well as create maintenance headaches!). @@ -25,4 +25,7 @@ See the layer definition for sample mmdebstrap instruction as shown below: DNS=1.1.1.1 DNS=8.8.8.8 IPv6AcceptRA=no - LinkLocalAddressing=no \ No newline at end of file + LinkLocalAddressing=no + EOF + +Note: Address, Gateway and DNS values will be specific to your environment and network. The first DNS is pointed to 127.0.0.1 (localhost) to support a local DNS server prior to reaching out to internet-based DNS server(s). \ No newline at end of file diff --git a/examples/example-networks/deb13-systemd-resolved/layer/v3-net-config-meta.yaml b/examples/example-networks/deb13-systemd-resolved/layer/v3-net-config-meta.yaml new file mode 100644 index 00000000..cac0684d --- /dev/null +++ b/examples/example-networks/deb13-systemd-resolved/layer/v3-net-config-meta.yaml @@ -0,0 +1,61 @@ +# METABEGIN +# X-Env-Layer-Name: v3-net-config +# X-Env-Layer-Desc: Linux network configuration using systemd-resolved +# X-Env-Layer-Version: 1.0.0 +# X-Env-Layer-Category: networking +# X-Env-VarRequires: IGconf_network_ipaddress +# X-Env-VarRequires-Default: 192.168.0.72 +# X-Env-VarRequires: IGconf_network_ipnetmask +# X-Env-VarRequires-Default: 24 +# X-Env-VarRequires-Description: Default IP address for the network configuration +# X-Env-VarRequires-Description: Default IPv6 address for the network configuration +# X-Env-VarRequires: IGconf_network_netmask +# X-Env-VarRequires-Default: 255.255.255.0 +# X-Env-VarRequires-Description: Default netmask for the network configuration +# X-Env-VarRequires: IGconf_network_gateway +# X-Env-VarRequires-Default: 192.168.0.1 +# X-Env-VarRequires-Description: Default gateway for the network configuration +# X-Env-VarRequires: IGconf_network_dns0 +# X-Env-VarRequires-Default: 127.0.0.1 +# X-Env-VarRequires: IGconf_network_dns1 +# X-Env-VarRequires-Default: 1.1.1.1 +# X-Env-VarRequires: IGconf_network_dns2 +# X-Env-VarRequires-Default: 8.8.8.8 +# X-Env-VarRequires-Description: Default DNS server for the network configuration +# X-Env-VarRequires: IGconf_network_domain +# X-Env-VarRequires-Default: lan +# X-Env-VarRequires-Description: Default domain name for the network configuration +# METAEND +mmdebstrap: + suite: trixie + variant: minbase + customize-hooks: + - | + #!/bin/bash + # Set up network configuration based on environment variables + IP_ADDRESS=${IGconf_network_ipaddress:-192.168.0.53} + NETMASK=${IGconf_network_ipnetmask:-24} + GATEWAY=${IGconf_network_gateway:-192.168.0.1} + DNS0=${IGconf_network_dns0:-127.0.0.1} + DNS1=${IGconf_network_dns1:-8.8.8.8} + DNS2=${IGconf_network_dns2:-1.1.1.1} + DOMAIN=${IGconf_network_domain:-lan} + + install -d "$1/etc/systemd/network" + cat > "$1/etc/systemd/network/01-eth0.network" <<-EOF + [Match] + Name=eth0 + + [Network] + DHCP=no + Address=${IP_ADDRESS}/${NETMASK} + Gateway=${GATEWAY} + DNS=${DNS0} + DNS=${DNS1} + DNS=${DNS2} + IPv6AcceptRA=no + LinkLocalAddressing=no + + [Link] + RequiredForOnline=yes + EOF \ No newline at end of file diff --git a/examples/example-networks/deb13-systemd-resolved/layer/v2-net-config.yaml b/examples/example-networks/deb13-systemd-resolved/layer/v3-net-config.yaml similarity index 94% rename from examples/example-networks/deb13-systemd-resolved/layer/v2-net-config.yaml rename to examples/example-networks/deb13-systemd-resolved/layer/v3-net-config.yaml index 0b1833fb..06c8e89d 100644 --- a/examples/example-networks/deb13-systemd-resolved/layer/v2-net-config.yaml +++ b/examples/example-networks/deb13-systemd-resolved/layer/v3-net-config.yaml @@ -1,5 +1,5 @@ # METABEGIN -# X-Env-Layer-Name: v2-net-config +# X-Env-Layer-Name: v3-net-config # X-Env-Layer-Desc: Linux network configuration using systemd-resolved # X-Env-Layer-Version: 1.0.0 # X-Env-Layer-Category: networking