[libvirt] [PATCH sandbox-image] Add manual pages to describe virt-sandbox-image
by Daniel P. Berrangé
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>
---
.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>, Eren Yagdiran <erenyagdiran(a)gmail.com>
+and Cédric Bosdonnat <cbosdonnat(a)suse.com>
+
+=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>, Eren Yagdiran <erenyagdiran(a)gmail.com>
+and Cédric Bosdonnat <cbosdonnat(a)suse.com>
+
+=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>, Eren Yagdiran <erenyagdiran(a)gmail.com>
+and Cédric Bosdonnat <cbosdonnat(a)suse.com>
+
+=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>, Eren Yagdiran <erenyagdiran(a)gmail.com>
+and Cédric Bosdonnat <cbosdonnat(a)suse.com>
+
+=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>, Eren Yagdiran <erenyagdiran(a)gmail.com>
+and Cédric Bosdonnat <cbosdonnat(a)suse.com>
+
+=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,
--
2.14.3
6 years, 7 months
[libvirt] [PATCH sandbox 0/1] split libvirt-sandbox project
by Daniel P. Berrangé
I've been preparing todo a long overdue release of the libvirt-sandbox
project. First of all I've already killed the virt-sandbox-service
tool, since that is essentially a failed concept. It had bitrotted
such that it didn't even work on a simple "httpd" systemd unit, let
alone anything complex. Docker and/or systemd do this better themselves.
I'm then also not entirely comfortable with having the
virt-sandbox-image tool as a core part of the libvirt-sandbox repo.
It is written entirely in python, and there is a simple one-way
dependancy from virt-sandbox-image onto libvirt-sandbox, so there's
no compelling reason to force them into the same repo.
Separating them will let us release them at independant times. It
will also let us use native python tools for build instead of
automake which is never a very nice fit for python.
The new repository is created using git filter-branch, so it has
preserved all git history for the virt-sandbox-image source still.
Daniel P. Berrangé (1):
Delete virt-sandbox-image tool now in separate repo
autobuild.sh | 3 +-
bin/virt-sandbox-image | 8 -
configure.ac | 4 -
libvirt-sandbox.spec.in | 9 -
libvirt-sandbox/image/Makefile.am | 10 -
libvirt-sandbox/image/__init__.py | 0
libvirt-sandbox/image/cli.py | 282 -----------
libvirt-sandbox/image/sources/Makefile.am | 10 -
libvirt-sandbox/image/sources/__init__.py | 0
libvirt-sandbox/image/sources/base.py | 160 -------
libvirt-sandbox/image/sources/docker.py | 690 ---------------------------
libvirt-sandbox/image/sources/virtbuilder.py | 109 -----
libvirt-sandbox/image/template.py | 133 ------
m4/virt-win32.m4 | 5 -
14 files changed, 1 insertion(+), 1422 deletions(-)
delete mode 100755 bin/virt-sandbox-image
delete mode 100644 libvirt-sandbox/image/Makefile.am
delete mode 100644 libvirt-sandbox/image/__init__.py
delete mode 100644 libvirt-sandbox/image/cli.py
delete mode 100644 libvirt-sandbox/image/sources/Makefile.am
delete mode 100644 libvirt-sandbox/image/sources/__init__.py
delete mode 100644 libvirt-sandbox/image/sources/base.py
delete mode 100755 libvirt-sandbox/image/sources/docker.py
delete mode 100755 libvirt-sandbox/image/sources/virtbuilder.py
delete mode 100644 libvirt-sandbox/image/template.py
--
2.14.3
6 years, 7 months
[libvirt] [not libvirt PATCH] rcc - resolve capabilities conflicts
by Ján Tomko
my tool for naively resolving qemu capabilities conflicts after a
rebase, that used to contain my latest syntax-check addition
---
rcc | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 62 insertions(+)
create mode 100755 rcc
diff --git a/rcc b/rcc
new file mode 100755
index 0000000..e0fdf41
--- /dev/null
+++ b/rcc
@@ -0,0 +1,62 @@
+#!/usr/bin/env perl
+# Automatically resolve QEMU capability conflicts
+#
+# Joins both parts of the conflicting hunk in
+# qemu_capabilities.[ch] and qemucapabilitiesdata XML
+#
+# Also rewraps the groups in qemu_capabilities.c if needed
+# and stages all the affected files.
+#
+# Author: Ján Tomko <jtomko(a)redhat.com>
+
+use warnings;
+use v5.10;
+
+use Git;
+
+sub union_merge {
+ my $filename = shift;
+
+ open FILE, '<', $filename or die "cannot open $file: $!";
+ my @original = <FILE>;
+ close FILE;
+
+ my @fixed;
+ foreach (@original) {
+ if (/^<<<<</) {
+ next;
+ } elsif (/^=====/) {
+ next;
+ } elsif (/^>>>>>/) {
+ next;
+ }
+
+ push @fixed, $_;
+ }
+
+ open FILE, '>', $filename or die "cannot open $file: $!";
+ foreach my $line (@fixed) {
+ print FILE $line;
+ }
+ close FILE;
+}
+
+my $repo = Git->repository(Directory => '.');
+my ($status_fh, $ctx) = $repo->command_output_pipe('status', '--porcelain');
+
+while (<$status_fh>) {
+ my ($flag, $filename) = split;
+ if ($flag eq 'UU') {
+ if ($filename =~ '^src/qemu/qemu_capabilities.[ch]$' or
+ $filename =~ '^tests/qemucapabilitiesdata/caps.*xml') {
+ say "Trying to fix $filename";
+ &union_merge($filename);
+ $repo->command('add', $filename);
+ }
+ }
+}
+$repo->command_close_pipe($status_fh, $ctx);
+system('tests/group-qemu-caps.pl');
+$repo->command('add', 'src/qemu/qemu_capabilities.c');
+$repo->command('add', 'src/qemu/qemu_capabilities.h');
+$repo->command('rebase', '--continue');
--
2.13.6
6 years, 7 months
[libvirt] [PATCHv2 0/3] query-cpu-model-baseline QMP command
by Chris Venteicher
Implementation of libvirt functions to support the
QEMU query-cpu-model-baseline QMP command.
This is part of resolution of: https://bugzilla.redhat.com/show_bug.cgi?id=1511999
Signed-off-by: Chris Venteicher <cventeic(a)redhat.com>
diff to v1:
- Replaced c++ style comments with c style
- qemuMonitorJSONGetCPUModelInfo{ToJSON,FromJSON} use To/From form
- qemuMonitorJSONGetCPUModelInfo{ToJSON,FromJSON} return pointers not integers
- VIR_STEAL_PTR form used
- switch statement uses virReportEnumRangeError
- qemuMonitorJSONHasError(reply, "GenericError") treated as no info, not fatal error
- virJSONValueFree(cpu_props) during error case
Chris Venteicher (3):
qemu_monitor_json: Populate CPUModelInfo struct from json
qemu_monitor_json: Build Json CPU Model Info
qemu_monitor: query-cpu-model-baseline QMP command
src/qemu/qemu_monitor.c | 13 ++++
src/qemu/qemu_monitor.h | 5 ++
src/qemu/qemu_monitor_json.c | 175 +++++++++++++++++++++++++++++++++++++------
src/qemu/qemu_monitor_json.h | 7 ++
4 files changed, 178 insertions(+), 22 deletions(-)
--
2.14.1
6 years, 7 months
[libvirt] [PATCH v4 00/14] Basic implementation of persistent reservations
by Michal Privoznik
v4 of:
https://www.redhat.com/archives/libvir-list/2018-March/msg00745.html
diff to v3:
- Peter's review worked in
Michal Privoznik (14):
virstoragefile: Introduce virStoragePRDef
qemuDomainDiskChangeSupported: Deny changing reservations
qemu: Introduce pr-manager-helper capability
qemu: Generate alias and socket path for pr-helper
qemu: Store pr runtime data in status XML
qemu_ns: Allow /dev/mapper/control for PR
qemu_cgroup: Allow /dev/mapper/control for PR
qemu: Generate cmd line at startup
qemu: Introduce pr_helper to qemu.conf
qemu: Start PR daemon on domain startup
qemu: Start PR daemon on disk hotplug
qemu_hotplug: Hotplug of reservations
qemu_hotplug: Hotunplug of reservations
qemu: Detect pr-manager-helper capability
docs/formatdomain.html.in | 25 ++-
docs/schemas/domaincommon.rng | 34 +---
docs/schemas/storagecommon.rng | 50 +++++
m4/virt-driver-qemu.m4 | 5 +
src/conf/domain_conf.c | 38 ++++
src/libvirt_private.syms | 6 +
src/qemu/libvirtd_qemu.aug | 1 +
src/qemu/qemu.conf | 4 +
src/qemu/qemu_alias.c | 11 +
src/qemu/qemu_alias.h | 2 +
src/qemu/qemu_capabilities.c | 2 +
src/qemu/qemu_capabilities.h | 1 +
src/qemu/qemu_cgroup.c | 33 ++-
src/qemu/qemu_command.c | 94 +++++++++
src/qemu/qemu_command.h | 3 +
src/qemu/qemu_conf.c | 7 +-
src/qemu/qemu_conf.h | 1 +
src/qemu/qemu_domain.c | 173 +++++++++++++++-
src/qemu/qemu_domain.h | 10 +
src/qemu/qemu_hotplug.c | 130 ++++++++++++
src/qemu/qemu_process.c | 224 +++++++++++++++++++++
src/qemu/qemu_process.h | 5 +
src/qemu/test_libvirtd_qemu.aug.in | 1 +
src/util/virdevmapper.c | 8 +-
src/util/virstoragefile.c | 164 +++++++++++++++
src/util/virstoragefile.h | 18 ++
tests/qemucapabilitiesdata/caps_2.11.0.s390x.xml | 1 +
tests/qemucapabilitiesdata/caps_2.12.0.aarch64.xml | 1 +
tests/qemucapabilitiesdata/caps_2.12.0.ppc64.xml | 1 +
tests/qemucapabilitiesdata/caps_2.12.0.s390x.xml | 1 +
tests/qemucapabilitiesdata/caps_2.12.0.x86_64.xml | 1 +
.../disk-virtio-scsi-reservations.args | 35 ++++
.../disk-virtio-scsi-reservations.xml | 49 +++++
tests/qemuxml2argvtest.c | 4 +
.../disk-virtio-scsi-reservations.xml | 1 +
tests/qemuxml2xmltest.c | 2 +
36 files changed, 1107 insertions(+), 39 deletions(-)
create mode 100644 tests/qemuxml2argvdata/disk-virtio-scsi-reservations.args
create mode 100644 tests/qemuxml2argvdata/disk-virtio-scsi-reservations.xml
create mode 120000 tests/qemuxml2xmloutdata/disk-virtio-scsi-reservations.xml
--
2.16.1
6 years, 7 months
[libvirt] [PATCH 0/5] qemu: fix domain object wait to handle monitor errors
by Nikolay Shirokovskiy
Main patch is 4th, others are misc.
Nikolay Shirokovskiy (5):
qemu: erase synchronous block job cancel mentions in comments
qemu: monitor: set error flag even in OOM conditions
utils: export virCopyError
qemu: fix domain object wait to handle monitor errors
qemu: fix races in beingDestroyed usage
src/conf/domain_conf.c | 43 ---------------------------------------
src/conf/domain_conf.h | 3 ---
src/libvirt_private.syms | 3 +--
src/qemu/qemu_domain.c | 45 +++++++++++++++++++++++++++++++++++++++++
src/qemu/qemu_domain.h | 7 +++++--
src/qemu/qemu_driver.c | 27 +++++++++++++++----------
src/qemu/qemu_hotplug.c | 4 ++--
src/qemu/qemu_migration.c | 12 +++++------
src/qemu/qemu_monitor.c | 5 +++++
src/qemu/qemu_process.c | 51 +++++++++++++++++++++++++++++++----------------
src/util/virerror.c | 12 ++++++++---
src/util/virerror.h | 1 +
12 files changed, 124 insertions(+), 89 deletions(-)
--
1.8.3.1
6 years, 7 months
[libvirt] [dbus PATCH 0/3] Last methods for Network Interface
by Katerina Koukiou
Katerina Koukiou (3):
Fix virtDBusUtilEnumFromString g_str_equal use
Implement GetDHCPLeases method for Network Interface
Implement Update method for Network Interface
data/org.libvirt.Network.xml | 17 ++++++
src/network.c | 125 +++++++++++++++++++++++++++++++++++++++++++
src/util.c | 2 +-
tests/test_network.py | 17 ++++++
4 files changed, 160 insertions(+), 1 deletion(-)
--
2.15.0
6 years, 7 months
[libvirt] [PATCH v1 0/4] CPU Model Comparsion via QEMU
by Collin Walling
[Overview]
This patch series implements an interface to "query-cpu-model-comparison"
(available QEMU ~2.8.0) via virsh cpu-compare.
[Using This Feature]
Run virsh cpu-compare (ensure you are running the virsh in your build dir) and
pass it an xml file describing a cpu definition. You can copy the cpu xml from
virsh capabilities (if you want to compare the host cpu to itself), or a cpu
defined in any guest xml. Additionally, you can create a cpu xml as such (e.g.
for s390x):
<cpu>
<arch>s390x</arch>
<model fallback='forbid'>model_name</model>
<feature policy='require|disable' name='feature_name'/>
</cpu>
NOTE: the presence of <arch> is optional and it will treat the cpu defined in
the xml as a host cpu. This will disregard all feature policies (i.e.
all features listed will behave with policy='require', even if disable
is specified).
NOTE: as s390x only supports feature policies 'require' and 'disable', I am
uncertain how to handle the other policies when parsing CPUDef to JSON.
[Example Output]
On an s390x system running a z13.2, this is the expected output (where each file
describes a CPU model corresponding to the name of the file):
$ virsh cpu-compare zEC12.xml
Host CPU is a superset of CPU described in zEC12.xml
$ virsh cpu-compare z13.2.xml
CPU described in z13.2.xml is identical to host CPU
$ virsh cpu-compare z14.xml
CPU described in z14.xml is incompatible with host CPU
$ virsh cpu-compare z14.xml --error
error: Failed to compare host CPU with z14.xml
error: the CPU is incompatible with host CPU
$ virsh cpu-compare z12345.xml
error: Failed to compare host CPU with z12345cpu.xml
error: internal error: unable to execute QEMU command 'query-cpu-model-comparison': The CPU definition 'z12345-base' is unknown.
[Patch Rundown]
The first patch copies the host CPU definition from qemuCaps to virCaps so
we can easily access the host CPU model and features when we handle the CPU
comparison in qemu_driver. Note that we take care to not clobber anything
already stored in the host CPU definition until we have successfully
constructed a new host CPU definition.
The second patch refactors the xml -> CPUDef code. This is used in
virCPUCompareXML, qemuCompareCPU (and potentially for baseline).
The third patch creates the interface from libvirt to QEMU and handles parsing
the CPUDef -> JSON and JSON -> CPUModelInfo. In order to respect the data
returned from this command, we capture the "responsible_properties" field
from the comparison command even though it is not entirely necessary for what
we are trying to accomplish here (which is to simply report if the comparison
result is "incompatible", "superset", or "identical").
The fourth patch creates the interface from virsh cpu-compare to the qemu driver.
The qemu driver will handle parsing the xml passed to the virsh command and
parsing the result of the QMP command. Note that the "incompatible" and
"subset" results are grouped together (and report "incompatible").
TODO:
- implement cpu-baseline (I've noted Chris Venteicher's current progress on this):
https://www.redhat.com/archives/libvir-list/2018-April/msg01274.html
- update qemucapabilitiestest files for qemu >= 2.8.0 (need to add comparison command)
- consider adding a new test file for comparing cpu models via QEMU if necessary
Collin Walling (4):
qemu: place qemuCaps host cpu model in virCaps
cpu_conf: xml to cpu definition parse helper
qemu: implement query-cpu-model-comparison via qemu
qemu: hook up cpu-comparison to qemu driver
src/conf/cpu_conf.c | 30 ++++++++++
src/conf/cpu_conf.h | 6 ++
src/cpu/cpu.c | 14 +----
src/libvirt_private.syms | 1 +
src/qemu/qemu_capabilities.c | 108 +++++++++++++++++++++++++++++++++++-
src/qemu/qemu_capabilities.h | 9 +++
src/qemu/qemu_driver.c | 96 ++++++++++++++++++++++++++++++++
src/qemu/qemu_monitor.c | 14 +++++
src/qemu/qemu_monitor.h | 6 ++
src/qemu/qemu_monitor_json.c | 128 +++++++++++++++++++++++++++++++++++++++++++
src/qemu/qemu_monitor_json.h | 6 ++
11 files changed, 404 insertions(+), 14 deletions(-)
--
2.7.4
6 years, 7 months
[libvirt] [PATCH] vz: build fix
by Nikolay Shirokovskiy
Broken by [1] commit - trailing comma instead of semicolon. Fortunately
the issue did not get sneak in released 4.2 version. Note that uriSchemes
for parallelsConnectDriver should not be allocated on stack.
[1] 8e4f9a27: "driver: declare supported URI schemes in virConnectDriver struct"
---
src/vz/vz_driver.c | 9 +++++----
1 file changed, 5 insertions(+), 4 deletions(-)
diff --git a/src/vz/vz_driver.c b/src/vz/vz_driver.c
index 4c30ee1..a9ee773 100644
--- a/src/vz/vz_driver.c
+++ b/src/vz/vz_driver.c
@@ -4163,7 +4163,11 @@ static virStateDriver vzStateDriver = {
/* Parallels domain type backward compatibility*/
static virHypervisorDriver parallelsHypervisorDriver;
-static virConnectDriver parallelsConnectDriver;
+static virConnectDriver parallelsConnectDriver = {
+ .localOnly = true,
+ .uriSchemes = (const char *[]){ "parallels", NULL },
+ .hypervisorDriver = ¶llelsHypervisorDriver,
+};
/**
* vzRegister:
@@ -4186,9 +4190,6 @@ vzRegister(void)
/* Backward compatibility with Parallels domain type */
parallelsHypervisorDriver = vzHypervisorDriver;
parallelsHypervisorDriver.name = "Parallels";
- parallelsConnectDriver = vzConnectDriver;
- parallelsConnectDriver.hypervisorDriver = ¶llelsHypervisorDriver;
- parallelsConnectDriver.uriSchemes = (const char *[]){ "parallels", NULL },
if (virRegisterConnectDriver(¶llelsConnectDriver, true) < 0)
return -1;
--
1.8.3.1
6 years, 7 months
[libvirt] [dbus PATCH 00/25] Introduce more Domain* APIs
by Katerina Koukiou
Katerina Koukiou (25):
Implement GetControlInfo method for Domain Interface
Implement SendKey method for Domain Interface
Implement InjectNMI method for Domain Interface
Implement BlockPeek metohd for Domain Interface
Implement MemoryPeek method for Domain Interface
Add AddIOThread method for Domain Interface
Implement BlockCommit method for Domain Interface
Implement BlockJobAbort method for Domain Interface
Implement BlockPull method for Domain Interface
Implement BlockRebase method for Domain Interface
Implement BlockResize method for Domain Interface
Implement CoreDumpWithFormat method for Domain Interface
Implement DelIOThread method for Domain Interface
Implement FSFreeze method for Domain Interface
Implement FSThaw method for Domain Interface
Implement FSTrim method for Domain Interface
Implement MigrateStartPostCopy method for Domain Interface
Implement PinEmulator method for Domain Interface
Implement PinIOThread method for Domain Interface
Implement Rename method for Domain Interface
Implement DomainRestore method for Connect Interface
Implement Save method for Domain Interface
Implement DomainSaveImageDefineXML method for Connect Interface
Implement SendProcessSignal method for Domain Interface
Implement UpdateDevice method for Domain Interface
data/org.libvirt.Connect.xml | 14 +
data/org.libvirt.Domain.xml | 157 ++++++++++
src/connect.c | 52 ++++
src/domain.c | 723 +++++++++++++++++++++++++++++++++++++++++++
4 files changed, 946 insertions(+)
--
2.15.0
6 years, 7 months