From nobody Sun Apr 28 14:59:16 2024
Delivered-To: importer@patchew.org
Received-SPF: pass (zoho.com: domain of redhat.com designates 209.132.183.28
 as permitted sender) client-ip=209.132.183.28;
 envelope-from=libvir-list-bounces@redhat.com; helo=mx1.redhat.com;
Authentication-Results: mx.zohomail.com;
	spf=pass (zoho.com: domain of redhat.com designates 209.132.183.28 as
 permitted sender)  smtp.mailfrom=libvir-list-bounces@redhat.com;
	dmarc=pass(p=none dis=none)  header.from=redhat.com
Return-Path: <libvir-list-bounces@redhat.com>
Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28]) by
 mx.zohomail.com
	with SMTPS id 1524067943784525.8456718299439;
 Wed, 18 Apr 2018 09:12:23 -0700 (PDT)
Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com
 [10.5.11.15])
	(using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits))
	(No client certificate requested)
	by mx1.redhat.com (Postfix) with ESMTPS id 5A9C631327DD;
	Wed, 18 Apr 2018 16:12:22 +0000 (UTC)
Received: from colo-mx.corp.redhat.com
 (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20])
	by smtp.corp.redhat.com (Postfix) with ESMTPS id 288D87ED71;
	Wed, 18 Apr 2018 16:12:22 +0000 (UTC)
Received: from lists01.pubmisc.prod.ext.phx2.redhat.com
 (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33])
	by colo-mx.corp.redhat.com (Postfix) with ESMTP id DC3D5180215E;
	Wed, 18 Apr 2018 16:12:21 +0000 (UTC)
Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.rdu2.redhat.com
	[10.11.54.3])
	by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP
	id w3IGCJtP020650 for <libvir-list@listman.util.phx.redhat.com>;
	Wed, 18 Apr 2018 12:12:19 -0400
Received: by smtp.corp.redhat.com (Postfix)
	id 5B39510F1BEA; Wed, 18 Apr 2018 16:12:19 +0000 (UTC)
Received: from t460.redhat.com (unknown [10.33.36.63])
	by smtp.corp.redhat.com (Postfix) with ESMTP id 672FE10F1BE8;
	Wed, 18 Apr 2018 16:12:16 +0000 (UTC)
From: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= <berrange@redhat.com>
To: libvir-list@redhat.com
Date: Wed, 18 Apr 2018 17:12:14 +0100
Message-Id: <20180418161214.30528-1-berrange@redhat.com>
MIME-Version: 1.0
X-Scanned-By: MIMEDefang 2.78 on 10.11.54.3
X-loop: libvir-list@redhat.com
Cc: Cedric Bosdonnat <cbosdonnat@suse.com>,
	Radostin Stoyanov <rstoyanov1@gmail.com>
Subject: [libvirt] [PATCH sandbox-image] Add manual pages to describe
	virt-sandbox-image
X-BeenThere: libvir-list@redhat.com
X-Mailman-Version: 2.1.12
Precedence: junk
List-Id: Development discussions about the libvirt library & tools
	<libvir-list.redhat.com>
List-Unsubscribe: <https://www.redhat.com/mailman/options/libvir-list>,
	<mailto:libvir-list-request@redhat.com?subject=unsubscribe>
List-Archive: <https://www.redhat.com/archives/libvir-list>
List-Post: <mailto:libvir-list@redhat.com>
List-Help: <mailto:libvir-list-request@redhat.com?subject=help>
List-Subscribe: <https://www.redhat.com/mailman/listinfo/libvir-list>,
	<mailto:libvir-list-request@redhat.com?subject=subscribe>
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: quoted-printable
Sender: libvir-list-bounces@redhat.com
Errors-To: libvir-list-bounces@redhat.com
X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15
X-Greylist: Sender IP whitelisted,
 not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.47]);
 Wed, 18 Apr 2018 16:12:22 +0000 (UTC)
X-ZohoMail: RSF_0  Z_629925259 SPT_0

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=C3=A9 <berrange@redhat.com>
---
 .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
