Merge branch 'pod2man' into 'main'

add documentation in pod2man format

Closes #2

See merge request helmutg/debvm!11

3 files changed, 143 insertions, 4 deletions

diff --git a/README.md b/README.md
index fd1c8cc..8109b2a 100644
--- a/README.md
+++ b/README.md
@@ -45,8 +45,8 @@ contains the root filesystem of a (Debian) installation including an init
 system and a kernel. There is no partition table or bootloader. The following
 paths are assumed inside:
  * `/bin/true` is used to detect the architecture of an image
- * `/vmlinuz` must be a symbolic link pointing to a regular file containing
-   the kernel.
+ * `/vmlinuz` or `/vmlinux` (depending on the architecture) must be a symbolic
+   link pointing to a regular file containing the kernel.
  * `/initrd.img` must be a symbolic link pointing to a regular file containing
    the initrd image.
 
diff --git a/debvm-create b/debvm-create
index da660cb..3e25578 100755
--- a/debvm-create
+++ b/debvm-create
@@ -4,10 +4,91 @@
 
 # shellcheck disable=SC2016 # Intentional quoting technique
 
+: <<'POD2MAN'
+=head1 NAME
+
+debvm-create - Create a VM image for various Debian releases and architectures
+
+=head1 SYNOPSIS
+
+B<debvm-create> [B<-a> I<architecture>] [B<-h> I<hostname>] [B<-k> I<sshkey>] [B<-m> I<mirror>] [B<-o> I<output>] [B<-p> I<package>] [B<-r> I<release>] [B<-z> I<size_in_GB>] [B<--> I<mmdebstrap options>]
+
+=head1 DESCRIPTION
+
+B<debvm-create> is essentially a thin wrapper around B<mmdebstrap> for creating a raw ext4 filesystem image for booting with B<debvm-run>.
+The purpose of these images primarily is testing the different releases and architectures without access to a physical machine of that architecture.
+Beyond essential packages, the image will contain B<apt>, an init system and a suitable kernel package.
+Notably absent is a bootloader and a partition table.
+In order to boot such an image, one is supposed to extract the kernel and initrd from the image and pass it to a suitable bootloader.
+No user account is created and root can login without specifying a password.
+
+=head1 OPTIONS
+
+=over 8
+
+=item B<-a> I<architecture>, B<--architecture>=I<architecture>
+
+Specify a Debian architecture name.
+By default, the native architecture is being used.
+A suitable kernel image is automatically selected and installed into the image.
+
+=item B<-h> I<hostname>, B<--hostname>=I<hostname>
+
+Set the hostname of the virtual machine.
+By default, the hostname is B<testvm>.
+
+=item B<-k> I<sshkey>, B<--sshkey>=I<sshkey>
+
+Install the given ssh public key file into the virtual machine image for the root user.
+This option also causes the ssh server to be installed.
+By default, no key or server is installed.
+
+=item B<-m> I<mirror>, B<--mirror>=I<mirror>
+
+Specify the Debian mirror to be used for downloading packages and to be configured inside the virtual machine image.
+By default, B<http://deb.debian.org/debian> is being used.
+
+=item B<-o> I<output>, B<--output>=I<output>
+
+Specify the file name of the resulting virtual machine image.
+By default, it is written to B<rootfs.ext4>.
+
+=item B<-p> I<package>, B<--package>=I<package>
+
+Request additional packages to be installed into the virtual machine image.
+This option can be specified multiple times and packages can be separated by a comma.
+Package recommendations are not honoured.
+If a linux-image is passed here, it will replace the one selected by default.
+
+=item B<-r> I<release>, B<--release>=I<release>
+
+Use the given Debian release.
+By default, B<unstable> is being used.
+
+=item B<-z> I<size_in_GB>, B<--size>=I<size_in_GB>
+
+Specify the minimum image size in giga bytes.
+The resulting image will be grown as a sparse file to this size if necessary.
+The default is 1 GB.
+
+=item B<--> I<mmdebstrap options>
+
+All options beyond a double dash are passed to B<mmdebstrap> before the suite, target and mirror specification.
+This can be used to provide additional hooks for image customization.
+
+=back
+
+=head1 SEE ALSO
+
+    debvm-run(1) mmdebstrap(1)
+
+=cut
+POD2MAN
+
 set -u
 
 ARCHITECTURE=$(dpkg --print-architecture)
-IMAGE=rootfs.ext2
+IMAGE=rootfs.ext4
 INCLUDE_PACKAGES=init
 MIRROR="http://deb.debian.org/debian"
 SIZE=$((1024*1024*1024))
diff --git a/debvm-run b/debvm-run
index c800215..d6a5422 100755
--- a/debvm-run
+++ b/debvm-run
@@ -2,9 +2,67 @@
 # Copyright 2022 Helmut Grohne <helmut@subdivi.de>
 # SPDX-License-Identifier: MIT
 
+: <<'POD2MAN'
+=head1 NAME
+
+debvm-run - Run a VM image created by debvm-create
+
+=head1 SYNOPSIS
+
+B<debvm-run> [B<-g>] [B<-i> I<image>] [B<-s> I<sshport>] [B<--> I<qemu options>]
+
+=head1 DESCRIPTION
+
+B<debvm-run> is essentially a thin wrapper around B<qemu> for running a virtual machine image created by B<debvm-create> or something compatible.
+The virtual machine image is expected to be a raw ext4 image with file system label B<debvm>.
+The architecture of the machine is detected from the contained B</bin/true>.
+It must contain a symbolic link pointing to a kernel image at B</vmlinuz> or B</vmlinux> depending on the architecture and a symbolic link pointing to an initrd image at B</initrd.img>.
+Both are extracted and passed to B<qemu>.
+A net interface configured for user mode is added automatically.
+
+=head1 OPTIONS
+
+=over 8
+
+=item B<-g>, B<--graphical>
+
+By default, the option B<-nographic> is passed to B<qemu> and one interacts with the serial console of the machine.
+This configuration is skipped in the presence of this option.
+
+=item B<-i> I<image>, B<--image>=I<image>
+
+This option specifies the location of the virtual machine image file.
+By default B<rootfs.ext4> in the working directory is used.
+
+=item B<-s> I<sshport>, B<--sshport>=I<sshport>
+
+If given, B<qemu> is configured to pass connections to I<127.0.0.1:sshport> to port 22 of the virtual machine.
+
+=item B<--> I<qemu options>
+
+All options beyond a double dash are passed to B<qemu>.
+This can be used to configure additional hardware components.
+One possible use of this method is passing B<-snapshot> to avoid modifying the virtual machine image.
+
+=back
+
+=head1 LIMITATIONS
+
+Due to the way kernel and bootloader are being extracted before running B<qemu>, one cannot upgrade a kernel and then just reboot.
+Attempting to do so, will still use the old kernel.
+Instead, B<qemu> must be terminated and B<debvm-run> should be launched again to pick up the new kernel.
+In order to avoid accidental reboots, one may pass B<-no-reboot> to B<qemu>.
+
+=head1 SEE ALSO
+
+    debvm-create(1) qemu(1)
+
+=cut
+POD2MAN
+
 set -u
 
-IMAGE=rootfs.ext2
+IMAGE=rootfs.ext4
 SSHPORT=
 GRAPHICAL=