7 files changed, 377 insertions, 105 deletions
diff --git a/share/doc/bugs.txt b/share/doc/bugs.txt
new file mode 100644
index 0000000..a49f9d8
--- /dev/null
+++ b/share/doc/bugs.txt
@@ -0,0 +1,51 @@
+container-tools: Bugs
+=====================
+
+
+1. veth not removed on container stop
+-------------------------------------
+
+When stopping a container, it irregularly but reproducibly happen that the
+corresponding veth device of the container is not shutdown, making it
+impossible to start the container again.
+
+This is caused by a kernel bug not cleaning up veth devices on container
+collapsing. The veth device is supposed to be go away automatically after
+some time, definitely after a reboot though.
+
+A manual workaround is to shutdown the veth device manually with:
+
+# ip link delete ${VETH_DEVICE}
+
+There is a patch for it, see for more information:
+http://lists.linuxfoundation.org/pipermail/containers/2012-October/030533.html
+
+FIXME: add nspan message about it here
+
+2. bug with machine.slices etc
+------------------------------
+
+FIXME
+
+3. veth length
+--------------
+
+systemd creates veth devices on the fly and names them vb-$NAME, where NAME is the
+container name truncated to the first 10 characters.
+
+Problem: if you have several containers named with the first 10 characters to be
+identical, systemd will not be able to create a new veth device.
+
+4. root console
+---------------
+
+# Let's attach a console to the example container.
+#
+# Note: we did not create a user in the container,
+# logging in as root over a pseudo-terminal is
+# considered insecure by pam and will fail.
+cnt console -n example.net
+# Let's disable pam_securetty.so for demonstration purpose only.
+vi /var/lib/machines/example.net/etc/pam.d/login
+# Now login as root will work.
+cnt console -n example.net
diff --git a/share/doc/examples/bullseye.cfg b/share/doc/examples/bookworm.cfg
index 4582c9f..1f878f4 100644
--- a/share/doc/examples/bullseye.cfg
+++ b/share/doc/examples/bookworm.cfg
@@ -1,4 +1,4 @@
-# example for automated Debian 11 (bullseye) based container building
+# example for automated Debian 12 (bookworm) based container building
 # using: sudo container build -s debian
 
 debconf debconf/priority select critical
@@ -9,12 +9,12 @@ compute-tools container/mode select debian
 #compute-tools container/preseed-files string 
 #compute-tools container/include-preseed-files string 
 
-compute-tools container/distribution select bullseye
+compute-tools container/distribution select bookworm
 #compute-tools container/parent-distribution select 
 
 compute-tools container/architecture select auto
 
-compute-tools container/archives multiselect bullseye-security, bullseye-updates
+compute-tools container/archives multiselect bookworm-security, bookworm-updates
 #compute-tools container/parent-archives multiselect 
 
 compute-tools container/mirror string https://deb.debian.org/debian
diff --git a/share/doc/examples/container-images.sh b/share/doc/examples/container-images.sh
index e6947e3..b711048 100755
--- a/share/doc/examples/container-images.sh
+++ b/share/doc/examples/container-images.sh
@@ -1,6 +1,6 @@
 #!/bin/sh
 
-# Copyright (C) 2014-2021 Daniel Baumann <daniel.baumann@open-infrastructure.net>
+# Copyright (C) 2014-2022 Daniel Baumann <daniel.baumann@open-infrastructure.net>
 #
 # SPDX-License-Identifier: GPL-3.0+
 #
@@ -24,7 +24,7 @@
 set -e
 
 ARCHITECTURES="amd64 i386"
-DISTRIBUTIONS="stretch buster bullseye sid"
+DISTRIBUTIONS="buster bullseye bookworm sid"
 MIRROR="https://deb.debian.org/debian"
 INCLUDE="dbus"
 
diff --git a/share/doc/examples/fuchur-backports.cfg b/share/doc/examples/graograman-backports.cfg
index c02e776..d1d2640 100644
--- a/share/doc/examples/fuchur-backports.cfg
+++ b/share/doc/examples/graograman-backports.cfg
@@ -1,4 +1,4 @@
-# example for automated Progress Linux 6.99 (fuchur-backports) container building
+# example for automated Progress Linux 7.99 (graograman-backports) container building
 # using: sudo container build -s progress-linux
 
 debconf debconf/priority select critical
@@ -9,12 +9,12 @@ compute-tools container/mode select progress-linux
 #compute-tools container/preseed-files string 
 #compute-tools container/include-preseed-files string 
 
