Re: [libvirt] [PATCH sandbox-image] Add manual pages to describe virt-sandbox-image

There's little point releasing a new tool if we don't provide any docs describing how it is used. Signed-off-by: Daniel P. Berrangé <berrange(a)redhat.com&gt; --- .gitignore | 1 + MANIFEST.in | 2 + libvirt-sandbox-image.spec.in | 1 + man/virt-sandbox-image-list.pod | 92 +++++++++++++++++++++ man/virt-sandbox-image-prepare.pod | 100 ++++++++++++++++++++++ man/virt-sandbox-image-purge.pod | 96 +++++++++++++++++++++ man/virt-sandbox-image-run.pod | 165 +++++++++++++++++++++++++++++++++++++ man/virt-sandbox-image.pod | 136 ++++++++++++++++++++++++++++++ setup.py | 33 +++++++- 9 files changed, 625 insertions(+), 1 deletion(-) create mode 100644 man/virt-sandbox-image-list.pod create mode 100644 man/virt-sandbox-image-prepare.pod create mode 100644 man/virt-sandbox-image-purge.pod create mode 100644 man/virt-sandbox-image-run.pod create mode 100644 man/virt-sandbox-image.pod diff --git a/.gitignore b/.gitignore index 052e94b..5c7f451 100644 --- a/.gitignore +++ b/.gitignore @@ -7,3 +7,4 @@ build/ AUTHORS ChangeLog *egg-info/ +man/*.1 diff --git a/MANIFEST.in b/MANIFEST.in index 5f690a3..794a949 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -11,4 +11,6 @@ include libvirt_sandbox_image/source/*.py include autobuild.sh include libvirt-sandbox-image.spec include libvirt-sandbox-image.spec.in +include man/*1 +include man/*pod global-exclude *.pyc diff --git a/libvirt-sandbox-image.spec.in b/libvirt-sandbox-image.spec.in index c122af0..69c18e3 100644 --- a/libvirt-sandbox-image.spec.in +++ b/libvirt-sandbox-image.spec.in @@ -28,6 +28,7 @@ Currently docker and virt-builder images are supported. %files %doc README LICENSE %{_bindir}/virt-sandbox-image +%{_mandir}/man1/virt-sandbox-image*1* %{python3_sitelib}/libvirt_sandbox_image/ %{python3_sitelib}/libvirt_sandbox_image-%{version}-py3.*.egg-info diff --git a/man/virt-sandbox-image-list.pod b/man/virt-sandbox-image-list.pod new file mode 100644 index 0000000..69c8bd5 --- /dev/null +++ b/man/virt-sandbox-image-list.pod @@ -0,0 +1,92 @@ +=encoding utf8 + +=head1 NAME + +virt-sandbox-image list - List cached image templates + +=head1 SYNOPSIS + + virt-sandbox-image list [-h] [-c CONNECT] [-t TEMPLATE_DIR] template + +=head1 DESCRIPTION + +B<virt-sandbox-image> is used to launch sandboxes from a pre-built container +image template. It is able to download image templates in a number of +formats from online image registries, including those built for Docker +and virt-builder. The images can be run with either QEMU (KVM) or LXC +virtualization drivers. + +The B<list> command can be used to display the templates which are present +in the local cache. Existance of a cached template will allow the B<run> +command to launch sandboxes immediately. Unwanted templates in the cache +can be deleted using the B<purge> command. + +=head1 OPTIONS + +=over 4 + +=item B<-h>, B<--help> + +Display help message + +=item B<-c URI>, B<--connect URI> + +The connection URI for the hypervisor. The following URIs are currently +supported + + - lxc:/// (if running as root) + - qemu:///system (if running as root) + - qemu:///session (if running as non-root) + +It is not permitted to use non-local URIs (ie URIs with a hostname) +at this time. + +=item B<-t TEMPLATE_DIR> + +Override the default template directory which is usually +C</var/lib/libvirt/templates> (root) or C<$HOME/.local/share/libvirt/templates>. + +=item B<template> + +The URI identifying the template to download and prepare. + +=back + +=head1 EXAMPLE + +Display a list of template images in the cache + + # virt-sandbox-image list -c qemu:///session + + +=head1 SEE ALSO + +C<virt-sandbox(1)>, +C<virt-sandbox-image(1)>, C<virt-sandbox-image-prepare(1)>, +C<virt-sandbox-image-run(1)>, C<virt-sandbox-image-purge(1)> + +=head1 FILES + +Pristine downloaded templates will be stored in subdirectories of +C</var/lib/libvirt/templates> (root) or C<$HOME/.local/share/libvirt/templates> +(non-root) by default. + +Overlay images created when running an instance of the template will +be stored in C</var/lib/libvirt/images> (root) or C<$HOME/.local/share/libvirt/images> +(non-root) by default. + +=head1 AUTHORS + +Daniel P. Berrangé <dan(a)berrange.com&gt;, Eren Yagdiran <erenyagdiran(a)gmail.com&gt; +and Cédric Bosdonnat <cbosdonnat(a)suse.com&gt; + +=head1 COPYRIGHT + +Copyright (C) 2011-2018 Red Hat, Inc. + +=head1 LICENSE + +virt-sandbox is distributed under the terms of the GNU LGPL v2+. +This is free software; see the source for copying conditions. +There is NO warranty; not even for MERCHANTABILITY or FITNESS +FOR A PARTICULAR PURPOSE diff --git a/man/virt-sandbox-image-prepare.pod b/man/virt-sandbox-image-prepare.pod new file mode 100644 index 0000000..8025c40 --- /dev/null +++ b/man/virt-sandbox-image-prepare.pod @@ -0,0 +1,100 @@ +=encoding utf8 + +=head1 NAME + +virt-sandbox-image prepare - Download and cache an image template + +=head1 SYNOPSIS + + virt-sandbox-image prepare [-h] [-c CONNECT] [-t TEMPLATE_DIR] template + +=head1 DESCRIPTION + +B<virt-sandbox-image> is used to manage and execute application container +images in secure sandboxes. These applications will be launched via l +ibvirt and run within a virtualization technology such as LinuX Containers +(LXC), or QEMU/KVM. The containers / virtual machines will be secured by +SELinux and resource separated using cgroups. + +The B<prepare> command is used to proactively download and cache an image +template. This ensures that when the B<run> command is used later, it will +be able to launch the sandbox immediately. Use of this command is optional, + since the B<run> command will automatically download image templates if +not already present in the cache. + +The cache will contain both the downloaded image in its original native +format, and the same content extracted into qcow2 images formatted with +an ext4 filesystem. + +=head1 OPTIONS + +=over 4 + +=item B<-h>, B<--help> + +Display help message + +=item B<-c URI>, B<--connect URI> + +The connection URI for the hypervisor. The following URIs are currently +supported + + - lxc:/// (if running as root) + - qemu:///system (if running as root) + - qemu:///session (if running as non-root) + +It is not permitted to use non-local URIs (ie URIs with a hostname) +at this time. + +=item B<-t TEMPLATE_DIR> + +Override the default template directory which is usually +C</var/lib/libvirt/templates> (root) or C<$HOME/.local/share/libvirt/templates>. + +=item B<template> + +The URI identifying the template to download and prepare. + +=back + +=head1 EXAMPLE + +Download and prepare a Docker Ubuntu 15.04 template for use with KVM + + # virt-sandbox-image prepare -c qemu:///session docker:///ubuntu?tag=15.04 + +Download and prepare a virt-builder Fedora 24 template for use with LXC + + # virt-sandbox-image prepare -c lxc:/// virt-builder:///fedora-24 + +=head1 SEE ALSO + +C<virt-sandbox(1)>, +C<virt-sandbox-image(1)>, C<virt-sandbox-image-run(1)>, +C<virt-sandbox-image-purge(1)>, C<virt-sandbox-image-list(1)> + +=head1 FILES + +Pristine downloaded templates will be stored in subdirectories of +C</var/lib/libvirt/templates> (root) or C<$HOME/.local/share/libvirt/templates> +(non-root) by default. + +Overlay images created when running an instance of the template will +be stored in C</var/lib/libvirt/images> (root) or C<$HOME/.local/share/libvirt/images> +(non-root) by default. + +=head1 AUTHORS + +Daniel P. Berrangé <dan(a)berrange.com&gt;, Eren Yagdiran <erenyagdiran(a)gmail.com&gt; +and Cédric Bosdonnat <cbosdonnat(a)suse.com&gt; + +=head1 COPYRIGHT + +Copyright (C) 2011-2018 Red Hat, Inc. + +=head1 LICENSE + +virt-sandbox is distributed under the terms of the GNU LGPL v2+. +This is free software; see the source for copying conditions. +There is NO warranty; not even for MERCHANTABILITY or FITNESS +FOR A PARTICULAR PURPOSE diff --git a/man/virt-sandbox-image-purge.pod b/man/virt-sandbox-image-purge.pod new file mode 100644 index 0000000..57f0a91 --- /dev/null +++ b/man/virt-sandbox-image-purge.pod @@ -0,0 +1,96 @@ +=encoding utf8 + +=head1 NAME + +virt-sandbox-image purge - Delete a cached image template + +=head1 SYNOPSIS + + virt-sandbox-image create [-h] [-c CONNECT] [-t TEMPLATE_DIR] template + +=head1 DESCRIPTION + +B<virt-sandbox-image> is used to launch sandboxes from a pre-built container +image template. It is able to download image templates in a number of +formats from online image registries, including those built for Docker +and virt-builder. The images can be run with either QEMU (KVM) or LXC +virtualization drivers. + +The B<purge> command can be used to delete previously cached image templates. +Templates are added to the cache by the B<prepare> and B<run> commands, and +so if a template is no longer required, the space it used should be freed. +Some image distribution formats allow sharing of content between templates. +If there are multiple locally cached images sharing content, the shared +pieces will only be deleted when the last image template is removed. + +It is the callers responsibility to ensure that the templates being deleted +are no longer required by any currently running sandboxes. + +=head1 OPTIONS + +=over 4 + +=item B<-h>, B<--help> + +Display help message + +=item B<-c URI>, B<--connect URI> + +The connection URI for the hypervisor. The following URIs are currently +supported + + - lxc:/// (if running as root) + - qemu:///system (if running as root) + - qemu:///session (if running as non-root) + +It is not permitted to use non-local URIs (ie URIs with a hostname) +at this time. + +=item B<-t TEMPLATE_DIR> + +Override the default template directory which is usually +C</var/lib/libvirt/templates> (root) or C<$HOME/.local/share/libvirt/templates>. + +=item B<template> + +The URI identifying the template to download and prepare. + +=back + +=head1 EXAMPLE + +To delete a Docker Ubuntu 15.04 template from the cache + + # virt-sandbox-image purge -c qemu:///session docker:///ubuntu?tag=15.04 + +=head1 SEE ALSO + +C<virt-sandbox(1)>, +C<virt-sandbox-image(1)>, C<virt-sandbox-image-prepare(1)>, +C<virt-sandbox-image-run(1)>, C<virt-sandbox-image-list(1)> + +=head1 FILES + +Pristine downloaded templates will be stored in subdirectories of +C</var/lib/libvirt/templates> (root) or C<$HOME/.local/share/libvirt/templates> +(non-root) by default. + +Overlay images created when running an instance of the template will +be stored in C</var/lib/libvirt/images> (root) or C<$HOME/.local/share/libvirt/images> +(non-root) by default. + +=head1 AUTHORS + +Daniel P. Berrangé <dan(a)berrange.com&gt;, Eren Yagdiran <erenyagdiran(a)gmail.com&gt; +and Cédric Bosdonnat <cbosdonnat(a)suse.com&gt; + +=head1 COPYRIGHT + +Copyright (C) 2011-2018 Red Hat, Inc. + +=head1 LICENSE + +virt-sandbox is distributed under the terms of the GNU LGPL v2+. +This is free software; see the source for copying conditions. +There is NO warranty; not even for MERCHANTABILITY or FITNESS +FOR A PARTICULAR PURPOSE diff --git a/man/virt-sandbox-image-run.pod b/man/virt-sandbox-image-run.pod new file mode 100644 index 0000000..d14e108 --- /dev/null +++ b/man/virt-sandbox-image-run.pod @@ -0,0 +1,165 @@ +=encoding utf8 + +=head1 NAME + +virt-sandbox-image run - Launch a sandbox from an image template + +=head1 SYNOPSIS + + virt-sandbox-image run [-h] [-n NAME] [-c CONNECT] [-t TEMPLATE_DIR] + [-I IMAGE_DIR] [-N NETWORK] [-e ENV] + TEMPLATE [--] [COMMAND [ARGS...]] + +=head1 DESCRIPTION + +B<virt-sandbox-image> is used to manage and execute application container +images in secure sandboxes. These applications will be launched via l +ibvirt and run within a virtualization technology such as LinuX Containers +(LXC), or QEMU/KVM. The containers / virtual machines will be secured by +SELinux and resource separated using cgroups. + +The B<run> command will launch a sandbox populated with content from the +image name B<TEMPLATE>. + +If B<COMMAND> is provided it determines the binary to run inside the sandbox. +If omitted, then the default binary for that image is run. Not all images +provide a default binary to run, and thus will launch to launch if no B<COMMAND> +is given. It is recommended to insert B<--> before B<COMMAND> to ensure that +any arguments for B<COMMAND> are not mistakenly interpreted as arguments for +B<virt-sandbox-image> + +If the requested B<TEMPLATE> is not already present on the local system, it +will be automatically downloaded and cached, which may delay startup of the +sandbox. To avoid these delays the cache can be populated using the B<prepare> +command ahead of time, while unwanted cached content can be deleted using the +B<purge> command. + +=head1 OPTIONS + +=over 4 + +=item B<-h>, B<--help> + +Display help message + +=item B<-c URI>, B<--run URI> + +The connection URI for the hypervisor (lxc:///, qemu:///system or +qemu:///session only). + +=item B<-n NAME>, B<--name=NAME> + +Set the unique name for the sandbox. This defaults to the base +name of the template image used, with a random identifier appended. +This is used as the name of the libvirt virtual machine or container. + +=item B<-t TEMPLATE_DIR>, B<--template-dir TEMPLATE_DIR> + +Override the default location of the directory holding the image +templates. + +=item B<-I IMAGE_DIR>, B<--image-dir IMAGE_DIR> + +Override the default location of the directory holding the instantiated +images. + +=item B<-N NETWORK>, B<--network NETWORK> + +Add a network interface to the sandbox. NETWORK-OPTIONS is a set of +key=val pairs, separated by commas. The following options are valid + +=over 4 + +=item dhcp + +Configure the network interface using dhcp. This key takes no value. +No other keys may be specified. eg + + -N dhcp,source=default + --network dhcp,source=lan + +where 'source' is the name of any libvirt virtual network. + +=item source=NETWORK + +Set the name of the network to connect the interface to. C<NETWORK> +is the name of any libvirt virtual network. See also B<virsh net-list> + +=item mac=NN:NN:NN:NN:NN:NN + +Set the MAC address of the network interface, where each NN is a pair +of hex digits. + +=item address=IP-ADDRESS/PREFIX%BROADCAST + +Configure the network interface with the static IPv4 or IPv6 address +B<IP-ADDRESS>. The B<PREFIX> value is the length of the network +prefix in B<IP-ADDRESS>. The optional B<BROADCAST> parameter +specifies the broadcast address. Some examples + + address=192.168.122.1/24 + address=192.168.122.1/24%192.168.122.255 + address=2001:212::204:2/64 + +=item route=IP-NETWORK/PREFIX%GATEWAY + +Configure the network interface with the static IPv4 or IPv6 route +B<IP-NETWORK>. The B<PREFIX> value is the length of the network +prefix in B<IP-NETWORK>. The B<GATEWAY> parameter specifies the +address of the gateway for the route. Some examples + + route=192.168.122.255/24%192.168.1.1 + +=back + +Can be repeated multiple times to provide multiple virtual interfaces. + +=item B<-e KEY=VAL>, B<--env KEY=VAL> + +Set the environment variable B<KEY> to the value B<VAL> when running +the initial application defined by the image. + +=back + +=head1 EXAMPLE + +Run the Ubuntu image, launching the default binary designated by the +image. + + # virt-sandbox-image run docker:///ubuntu + +Run the Fedora image, launching the '/bin/ls' binary + + # virt-sandbox-image run docker:///fedora -- /bin/ls -l / + +=head1 SEE ALSO + +C<virt-sandbox(1)>, +C<virt-sandbox-image(1)>, C<virt-sandbox-image-prepare(1)>, +C<virt-sandbox-image-purge(1)>, C<virt-sandbox-image-list(1)> + +=head1 FILES + +Pristine downloaded templates will be stored in subdirectories of +C</var/lib/libvirt/templates> (root) or C<$HOME/.local/share/libvirt/templates> +(non-root) by default. + +Overlay images created when running an instance of the template will +be stored in C</var/lib/libvirt/images> (root) or C<$HOME/.local/share/libvirt/images> +(non-root) by default. + +=head1 AUTHORS + +Daniel P. Berrangé <dan(a)berrange.com&gt;, Eren Yagdiran <erenyagdiran(a)gmail.com&gt; +and Cédric Bosdonnat <cbosdonnat(a)suse.com&gt; + +=head1 COPYRIGHT + +Copyright (C) 2011-2018 Red Hat, Inc. + +=head1 LICENSE + +virt-sandbox is distributed under the terms of the GNU LGPL v2+. +This is free software; see the source for copying conditions. +There is NO warranty; not even for MERCHANTABILITY or FITNESS +FOR A PARTICULAR PURPOSE diff --git a/man/virt-sandbox-image.pod b/man/virt-sandbox-image.pod new file mode 100644 index 0000000..9700c70 --- /dev/null +++ b/man/virt-sandbox-image.pod @@ -0,0 +1,136 @@ +=encoding utf8 + +=head1 NAME + +virt-sandbox-image - Sandbox container image tool + +=head1 SYNOPSIS + + virt-sandbox-image COMMAND [ARGS...] + +Valid B<COMMAND> values are: + + prepare Download and cache an image template + + run Launch a sandbox from an image template + + delete Delete a cached image template + + list List cached image templates + +=head1 DESCRIPTION + +B<virt-sandbox-image> is used to launch sandboxes from pre-built container +image templates. It is able to download image templates in a number of +formats from online image registries, including those built for Docker +and virt-builder. The images can be run with either QEMU (KVM) or LXC +virtualization drivers. + +Refer to the command specific manual pages for information about usage +of each command. + +=head1 OPTIONS + +=over 4 + +=item B<-h>, B<--help> + +Display help message + +=item B<-c URI>, B<--connect URI> + +The connection URI for the hypervisor. The following URIs are currently +supported + + - lxc:/// (if running as root) + - qemu:///system (if running as root) + - qemu:///session (if running as non-root) + +It is not permitted to use other virtualization drivers or non-local +URIs (ie URIs with a hostname) at this time. + +=back + +=head1 TEMPLATE URIs + +virt-sandbox-image is intended to be extensible to consume any commonly +distributed container image format. To enable different image format +to be reliably located, a URI syntax is used to identify templates +with the general syntax + + B<format+protocol://server:port/template-name?parameters> + +Refer to the text that follows for detailed information on URI +syntax for each different template format. + +=head1 DOCKER TEMPLATE URIs + +When refering to docker templates it is possible to leave out the +protocol, server port, and parameters, to just give the template +name on its own. For example + +B<docker:///ubuntu> + +Will refer to the latest Ubuntu image available on the default +Docker image registry. + +If an alternative Ubuntu image is desired, it can be requested by +setting the tag parameter. For example to get Ubuntu 15.04 + +B<docker:///ubuntu?tag=15.04> + +Support for downloading from alternative docker registries is +possible by specifying the protocol, server and (optionally) +port. For example, the bare B<docker:///ubuntu> URL above, +when fully specified would look like: + +B<docker+https://index.docker.io:443/ubuntu?tag=latest>; + +The driver for Docker images does not currently support the full +range of configuration options that are possible in docker image +metadata. It will, however, honour all command line arguments +and environment variables specified. + +=head1 VIRT BUILDER TEMPLATE URIs + +When refering to virt-builder templates the protocol, server and +port should not currently be used. Only the template name should +be given in the URI. For example + +B<virt-builder:///fedora-20> + +The virt-builder template format does not provide any metadata +about default commands to run, so the user must fully specify +what they wish to launch when running these images. + +=head1 SEE ALSO + +C<virt-sandbox(1)>, +C<virt-sandbox-image-prepare(1)>, C<virt-sandbox-image-run(1)>, +C<virt-sandbox-image-purge(1)>, C<virt-sandbox-image-list(1)> + +=head1 FILES + +Pristine downloaded templates will be stored in subdirectories of +C</var/lib/libvirt/templates> (root) or C<$HOME/.local/share/libvirt/templates> +(non-root) by default. + +Overlay images created when running an instance of the template will +be stored in C</var/lib/libvirt/images> (root) or C<$HOME/.local/share/libvirt/images> +(non-root) by default. + +=head1 AUTHORS + +Daniel P. Berrangé <dan(a)berrange.com&gt;, Eren Yagdiran <erenyagdiran(a)gmail.com&gt; +and Cédric Bosdonnat <cbosdonnat(a)suse.com&gt; + +=head1 COPYRIGHT + +Copyright (C) 2011-2018 Red Hat, Inc. + +=head1 LICENSE + +virt-sandbox is distributed under the terms of the GNU LGPL v2+. +This is free software; see the source for copying conditions. +There is NO warranty; not even for MERCHANTABILITY or FITNESS +FOR A PARTICULAR PURPOSE diff --git a/setup.py b/setup.py index c23c84d..ddd9302 100644 --- a/setup.py +++ b/setup.py @@ -4,6 +4,7 @@ from setuptools import Command from distutils.command.build import build from distutils.util import get_platform +import glob import sys import os import re @@ -38,6 +39,26 @@ class my_build(build): f1.close() f2.close() + def gen_man_pages(self): + for path in glob.glob("man/*.pod"): + base = os.path.basename(path) + appname = os.path.splitext(base)[0] + newpath = os.path.join(os.path.dirname(path), + appname + ".1") + + print("Generating %s" % newpath) + ret = os.system('pod2man ' + '--center "Virtualization Support" ' + '--release %s --name %s ' + '< %s > %s' % (self.distribution.get_version(), + appname.upper(), + path, newpath)) + if ret != 0: + raise RuntimeError("Generating '%s' failed." % newpath) + + if os.system("grep -IRq 'Hey!' man/") == 0: + raise RuntimeError("man pages have errors in them! " + "(grep for 'Hey!')") def gen_changelog(self): f1 = os.popen("git log '--pretty=format:%H:%ct %an <%ae>%n%n%s%n%b%n'") @@ -66,7 +87,7 @@ class my_build(build): self.gen_rpm_spec() self.gen_authors() self.gen_changelog() - + self.gen_man_pages() build.run(self) except: @@ -76,6 +97,7 @@ class my_build(build): for f in files: if os.path.exists(f): os.unlink(f) + raise else: build.run(self) @@ -98,6 +120,15 @@ setup( "libvirt_sandbox_image", "libvirt_sandbox_image/sources" ], + data_files=[ + ("share/man/man1", [ + "man/virt-sandbox-image.1", + "man/virt-sandbox-image-prepare.1", + "man/virt-sandbox-image-run.1", + "man/virt-sandbox-image-list.1", + "man/virt-sandbox-image-purge.1", + ]), + ], install_requires=[], cmdclass = { 'build': my_build,