From 6cd0bef858db460ecb4a6b153225d15bdc62a5fd Mon Sep 17 00:00:00 2001 From: Helmut Grohne Date: Fri, 23 Dec 2022 12:18:26 +0100 Subject: add documentation in pod2man format Fixes: #2 --- README.md | 4 +-- debvm-create | 79 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ debvm-run | 56 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 137 insertions(+), 2 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 a8f164d..6026a7c 100755 --- a/debvm-create +++ b/debvm-create @@ -4,6 +4,85 @@ # shellcheck disable=SC2016 # Intentional quoting technique +: <<'POD2MAN' +=head1 NAME + +debvm-create - Create a VM image for various Debian releases and architectures + +=head1 SYNOPSIS + +B [B<-a> I] [B<-h> I] [B<-k> I] [B<-m> I] [B<-o> I] [B<-p> I] [B<-r> I] [B<-s> I] [B<--> I] + +=head1 DESCRIPTION + +B is essentially a thin wrapper around B for creating a raw ext4 filesystem image for booting with B. +The purpose of these images primarily is testing the different releases and architectures. +Beyond essential packages, the image will contain B, an init system and a suitable kernel package. +Notably absent is a bootloader and 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 + +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 + +Set the hostname of the virtual machine. +By default, the hostname is B. + +=item B<-k> I + +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 + +Specify the Debian mirror to be used for downloading packages and to be configured inside the virtual machine image. +By default, B is being used. + +=item B<-o> I + +Specify the file name of the resulting virtual machine image. +By default, it is written to B. + +=item B<-p> I + +Request additional packages to be installed into the virtual machine image. +This option can be specified multiple times and packages can be separated with comma. +Package recommendations are not honoured. + +=item B<-r> I + +Use the given Debian release. +By default, B is being used. + +=item B<-s> I + +Specify the image size in giga bytes. +The default image size is 1 GB. + +=item B<--> I + +All options beyond a double dash are passed to B 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) diff --git a/debvm-run b/debvm-run index edb01ad..1081597 100755 --- a/debvm-run +++ b/debvm-run @@ -2,6 +2,62 @@ # Copyright 2022 Helmut Grohne # SPDX-License-Identifier: MIT +: <<'POD2MAN' +=head1 NAME + +debvm-run - Run a VM image created by debvm-create + +=head1 SYNOPSIS + +B [B<-g>] [B<-i> I] [B<-s> I] [B<--> I] + +=head1 DESCRIPTION + +B is essentially a thing wrapper around B for running a virtual machine image created by B or something compatible. +The virtual machine image is expected to be a raw ext4 image with file system label B. +The architecture of the machine is detected from the contained B. +It must contain a symbolic link pointing to a kernel image at B or B depending on the architecture and a symbolic link pointing to an initrd image at B. +Both are extracted and passed to B. +A net interface configured for user mode is added automatically. + +=head1 OPTIONS + +=over 8 + +=item B<-g> + +By default, the option B<-nographic> is passed to B and one interacts with the serial console of the machine. +This configuration is skipped in the presence of this option. + +=item B<-i> I + +This option specifies the location of the virtual machine image file. +By default B in the working directory is used. + +=item B<-s> I + +If given, B is configured to pass connections to I<127.0.0.1:sshport> to port 22 of the virtual machine. + +=item B<--> I + +All options beyond a double dash are passed to B. +This can be used to configure additional hardware components. +Another 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 qemu, one cannot upgrade a kernel and then just reboot. +Instead, B must be terminated and B should be launched again to pick up a new kernel. + +=head1 SEE ALSO + + debvm-create(1) qemu(1) + +=cut +POD2MAN + set -u IMAGE=rootfs.ext2 -- cgit v1.2.3 From 9aa4cb7de93569c35994faea051b9e390da25008 Mon Sep 17 00:00:00 2001 From: Helmut Grohne Date: Fri, 23 Dec 2022 22:51:50 +0100 Subject: standardize on image name rootfs.ext4 Reported-by: Johannes Schauer Marin Rodrigues --- debvm-create | 4 ++-- debvm-run | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/debvm-create b/debvm-create index 6026a7c..5fc8950 100755 --- a/debvm-create +++ b/debvm-create @@ -86,7 +86,7 @@ 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)) @@ -304,4 +304,4 @@ truncate -s "$SIZE" "$IMAGE" /sbin/resize2fs "$IMAGE" /sbin/tune2fs -L debvm -i 0 -O extents,uninit_bg,dir_index,has_journal "$IMAGE" # Must fsck after tune2fs: https://ext4.wiki.kernel.org/index.php/UpgradeToExt4 -/sbin/fsck.ext4 -fDp rootfs.ext2 +/sbin/fsck.ext4 -fDp "$IMAGE" diff --git a/debvm-run b/debvm-run index 1081597..729ba6d 100755 --- a/debvm-run +++ b/debvm-run @@ -32,7 +32,7 @@ This configuration is skipped in the presence of this option. =item B<-i> I This option specifies the location of the virtual machine image file. -By default B in the working directory is used. +By default B in the working directory is used. =item B<-s> I @@ -60,7 +60,7 @@ POD2MAN set -u -IMAGE=rootfs.ext2 +IMAGE=rootfs.ext4 SSHPORT= GRAPHICAL= -- cgit v1.2.3 From 86ad5dc1f589d78053eeaa7054dd5a4e5d606422 Mon Sep 17 00:00:00 2001 From: Helmut Grohne Date: Fri, 23 Dec 2022 22:55:37 +0100 Subject: improve documentation wording and content Reported-by: Johannes Schauer Marin Rodrigues --- debvm-create | 6 +++--- debvm-run | 8 +++++--- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/debvm-create b/debvm-create index 5fc8950..65b3c54 100755 --- a/debvm-create +++ b/debvm-create @@ -16,9 +16,9 @@ B [B<-a> I] [B<-h> I] [B<-k> I] [B =head1 DESCRIPTION B is essentially a thin wrapper around B for creating a raw ext4 filesystem image for booting with B. -The purpose of these images primarily is testing the different releases and architectures. +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, an init system and a suitable kernel package. -Notably absent is a bootloader and partition table. +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. @@ -56,7 +56,7 @@ By default, it is written to B. =item B<-p> I Request additional packages to be installed into the virtual machine image. -This option can be specified multiple times and packages can be separated with comma. +This option can be specified multiple times and packages can be separated by a comma. Package recommendations are not honoured. =item B<-r> I diff --git a/debvm-run b/debvm-run index 729ba6d..cb782db 100755 --- a/debvm-run +++ b/debvm-run @@ -13,7 +13,7 @@ B [B<-g>] [B<-i> I] [B<-s> I] [B<--> I] =head1 DESCRIPTION -B is essentially a thing wrapper around B for running a virtual machine image created by B or something compatible. +B is essentially a thin wrapper around B for running a virtual machine image created by B or something compatible. The virtual machine image is expected to be a raw ext4 image with file system label B. The architecture of the machine is detected from the contained B. It must contain a symbolic link pointing to a kernel image at B or B depending on the architecture and a symbolic link pointing to an initrd image at B. @@ -42,14 +42,16 @@ If given, B is configured to pass connections to I<127.0.0.1:sshport> to p All options beyond a double dash are passed to B. This can be used to configure additional hardware components. -Another use of this method is passing B<-snapshot> to avoid modifying the virtual machine image. +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 qemu, one cannot upgrade a kernel and then just reboot. +Due to the way kernel and bootloader are being extracted before running B, one cannot upgrade a kernel and then just reboot. +Attempting to do so, will still use the old kernel. Instead, B must be terminated and B should be launched again to pick up a new kernel. +In order to avoid accidental reboots, one may pass B<-no-reboot> to B. =head1 SEE ALSO -- cgit v1.2.3 From 0c50e3b74ec8173d6b0b5f26250a8feee0ceda7b Mon Sep 17 00:00:00 2001 From: Helmut Grohne Date: Fri, 23 Dec 2022 22:58:11 +0100 Subject: another documentation improvement I missed earlier Reported-by: Johannes Schauer Marin Rodrigues --- debvm-run | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/debvm-run b/debvm-run index cb782db..c227aa3 100755 --- a/debvm-run +++ b/debvm-run @@ -50,7 +50,7 @@ One possible use of this method is passing B<-snapshot> to avoid modifying the v Due to the way kernel and bootloader are being extracted before running B, one cannot upgrade a kernel and then just reboot. Attempting to do so, will still use the old kernel. -Instead, B must be terminated and B should be launched again to pick up a new kernel. +Instead, B must be terminated and B should be launched again to pick up the new kernel. In order to avoid accidental reboots, one may pass B<-no-reboot> to B. =head1 SEE ALSO -- cgit v1.2.3 From 293a1fa978c0dff81bdf6f37f89eef22066783c6 Mon Sep 17 00:00:00 2001 From: Helmut Grohne Date: Wed, 28 Dec 2022 10:19:07 +0100 Subject: update pod2man documentation * Rename debvm-create -s to -z. * Add long options. * Improve documentation of debvm-create -p and -z. --- debvm-create | 24 +++++++++++++----------- debvm-run | 6 +++--- 2 files changed, 16 insertions(+), 14 deletions(-) diff --git a/debvm-create b/debvm-create index 37fa514..b39330b 100755 --- a/debvm-create +++ b/debvm-create @@ -11,7 +11,7 @@ debvm-create - Create a VM image for various Debian releases and architectures =head1 SYNOPSIS -B [B<-a> I] [B<-h> I] [B<-k> I] [B<-m> I] [B<-o> I] [B<-p> I] [B<-r> I] [B<-s> I] [B<--> I] +B [B<-a> I] [B<-h> I] [B<-k> I] [B<-m> I] [B<-o> I] [B<-p> I] [B<-r> I] [B<-z> I] [B<--> I] =head1 DESCRIPTION @@ -26,48 +26,50 @@ No user account is created and root can login without specifying a password. =over 8 -=item B<-a> I +=item B<-a> I, B<--architecture>=I 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 +=item B<-h> I, B<--hostname>=I Set the hostname of the virtual machine. By default, the hostname is B. -=item B<-k> I +=item B<-k> I, B<--sshkey>=I 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 +=item B<-m> I, B<--mirror>=I Specify the Debian mirror to be used for downloading packages and to be configured inside the virtual machine image. By default, B is being used. -=item B<-o> I +=item B<-o> I, B<--output>=I Specify the file name of the resulting virtual machine image. By default, it is written to B. -=item B<-p> I +=item B<-p> I, B<--package>=I 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 +=item B<-r> I, B<--release>=I Use the given Debian release. By default, B is being used. -=item B<-s> I +=item B<-z> I, B<--size>=I -Specify the image size in giga bytes. -The default image size is 1 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 diff --git a/debvm-run b/debvm-run index 58bf2f7..d6a5422 100755 --- a/debvm-run +++ b/debvm-run @@ -24,17 +24,17 @@ A net interface configured for user mode is added automatically. =over 8 -=item B<-g> +=item B<-g>, B<--graphical> By default, the option B<-nographic> is passed to B and one interacts with the serial console of the machine. This configuration is skipped in the presence of this option. -=item B<-i> I +=item B<-i> I, B<--image>=I This option specifies the location of the virtual machine image file. By default B in the working directory is used. -=item B<-s> I +=item B<-s> I, B<--sshport>=I If given, B is configured to pass connections to I<127.0.0.1:sshport> to port 22 of the virtual machine. -- cgit v1.2.3