[1/2] Add a rudimentary manpage

Commit Message

Andre Przywara Dec. 22, 2015, 2 p.m. UTC

The kvmtool documentation is somewhat lacking, also it is not easily
accessible when living in the source tree only.
Add a good ol' manpage to document at least the basic commands and
their options.
This level of documentation matches the one that is already there in
the Documentation directory and should be subject to extension.

Signed-off-by: Andre Przywara <[e-mail]>
---
 Documentation/kvmtool.1 | 222 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 222 insertions(+)
 create mode 100644 Documentation/kvmtool.1

Comments

Will Deacon Dec. 22, 2015, 3:11 p.m. UTC | #1

Hi Andre, of Phoronix fame,

On Tue, Dec 22, 2015 at 02:00:46PM +0000, Andre Przywara wrote:
> The kvmtool documentation is somewhat lacking, also it is not easily
> accessible when living in the source tree only.
> Add a good ol' manpage to document at least the basic commands and
> their options.
> This level of documentation matches the one that is already there in
> the Documentation directory and should be subject to extension.
> 
> Signed-off-by: Andre Przywara <[e-mail]>
> ---
>  Documentation/kvmtool.1 | 222 ++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 222 insertions(+)
>  create mode 100644 Documentation/kvmtool.1
> 
> diff --git a/Documentation/kvmtool.1 b/Documentation/kvmtool.1
> new file mode 100644
> index 0000000..aecb2dc
> --- /dev/null
> +++ b/Documentation/kvmtool.1
> @@ -0,0 +1,222 @@
> +.\" Manpage for kvmtool
> +.\" Copyright (C) 2015 by Andre Przywara <[e-mail]>
> +.TH kvmtool 1 "11 Nov 2015" "0.1" "kvmtool man page"
> +.SH NAME
> +kvmtool \- running KVM guests
> +.SH SYNOPSIS
> +lkvm COMMAND [ARGS]
> +.SH DESCRIPTION
> +kvmtool is a userland tool for creating and controlling KVM guests.
> +.SH "KVMTOOL COMMANDS"
> +.sp
> +.PP
> +.B run -k <kernel-image> ...

You seem to be inconsistent with your synopses for each command. That is,
here you just have -k <kernel-image> ... , but later you have things like

> +.B debug --all|--name <guest name> [--dump] [--nmi <n>] [--sysrq <rq>]

which describes all of the possible options to debug. I think I prefer
this latter way, so could you make all of the commands look like that,
please?

Will
--
To unsubscribe from this list: send the line "unsubscribe kvm" in
the body of a message to [e-mail]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Patch

