From 6cd0bef858db460ecb4a6b153225d15bdc62a5fd Mon Sep 17 00:00:00 2001
From: Helmut Grohne <helmut@subdivi.de>
Date: Fri, 23 Dec 2022 12:18:26 +0100
Subject: add documentation in pod2man format

Fixes: #2
---
 debvm-run | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)

(limited to 'debvm-run')

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 <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 thing 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.ext2> 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.
+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<qemu> must be terminated and B<debvm-run> 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