Distinguish net config approaches

examples/example-networks/README.md

@@ -0,0 +1,15 @@
+# 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.
+
+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.

examples/example-networks/deb-interfaces.md

@@ -0,0 +1,30 @@
+# Debian Interfaces Network
+
+The /etc/network/interfaces is the earliest networking configuration file setup.
+
+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.
+
+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
+
+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).

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

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
+

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

examples/example-networks/deb-interfaces/layer/v1-net-config.yaml

@@ -0,0 +1,25 @@
+# METABEGIN
+# 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
+# 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

examples/example-networks/deb-netplan.md

@@ -0,0 +1,41 @@
+# Debian Netplan Network
+
+The /etc/netplan/<00-70>-filename.yaml is the next or first post-interfaces networking configuration file setup.
+
+Refer to this as version 2 (two). It integrates with both Systemd-resolved and NetworkManager (nmcli).
+
+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
+
+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).

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

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

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
+

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    

examples/example-networks/deb-netplan/layer/v2-net-config.yaml

@@ -0,0 +1,34 @@
+# METABEGIN
+# 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
+# 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    

examples/example-networks/deb-systemd-resolved.md

@@ -0,0 +1,31 @@
+# Debian SystemD-Resolved Network
+
+The /etc/resolv.conf file is now generated and linked to /run. This is the newest networking configuration.
+
+Refer to this as version 3 (three). It integrates with both Systemd-resolved and NetworkManager (nmcli).
+
+Output the named file with the correct indentations and line endings. It will be read as a special file name <priority>-<device>.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!).
+
+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
+      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).

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
+

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