diff --git a/Documentation/kvmtool.1 b/Documentation/kvmtool.1
new file mode 100644
index 0000000..aecb2dc
--- /dev/null
+++ b/Documentation/kvmtool.1
@@ -0,0 +1,222 @@ 
+.\" Manpage for kvmtool
+.\" Copyright (C) 2015 by Andre Przywara <[e-mail]>
+.TH kvmtool 1 "11 Nov 2015" "0.1" "kvmtool man page"
+.SH NAME
+kvmtool \- running KVM guests
+.SH SYNOPSIS
+lkvm COMMAND [ARGS]
+.SH DESCRIPTION
+kvmtool is a userland tool for creating and controlling KVM guests.
+.SH "KVMTOOL COMMANDS"
+.sp
+.PP
+.B run -k <kernel-image> ...
+.RS 4
+Run a guest.
+.sp
+.B \-k, \-\-kernel <image file>
+.RS 4
+The virtual machine kernel.
+.RE
+.sp
+.B \-c, \-\-cpus <n>
+.RS 4
+The number of virtual CPUs to run.
+.RE
+.sp
+.B \-m, \-\-mem <n>
+.RS 4
+Virtual machine memory size in MiB.
+.RE
+.sp
+.B \-p, \-\-params <parameters>
+.RS 4
+Additional kernel command line arguments.
+.RE
+.sp
+.B \-i, \-\-initrd <image file>
+.RS 4
+Initial RAM disk image.
+.RE
+.sp
+.B \-d, \-\-disk <image file|directory>
+.RS 4
+A disk image file or a rootfs directory.
+.RE
+.sp
+.B \-\-console serial|virtio|hv
+.RS 4
+Console to use.
+.RE
+.sp
+.B \-\-dev <device node>
+.RS 4
+KVM device file (instead of the default /dev/kvm).
+.RE
+.sp
+.B \-\-debug
+.RS 4
+Enable debug messages.
+.RE
+.sp
+.B \-\-debug-single-step
+.RS 4
+Enable single stepping.
+.RE
+.sp
+.B \-\-debug-ioport
+.RS 4
+Enable ioport debugging.
+.RE
+.RE
+.PP
+.B setup <name>
+.RS 4
+Setup a new virtual machine. This creates a new rootfs in the .lkvm
+folder of your home directory.
+.RE
+.PP
+.B pause \-\-all|\-\-name <name>
+.RS 4
+Pause a virtual machine.
+.sp
+.B \-a, \-\-all
+.RS 4
+Pause all running instances.
+.RE
+.sp
+.B \-n, \-\-name <name>
+.RS 4
+Pause that specified instance. For a list of running instances, see \fI lkvm list\fR.
+.RE
+.RE
+.PP
+.B resume --all|--name <name>
+.RS 4
+Resume a previously paused virtual machine.
+.sp
+.B \-a, \-\-all
+.RS 4
+Resume all running instances.
+.RE
+.sp
+.B \-n, \-\-name <name>
+.RS 4
+Resume that specified instance. For a list of running instances, see \fI lkvm list\fR.
+.RE
+.RE
+.PP
+.B list [\-i] [\-r]
+.RS 4
+Print a list of running instances on the host. This is restricted to instances
+started by the current user, as it looks in the .lkvm folder in your home
+directory to find the socket files.
+.sp
+.B \-i, \-\-run
+.RS 4
+List all running instances.
+.RE
+.sp
+.B \-r, \-\-rootfs
+.RS 4
+List rootfs instances.
+.RE
+.RE
+.PP
+.B debug --all|--name <guest name> [--dump] [--nmi <n>] [--sysrq <rq>]
+.RS 4
+Print debug information from a running VM instance.
+.sp
+.B \-a, \-\-all
+.RS 4
+Debug all running instances.
+.RE
+.PP
+.B \-n, \-\-name <guest name>
+.RS 4
+Debug the specified instance.
+.RE
+.sp
+.B \-d, \-\-dump
+.RS 4
+Generate a debug dump from guest.
+.RE
+.PP
+.B \-m, \-\-nmi <VCPU nr>
+.RS 4
+Generate an NMI on the specified virtual CPU.
+.RE
+.PP
+.B \-s, \-\-sysrq <sysrq>
+.RS 4
+Inject a Linux sysrq into the guest.
+.RE
+.RE
+.PP
+.B balloon \-\-name <guest name> \-\-inflate|\-\-deflate <amount in MB>
+.RS 4
+This command inflates or deflates the virtio balloon located in the
+specified instance.
+\-\-inflate increases the size of the balloon, thus \fIdecreasing\fR the
+amount of virtual RAM available for the guest. \-\-deflate returns previously
+inflated memory back to the guest.
+.sp
+.B \-n, \-\-name <guest name>
+.RS 4
+Ballon the specified instance. For a list of all instances, see \fI"lkvm list"\fR.
+.RE
+.PP
+.B \-i, \-\-inflate <n>
+.RS 4
+Inflates the ballon by the specified number of Megabytes. This decreases the
+amount of usable memory in the guest.
+.RE
+.PP
+.B \-d, \-\-deflate <n>
+.RS 4
+Deflates the ballon by the specified number of Megabytes. This increases the
+amount of usable memory in the guest.
+.RE
+.RE
+.PP
+.B stop --all|--name <name>
+.RS 4
+Stop a running instance.
+.sp
+.B \-a, \-\-all
+.RS 4
+Stop all running instances.
+.RE
+.sp
+.B \-n, \-\-name <name>
+.RS 4
+Stop the specified instance. For a list of running instances, see \fI lkvm list\fR.
+.RE
+.RE
+.PP
+.B stat \-\-all|\-\-name <name> [\-m]
+.RS 4
+Print statistics about a running instance.
+.sp
+.B \-m, \-\-memory
+.RS 4
+Display memory statistics.
+.RE
+.RE
+.PP
+.B sandbox (\fIlkvm run arguments\fR) \-\- [sandboxed command]
+.RS 4
+Run a command in a sandboxed guest. Kvmtool will inject a special init
+binary which will do an initial setup of the guest Linux and then
+lauch a shell script with the specified command. Upon this command ending,
+the guest will be shutdown.
+.RE
+.SH EXAMPLES
+.RS 4
+\fB$\fR lkvm run -k bzImage
+.RE
+.SH SEE ALSO
+qemu(1), kvm(4)
+.SH BUGS
+.SH AUTHOR
+Andre Przywara <[e-mail]>