diff options
| -rw-r--r-- | README.md | 4 | ||||
| -rwxr-xr-x | debvm-create | 81 | ||||
| -rwxr-xr-x | debvm-run | 60 |
3 files changed, 141 insertions, 4 deletions
@@ -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 cddab8f..37fa514 100755 --- a/debvm-create +++ b/debvm-create @@ -4,10 +4,89 @@ # 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<-s> 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> + +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> + +Set the hostname of the virtual machine. +By default, the hostname is B<testvm>. + +=item B<-k> 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> + +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> + +Specify the file name of the resulting virtual machine image. +By default, it is written to B<rootfs.ext4>. + +=item B<-p> 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. + +=item B<-r> I<release> + +Use the given Debian release. +By default, B<unstable> is being used. + +=item B<-s> I<size_in_GB> + +Specify the image size in giga bytes. +The default image size 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)) @@ -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> + +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> + +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> + +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= |