=20
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 @@
+=3Dencoding utf8
+
+=3Dhead1 NAME
+
+virt-sandbox-image list - List cached image templates
+
+=3Dhead1 SYNOPSIS
+
+  virt-sandbox-image list [-h] [-c CONNECT] [-t TEMPLATE_DIR] template
+
+=3Dhead1 DESCRIPTION
+
+B<virt-sandbox-image> is used to launch sandboxes from a pre-built contain=
er
+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.
+
+=3Dhead1 OPTIONS
+
+=3Dover 4
+
+=3Ditem B<-h>, B<--help>
+
+Display help message
+
+=3Ditem 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.
+
+=3Ditem B<-t TEMPLATE_DIR>
+
+Override the default template directory which is usually
+C</var/lib/libvirt/templates> (root) or C<$HOME/.local/share/libvirt/templ=
ates>.
+
+=3Ditem B<template>
+
+The URI identifying the template to download and prepare.
+
+=3Dback
+
+=3Dhead1 EXAMPLE
+
+Display a list of template images in the cache
+
+ # virt-sandbox-image list -c qemu:///session
+
+
+=3Dhead1 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)>
+
+=3Dhead1 FILES
+
+Pristine downloaded templates will be stored in subdirectories of
+C</var/lib/libvirt/templates> (root) or C<$HOME/.local/share/libvirt/templ=
ates>
+(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/lib=
virt/images>
+(non-root) by default.
+
+=3Dhead1 AUTHORS
+
+Daniel P. Berrang=C3=A9 <dan@berrange.com>, Eren Yagdiran <erenyagdiran@gm=
ail.com>
+and C=C3=A9dric Bosdonnat <cbosdonnat@suse.com>
+
+=3Dhead1 COPYRIGHT
+
+Copyright (C) 2011-2018 Red Hat, Inc.
+
+=3Dhead1 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-pr=
epare.pod
new file mode 100644
index 0000000..8025c40
--- /dev/null
+++ b/man/virt-sandbox-image-prepare.pod
@@ -0,0 +1,100 @@
+=3Dencoding utf8
+
+=3Dhead1 NAME
+
+virt-sandbox-image prepare - Download and cache an image template
+
+=3Dhead1 SYNOPSIS
+
+  virt-sandbox-image prepare [-h] [-c CONNECT] [-t TEMPLATE_DIR] template
+
+=3Dhead1 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.
+
+=3Dhead1 OPTIONS
+
+=3Dover 4
+
+=3Ditem B<-h>, B<--help>
+
+Display help message
+
+=3Ditem 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.
+
+=3Ditem B<-t TEMPLATE_DIR>
+
+Override the default template directory which is usually
+C</var/lib/libvirt/templates> (root) or C<$HOME/.local/share/libvirt/templ=
ates>.
+
+=3Ditem B<template>
+
+The URI identifying the template to download and prepare.
+
+=3Dback
+
+=3Dhead1 EXAMPLE
+
+Download and prepare a Docker Ubuntu 15.04 template for use with KVM
+
+ # virt-sandbox-image prepare -c qemu:///session docker:///ubuntu?tag=3D15=
.04
+
+Download and prepare a virt-builder Fedora 24 template for use with LXC
+
+ # virt-sandbox-image prepare -c lxc:/// virt-builder:///fedora-24
+
+=3Dhead1 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)>
+
+=3Dhead1 FILES
+
+Pristine downloaded templates will be stored in subdirectories of
+C</var/lib/libvirt/templates> (root) or C<$HOME/.local/share/libvirt/templ=
ates>
+(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/lib=
virt/images>
+(non-root) by default.
+
+=3Dhead1 AUTHORS
+
+Daniel P. Berrang=C3=A9 <dan@berrange.com>, Eren Yagdiran <erenyagdiran@gm=
ail.com>
+and C=C3=A9dric Bosdonnat <cbosdonnat@suse.com>
+
+=3Dhead1 COPYRIGHT
+
+Copyright (C) 2011-2018 Red Hat, Inc.
+
+=3Dhead1 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-purg=
e.pod
new file mode 100644
index 0000000..57f0a91
--- /dev/null
+++ b/man/virt-sandbox-image-purge.pod
@@ -0,0 +1,96 @@
+=3Dencoding utf8
+
+=3Dhead1 NAME
+
+virt-sandbox-image purge - Delete a cached image template
+
+=3Dhead1 SYNOPSIS
+
+  virt-sandbox-image create [-h] [-c CONNECT] [-t TEMPLATE_DIR] template
+
+=3Dhead1 DESCRIPTION
+
+B<virt-sandbox-image> is used to launch sandboxes from a pre-built contain=
er
+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 templat=
es.
+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.
+
+=3Dhead1 OPTIONS
+
+=3Dover 4
+
+=3Ditem B<-h>, B<--help>
+
+Display help message
+
+=3Ditem 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.
+
+=3Ditem B<-t TEMPLATE_DIR>
+
+Override the default template directory which is usually
+C</var/lib/libvirt/templates> (root) or C<$HOME/.local/share/libvirt/templ=
ates>.
+
+=3Ditem B<template>
+
+The URI identifying the template to download and prepare.
+
+=3Dback
+
+=3Dhead1 EXAMPLE
+
+To delete a Docker Ubuntu 15.04 template from the cache
+
+ # virt-sandbox-image purge -c qemu:///session docker:///ubuntu?tag=3D15.04
+
+=3Dhead1 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)>
+
+=3Dhead1 FILES
+
+Pristine downloaded templates will be stored in subdirectories of
+C</var/lib/libvirt/templates> (root) or C<$HOME/.local/share/libvirt/templ=
ates>
+(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/lib=
virt/images>
+(non-root) by default.
+
+=3Dhead1 AUTHORS
+
+Daniel P. Berrang=C3=A9 <dan@berrange.com>, Eren Yagdiran <erenyagdiran@gm=
ail.com>
+and C=C3=A9dric Bosdonnat <cbosdonnat@suse.com>
+
+=3Dhead1 COPYRIGHT
+
+Copyright (C) 2011-2018 Red Hat, Inc.
+
+=3Dhead1 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 @@
+=3Dencoding utf8
+
+=3Dhead1 NAME
+
+virt-sandbox-image run - Launch a sandbox from an image template
+
+=3Dhead1 SYNOPSIS
+
+  virt-sandbox-image run [-h] [-n NAME] [-c CONNECT] [-t TEMPLATE_DIR]
+                         [-I IMAGE_DIR] [-N NETWORK] [-e ENV]
+                         TEMPLATE [--] [COMMAND [ARGS...]]
+
+=3Dhead1 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 sandb=
ox.
+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<CO=
MMAND>
+is given. It is recommended to insert B<--> before B<COMMAND> to ensure th=
at
+any arguments for B<COMMAND> are not mistakenly interpreted as arguments f=
or
+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<prep=
are>
+command ahead of time, while unwanted cached content can be deleted using =
the
+B<purge> command.
+
+=3Dhead1 OPTIONS
+
+=3Dover 4
+
+=3Ditem B<-h>, B<--help>
+
+Display help message
+
+=3Ditem B<-c URI>, B<--run URI>
+
+The connection URI for the hypervisor (lxc:///, qemu:///system or
+qemu:///session only).
+
+=3Ditem B<-n NAME>, B<--name=3DNAME>
+
+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.
+
+=3Ditem B<-t TEMPLATE_DIR>, B<--template-dir TEMPLATE_DIR>
+
+Override the default location of the directory holding the image
+templates.
+
+=3Ditem B<-I IMAGE_DIR>, B<--image-dir IMAGE_DIR>
+
+Override the default location of the directory holding the instantiated
+images.
+
+=3Ditem B<-N NETWORK>, B<--network NETWORK>
+
+Add a network interface to the sandbox. NETWORK-OPTIONS is a set of
+key=3Dval pairs, separated by commas. The following options are valid
+
+=3Dover 4
+
+=3Ditem dhcp
+
+Configure the network interface using dhcp. This key takes no value.
+No other keys may be specified. eg
+
+  -N dhcp,source=3Ddefault
+  --network dhcp,source=3Dlan
+
+where 'source' is the name of any libvirt virtual network.
+
+=3Ditem source=3DNETWORK
+
+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>
+
+=3Ditem mac=3DNN:NN:NN:NN:NN:NN
+
+Set the MAC address of the network interface, where each NN is a pair
+of hex digits.
+
+=3Ditem address=3DIP-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=3D192.168.122.1/24
+  address=3D192.168.122.1/24%192.168.122.255
+  address=3D2001:212::204:2/64
+
+=3Ditem route=3DIP-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=3D192.168.122.255/24%192.168.1.1
+
+=3Dback
+
+Can be repeated multiple times to provide multiple virtual interfaces.
+
+=3Ditem B<-e KEY=3DVAL>, B<--env KEY=3DVAL>
+
+Set the environment variable B<KEY> to the value B<VAL> when running
+the initial application defined by the image.
+
+=3Dback
+
+=3Dhead1 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 /
+
+=3Dhead1 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)>
+
+=3Dhead1 FILES
+
+Pristine downloaded templates will be stored in subdirectories of
+C</var/lib/libvirt/templates> (root) or C<$HOME/.local/share/libvirt/templ=
ates>
+(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/lib=
virt/images>
+(non-root) by default.
+
+=3Dhead1 AUTHORS
+
+Daniel P. Berrang=C3=A9 <dan@berrange.com>, Eren Yagdiran <erenyagdiran@gm=
ail.com>
+and C=C3=A9dric Bosdonnat <cbosdonnat@suse.com>
+
+=3Dhead1 COPYRIGHT
+
+Copyright (C) 2011-2018 Red Hat, Inc.
+
+=3Dhead1 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 @@
+=3Dencoding utf8
+
+=3Dhead1 NAME
+
+virt-sandbox-image - Sandbox container image tool
+
+=3Dhead1 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
+
+=3Dhead1 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.
+
+=3Dhead1 OPTIONS
+
+=3Dover 4
+
+=3Ditem B<-h>, B<--help>
+
+Display help message
+
+=3Ditem 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.
+
+=3Dback
+
+=3Dhead1 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.
+
+=3Dhead1 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=3D15.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=3Dlatest>
+
+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.
+
+=3Dhead1 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.
+
+=3Dhead1 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)>
+
+=3Dhead1 FILES
+
+Pristine downloaded templates will be stored in subdirectories of
+C</var/lib/libvirt/templates> (root) or C<$HOME/.local/share/libvirt/templ=
ates>
+(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/lib=
virt/images>
+(non-root) by default.
+
+=3Dhead1 AUTHORS
+
+Daniel P. Berrang=C3=A9 <dan@berrange.com>, Eren Yagdiran <erenyagdiran@gm=
ail.com>
+and C=C3=A9dric Bosdonnat <cbosdonnat@suse.com>
+
+=3Dhead1 COPYRIGHT
+
+Copyright (C) 2011-2018 Red Hat, Inc.
+
+=3Dhead1 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
=20
+import glob
 import sys
 import os
 import re
@@ -38,6 +39,26 @@ class my_build(build):
         f1.close()
         f2.close()
=20
+    def gen_man_pages(self):
+        for path in glob.glob("man/*.pod"):
+            base =3D os.path.basename(path)
+            appname =3D os.path.splitext(base)[0]
+            newpath =3D os.path.join(os.path.dirname(path),
+                                   appname + ".1")
+
+            print("Generating %s" % newpath)
+            ret =3D os.system('pod2man '
+                            '--center "Virtualization Support" '
+                            '--release %s --name %s '
+                            '< %s > %s' % (self.distribution.get_version(),
+                                           appname.upper(),
+                                           path, newpath))
+            if ret !=3D 0:
+                raise RuntimeError("Generating '%s' failed." % newpath)
+
+        if os.system("grep -IRq 'Hey!' man/") =3D=3D 0:
+            raise RuntimeError("man pages have errors in them! "
+                               "(grep for 'Hey!')")
=20
     def gen_changelog(self):
         f1 =3D os.popen("git log '--pretty=3Dformat:%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)
=20
             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)
=20
@@ -98,6 +120,15 @@ setup(
         "libvirt_sandbox_image",
         "libvirt_sandbox_image/sources"
     ],
+    data_files=3D[
+        ("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=3D[],
     cmdclass =3D {
           'build': my_build,
--=20
2.14.3

--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list