-compute-tools container/distribution select fuchur-backports
+compute-tools container/distribution select graograman-backports
 #compute-tools container/parent-distribution select 
 
 compute-tools container/architecture select auto
 
-compute-tools container/archives multiselect fuchur-security, fuchur-updates, fuchur-extras, fuchur-backports, fuchur-backports-extras
+compute-tools container/archives multiselect graograman-security, graograman-updates, graograman-extras, graograman-backports, graograman-backports-extras
 #compute-tools container/parent-archives multiselect 
 
 compute-tools container/mirror string https://deb.progress-linux.org/packages
@@ -23,8 +23,8 @@ compute-tools container/mirror-security string https://deb.progress-linux.org/pa
 compute-tools container/parent-mirror string https://deb.debian.org/debian
 compute-tools container/parent-mirror-security string https://security.debian.org
 
-compute-tools container/archive-areas multiselect main, contrib, non-free
-compute-tools container/parent-archive-areas multiselect main, contrib, non-free
+compute-tools container/archive-areas multiselect main, contrib, non-free, non-free-firmware
+compute-tools container/parent-archive-areas multiselect main, contrib, non-free, non-free-firmware
 
 compute-tools container/packages string knot-resolver openssh-server
 
diff --git a/share/doc/host-setup.old.txt b/share/doc/host-setup.old.txt
new file mode 100644
index 0000000..69368d1
--- /dev/null
+++ b/share/doc/host-setup.old.txt
@@ -0,0 +1,230 @@
+compute-tools: Host Setup (with ifupdown)
+=========================================
+
+
+1. Debian Packages
+-------------------
+
+apt install bridge-utils ifenslave vlan
+
+
+2. Boot Parameters
+------------------
+
+2.1 CGroup Memory Controller (optional)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In order to enable the memory controller the following boot parameter needs to be used:
+
+	cgroup_enable=memory
+
+
+2.2 CGroup Swap Controller (optional)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In order to enable the swap controller the following boot parameter needs to be used:
+
+	swapaccount=1
+
+2.3 vsyscall (legacy)
+~~~~~~~~~~~~~~~~~~~~~
+
+In order to be able to execute binaries linked to older libc versions
+(<= wheezy) on newer linux versions (>= buster), add the following boot
+parameter (see #881813 for more information):
+
+	vsyscall=emulate
+
+
+3. Networking
+~~~~~~~~~~~~~
+
+3.1 Configure Network Bridge
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+3.1.1 Bridge: 1 Interface, standalone, DHCP
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+cat > /etc/network/interfaces << EOF
+# /etc/network/interfaces
+
+source /etc/network/interfaces.d/*
+
+auto lo
+iface lo inet loopback
+
+iface eno1 inet manual
+
+auto bridge0
+iface bridge0 inet dhcp
+	bridge_ports	eno1
+	bridge_fd	0
+	bridge_maxwait	0
+	bridge_stp	0
+EOF
+
+
+3.1.2 Bridge: 1 Interface, standalone, static
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+cat > /etc/network/interfaces << EOF
+# /etc/network/interfaces
+
+source /etc/network/interfaces.d/*
+
+auto lo
+iface lo inet loopback
+
+iface eno1 inet manual
+
+auto bridge0
+iface bridge0 inet static
+	address		10.0.0.2
+	gateway		10.0.0.1
+	netmask		24
+
+	pre-up		ip link set eno1 down
+	pre-up		ip link set eno1 up
+
+	bridge_ports	eno1
+	bridge_fd	0
+	bridge_maxwait	0
+	bridge_stp	0
+EOF
+
+
+3.1.3 Bridge: 2 logical Interfaces, subnet, static
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+cat > /etc/network/interfaces << EOF
+# /etc/network/interfaces
+
+source /etc/network/interfaces.d/*
+
+auto lo
+iface lo inet loopback
+
+allow-hotplug eno1
+iface eno1 inet dhcp
+
+auto bridge0
+iface bridge0 inet static
+	address		10.0.0.1
+	netmask		24
+
+	pre-up		ip link add name bridge0 type bridge
+	post-down	ip link delete bridge0 type bridge
+
+	bridge_fd	0
+	bridge_maxwait	0
+	bridge_stp	0
+EOF
+
+
+3.1.4 Bridge: 3 physical Interfaces, vlan, bonding, static
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+cat > /etc/network/interfaces << EOF
+# /etc/network/interfaces
+
+source /etc/network/interfaces.d/*
+
+auto lo
+iface lo inet loopback
+
+allow-hotplug eno1
+iface eno1 inet dhcp
+
+iface eno2 inet manual
+
+iface eno3 inet manual
+
+auto bond0
+iface bond0 inet manual
+	up			ip link set bond0 up
+	down			ip link set bond0 down
+
+	slaves			eno2 eno3
+
+	bond-mode		4
+	bond-miimon		100
+	bond-downdelay		200
+	bond-updelay		200
+	bond-lacp-rate		1
+	bond-xmit-hash-policy	layer2+3
+
+iface bond0.100 inet manual
+	vlan-raw-device bond0
+
+auto bridge-100
+iface bridge-100 inet static
+	address			10.100.0.2
+	netmask			24
+
+	bridge_ports		bond0.100
+	bridge_fd		0
+	bridge_maxwait		0
+	bridge_stp		0
+EOF
+
+
+4. Enabling user namespace for unprivileged containers
+------------------------------------------------------
+
+Linux supports unprivileged containers with the user namespace.
+By default the user namespace is disabled on Debian systems (see #898446).
+To enable user namespace, edit the following file for a permant change:
+
+  /etc/sysctl.d/zz-compute-tools.conf
+  sysctl -p
+
+or enable it manually with:
+
+  echo 1 > /proc/sys/kernel/unprivileged_userns_clone
+
+Note that containers need to be started with the correct
+configuration in /etc/compute-tools/container/config to run unpriviled
+(private-users option).
+
+
+5. Enabling container-shell
+---------------------------
+
+Managing privileged containers requires root privileges. In order to allow
+unprivileged users to manage privileged containers without granting them
+privileges or accounts, the container-shell can be used together with sudo
+and a container user.
+
+  sudo adduser --gecos "compute-tools,,," \
+	--home /var/lib/open-infrastructure/container-shell \
+	--shell /usr/bin/container-shell
+
+
+6. IPv4 and IPv6 dual-stack
+---------------------------
+
+Examples for /etc/network/interfaces above work for IPv6 too when using correct
+IPv6 addresses and netmasks.
+
+In order to use dual-stack, bridges must have a IPv4 address assigned
+(can be a dummy one from a privacy range or 127.0.0.0/8).
+
+Let me repeat: dual-stack only works when you assign a primary IPv6 address
+(private or public, doesn't matter) *and* add an additional IPv4 address.
+Yes, the IPv4 address can be a private address, the containers can still
+have a public IPv4 address.
+
+A complete example looks like this:
+
+auto bridge0
+iface bridge0 inet6 static
+	address			2a07:6b47:4::4:1
+	netmask			48
+
+	up			ip addr add 127.4.4.1 dev $IFACE
+	down			ip addr del 127.4.4.1 dev $IFACE
+
+	bridge_fd		0
+	bridge_maxwait		0
+	bridge_stp		0
+	bridge-mcquerier	1
diff --git a/share/doc/host-setup.txt b/share/doc/host-setup.txt
index 9a9ec94..083e1aa 100644
--- a/share/doc/host-setup.txt
+++ b/share/doc/host-setup.txt
@@ -1,11 +1,14 @@
-compute-tools: Host Setup
-=========================
+compute-tools: Host Setup (with systemd-networkd)
+=================================================
 
 
 1. Debian Packages
 -------------------
 
-apt install bridge-utils ifenslave vlan
+apt install systemd-networkd bridge-utils
+
+Make sure to enable networkd (sudo systemctl enable systemd-networkd)
+and convert /etc/network/interfaces (see systemd-networkd documentation).
 
 
 2. Boot Parameters
@@ -45,126 +48,110 @@ parameter (see #881813 for more information):
 3.1.1 Bridge: 1 Interface, standalone, DHCP
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-cat > /etc/network/interfaces << EOF
-# /etc/network/interfaces
-
-source /etc/network/interfaces.d/*
-
-auto lo
-iface lo inet loopback
+cat > /etc/systemd/network/bridge0.netdev << EOF
+[NetDev]
+Name=bridge0
+Kind=bridge
+EOF
 
-iface eno1 inet manual
+cat > /etc/systemd/network/bridge0.network << EOF
+[Match]
+Name=bridge-0
 
-auto bridge0
-iface bridge0 inet dhcp
-	bridge_ports	eno1
-	bridge_fd	0
-	bridge_maxwait	0
-	bridge_stp	0
+[Network]
+DHCP=yes
 EOF
 
 
 3.1.2 Bridge: 1 Interface, standalone, static
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-cat > /etc/network/interfaces << EOF
-# /etc/network/interfaces
-
-source /etc/network/interfaces.d/*
-
-auto lo
-iface lo inet loopback
-
-iface eno1 inet manual
-
-auto bridge0
-iface bridge0 inet static
-	address		10.0.0.2
-	gateway		10.0.0.1
-	netmask		24
-
-	pre-up		ip link set eno1 down
-	pre-up		ip link set eno1 up
-
-	bridge_ports	eno1
-	bridge_fd	0
-	bridge_maxwait	0
-	bridge_stp	0
+cat > /etc/systemd/network/bridge0.netdev << EOF
+[NetDev]
+Name=bridge0
+Kind=bridge
 EOF
 
+cat > /etc/systemd/network/bridge0.network << EOF
+[Match]
+Name=bridge-0
 
-3.1.3 Bridge: 2 logical Interfaces, subnet, static
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-cat > /etc/network/interfaces << EOF
-# /etc/network/interfaces
-
-source /etc/network/interfaces.d/*
-
-auto lo
-iface lo inet loopback
+[Network]
+Address=10.0.0.2/24
+Gateway=10.0.0.1
+EOF
 
-allow-hotplug eno1
-iface eno1 inet dhcp
 
-auto bridge0
-iface bridge0 inet static
-	address		10.0.0.1
-	netmask		24
+3.1.3 Bridge: 3 physical Interfaces, vlan, bonding, static
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-	pre-up		ip link add name bridge0 type bridge
-	post-down	ip link delete bridge0 type bridge
+cat > /etc/systemd/network/eno2.network<< EOF
+[Match]
+Name=eno2
 
-	bridge_fd	0
-	bridge_maxwait	0
-	bridge_stp	0
+[Network]
+Bond=bond0
 EOF
 
+cat > /etc/systemd/network/eno3.network<< EOF
+[Match]
+Name=eno3
 
-3.1.4 Bridge: 3 physical Interfaces, vlan, bonding, static
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-cat > /etc/network/interfaces << EOF
-# /etc/network/interfaces
-
-source /etc/network/interfaces.d/*
+[Network]
+Bond=bond0
+EOF
 
-auto lo
-iface lo inet loopback
+cat > /etc/systemd/network/bond0.netdev << EOF
+[NetDev]
+Name=bond0
+Kind=bond
+
+[Bond]
+Mode=802.3ad
+TransmitHashPolicy=layer3+4
+MIIMonitorSec=0.1
+UpDelaySec=0.2
+DownDelaySec=0.2
+EOF
 
-allow-hotplug eno1
-iface eno1 inet dhcp
+cat > /etc/systemd/network/bond0.network << EOF
+[Match]
+Name=bond0
 
-iface eno2 inet manual
+[Network]
+VLAN=100
+EOF
 
-iface eno3 inet manual
+cat > /etc/systemd/network/vlan-100.netdev << EOF
+[NetDev]
+Name=vlan-100
+Kind=vlan
 
-auto bond0
-iface bond0 inet manual
-	up			ip link set bond0 up
-	down			ip link set bond0 down
+[VLAN]
+Id=100
+EOF
 
-	slaves			eno2 eno3
+cat > /etc/systemd/network/vlan-100.netdev << EOF
+[Match]
+Name=vlan-100
 
-	bond-mode		4
-	bond-miimon		100
-	bond-downdelay		200
-	bond-updelay		200
-	bond-lacp-rate		1
-	bond-xmit-hash-policy	layer2+3
+[Network]
+Bridge=bridge-100
+EOF
 
-iface bond0.100 inet manual
-	vlan-raw-device bond0
+cat > /etc/systemd/network/bridge-100.netdev << EOF
+[NetDev]
+Name=bridge-100
+Kind=bridge
+EOF
 
-auto bridge-100
-iface bridge-100 inet static
-	address			10.100.0.2
-	netmask			24
+cat > /etc/systemd/network/bridge-100.network << EOF
+[Match]
+Name=bridge-100
 
-	bridge_ports		bond0.100
-	bridge_fd		0
-	bridge_maxwait		0
-	bridge_stp		0
+[Network]
+Address=10.100.0.2/24
+Gateway=10.100.0.1
 EOF
 
 
diff --git a/share/doc/todo.txt b/share/doc/todo.txt
new file mode 100644
index 0000000..61f6309
--- /dev/null
+++ b/share/doc/todo.txt
@@ -0,0 +1,4 @@
+TODO
+====
+
+  * i18n and l10n for manpages.