parabola-vmbootstrap
====================

This is a collection of scripts for creating and booting parabola virtual
machine images for use with qemu.


------------------------------
virtual machine image creation
------------------------------

To create a new virtual machine image, run

  $> pvmbootstrap [options] <path-to-image> <arch>

... where <arch> is one of the parabola arches, which are currently:

  supported:    [ armv7h, i686, x86_64 ]
  experimental: [ ppc64le, riscv64 ]

The script will attempt to bootstrap a virtual machine of the selected
archituecture to the output file specified. If the output file already exists,
the script will emit a warning and ask for confirmation to proceed.

The creation can be influenced by providing one or more of the following
options to pvmbootstrap:

  -b <base-set>  -- Select one of the pre-defined package-sets described below
                    (default: standard)
  -c <package>   -- Specify a package to store in the image pacman cache.
                    This option does not implcitly install the package.
                    This option can be specified multiple times;
                    but note that these will be ignored if -s <root_size> is 0.
  -H <hook>      -- Enable a hook to customize the created image. This can be
                    the path to a custom script, or one of the predefined hooks
                    described below. The VM will boot the newly created image,
                    and the hook script(s) will be executed once each within
                    the running VM. This option can be specified multiple times.
  -k <kernel>    -- Specify an additional kernel package (default: linux-libre).
                    This option can be specified multiple times; but note that
                    'linux-libre' will be installed, regardless of this option.
  -M <mirror>    -- Set the mirror from which to fetch packages
                    (default: https://repo.parabola.nu/$repo/os/$arch)
  -O             -- Bootstrap an openrc system instead of a systemd one
  -p <package>   -- Specify an additional package to be installed in the image.
                    This option can be specified multiple times;
                    but note that these will be ignored if -s <root_size> is 0.
  -s <root_size> -- Set the size (in MB) of the root partition (default: 32000).
                    If this is 0 (or less than the <base-set> requires),
                    the VM image will be the smallest size possible,
                    fit to the <base-set>; and any -p <package> will be ignored.
  -S <swap_size> -- Set the size (in MB) of the swap partition (default: 0).
                    If this is 0, no swap partition will be created.

Pre-defined package-sets:
  minimal:          base
  standard:         base parabola-base
  devel:            base parabola-base base-devel

Pre-defined hooks:
  ethernet-dhcp:    This hook will setup ethernet in the VM by enabling
                    systemd-resolved and openresolv properly, as well as creating
                    and enabling a systemd-networkd configuration. (systemd only)


--------------------
virtual machine boot
--------------------

To boot a created virtual machine, run:

  $> pvmboot [options] <path_to_image> [qemu-args ...]

The script will attempt to determine the architecture and partition layout
of the provided virtual machine image, and set the qemu executable and sane
default flags for the qemu invocation automatically; and will enable KVM
acceleration, if available for the target architecture.

The pvmbootstrap script creates a boot partition formatted with either the
vfat or ext2 filesystems, and a root partition formatted with the ext4
filesystems. If the specified image was not created using pvmbootstrap, the
partition detection will fail unless the image coforms to this expected schema.
The first vfat or ext2 filesystem detected, will be considered as the boot
partition; and the first ext4 filesystem detected, will be considered as the
root partition.

The default kernel installed by pvmbootstrap is 'linux-libre'.
The -k option ca be used to specify an alternate kernel to boot.

  $> pvmboot -k linux-libre-lts ./an.img

Additionally, the script will evaluate the DISPLAY environment variable to
determine whether a graphical desktop environment is available, and will start
the image in serial console mode if necessary. This behavior can be forced by
unsetting DISPLAY before executing the script:

  $> DISPLAY= pvmboot ./an.img

If qemu boots into graphical mode, the serial console can be redirected
to the host console by passing the -r option.

  $> pvmboot -r ./an.img

The qemu launch configuration can be customized, for example to allocate more
memory to the machine, by specifying additional qemu options on the command
line following the virtual machine image name:

  $> DISPLAY= pvmboot ./an.img -m 2G


------------------------
release tarball creation
------------------------

To convert a virtual machine image into a parabola release tarball, run:

  $> pvm2tarball <path_to_image>

This will attempt to mount the rootfs and the /boot partition, and tar the
contents to an output file, filtering out all unneeded files. The /boot
partition is optional if the kernel and initramfs are in /boot; though
pvmbootstrap always creates a /boot partition.

for example, to generate the parabola armv7h release tarball:

  $> img_filename=parabola-systemd-cli-armv7h-tarball-$(date +%Y.%m).img
  $> pvmbootstrap -b minimal -H ethernet-dhcp -s 0 -S0 $img_file armv7h
  $> pvm2tarball $img_file