While we have a wiki page describing the feature [1] since the
feature is distributed in our .tar.gz we ought to document it. So
I went ahead, copied the wiki page and reformatted so it fits our
docs coding style.
1: http://wiki.libvirt.org/page/NSS_module
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
In preparation for adding docs about virtlockd, split out
the sanlock setup docs into a separate page.
Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
The API docs generators were broken by the header file
re-organization. Specifically
* html/libvirt-libvirt.html was empty (and should be deleted)
* Makefile.am didn't install html/libvirt-libvirt-*.html
* hvsupport.html was mostly empty
* sitemap.html.in didn't list the new html/*.html files
This new module holds and formats capabilities for emulator. If you
are about to create a new domain, you may want to know what is the
host or hypervisor capable of. To make sure we don't regress on the
XML, the formatting is not something left for each driver to
implement, rather there's general format function.
The domain capabilities is a lockable object (even though the locking
is not necessary yet) which uses reference counter.
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
The previous OOM testing support would re-run the entire "main"
method each iteration, failing a different malloc each time.
When a test suite has 'n' allocations, the number of repeats
requires is (n * (n + 1) ) / 2. This gets very large, very
quickly.
This new OOM testing support instead integrates at the
virtTestRun level, so each individual test case gets repeated,
instead of the entire test suite. This means the values of
'n' are orders of magnitude smaller.
The simple usage is
$ VIR_TEST_OOM=1 ./qemuxml2argvtest
...
29) QEMU XML-2-ARGV clock-utc ... OK
Test OOM for nalloc=36 .................................... OK
30) QEMU XML-2-ARGV clock-localtime ... OK
Test OOM for nalloc=36 .................................... OK
31) QEMU XML-2-ARGV clock-france ... OK
Test OOM for nalloc=38 ...................................... OK
...
the second lines reports how many mallocs have to be failed, and thus
how many repeats of the test will be run.
If it crashes, then running under valgrind will often show the problem
$ VIR_TEST_OOM=1 ../run valgrind ./qemuxml2argvtest
When debugging problems it is also helpful to select an individual
test case
$ VIR_TEST_RANGE=30 VIR_TEST_OOM=1 ../run valgrind ./qemuxml2argvtest
When things get really tricky, it is possible to request that just
specific allocs are failed. eg to fail allocs 5 -> 12, use
$ VIR_TEST_RANGE=30 VIR_TEST_OOM=1:5-12 ../run valgrind ./qemuxml2argvtest
In the worse case, you might want to know the stack trace of the
alloc which was failed then VIR_TEST_OOM_TRACE can be set. If it
is set to 1 then it will only print if it thinks a mistake happened.
This is often not reliable, so setting it to 2 will make it print
the stack trace for every alloc that is failed.
$ VIR_TEST_OOM_TRACE=2 VIR_TEST_RANGE=30 VIR_TEST_OOM=1:5-5 ../run valgrind ./qemuxml2argvtest
30) QEMU XML-2-ARGV clock-localtime ... OK
Test OOM for nalloc=36 !virAllocN
/home/berrange/src/virt/libvirt/src/util/viralloc.c:180
virHashCreateFull
/home/berrange/src/virt/libvirt/src/util/virhash.c:144
virDomainDefParseXML
/home/berrange/src/virt/libvirt/src/conf/domain_conf.c:11745
virDomainDefParseNode
/home/berrange/src/virt/libvirt/src/conf/domain_conf.c:12646
virDomainDefParse
/home/berrange/src/virt/libvirt/src/conf/domain_conf.c:12590
testCompareXMLToArgvFiles
/home/berrange/src/virt/libvirt/tests/qemuxml2argvtest.c:106
virtTestRun
/home/berrange/src/virt/libvirt/tests/testutils.c:250
mymain
/home/berrange/src/virt/libvirt/tests/qemuxml2argvtest.c:418 (discriminator 2)
virtTestMain
/home/berrange/src/virt/libvirt/tests/testutils.c:750
??
??:0
_start
??:?
FAILED
Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
The project has historically operated as a meritocratic
consensus based community. Formally document what has
always been an unwritten assumption amongst the community
participants. Also include an explicit code of conduct
to preempt any potential, but unlikely, future problems.
Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
Adds a new page to the website "Deployment" section describing
what data is sent to the audit logs and how to configure libvirtd
audit settings.
Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
Start a page describing some of the things that applications
using libvirt need to bear in mind to ensure security of their
systems.
Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
This adds two new pages to the website, acl.html describing
the general access control framework and permissions models,
and aclpolkit.html describing the use of polkit as an
access control driver.
page.xsl is modified to support a new syntax
<div id="include" filename="somefile.htmlinc"/>
which will cause the XSL transform to replace that <div>
with the contents of 'somefile.htmlinc'. We use this in
the acl.html.in file, to pull the table of permissions
for each libvirt object. This table is autogenerated
from the enums in src/access/viraccessperms.h by the
genaclperms.pl script.
newapi.xsl is modified so that the list of permissions
checks shown against each API will link to the description
of the permissions in acl.html
Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
Historically security issues in libvirt have been primarily
triaged & fixed by the Red Hat libvirt members & Red Hat
security team, who then usually notify other vendors via
appropriate channels. There have been a number of times
when vendors have not been properly notified ahead of
announcement. It has also disadvantaged community members
who have to backport fixes to releases for which there are
no current libvirt stable branches.
To address this, we want to make the libvirt security process
entirely community focused / driven. To this end I have setup
a new email address "libvirt-security@redhat.com" for end
users to report bugs which have (possible) security implications.
This email addr is backed by an invitation only, private
archive, mailing list. The intent is for the list membership
to comprise a subset of the libvirt core team, along with any
vendor security team engineers who wish to participate in a
responsible disclosure process for libvirt. Members of the
list will be responsible for analysing the problem to determine
if a security issue exists and then issue fixes for all current
official stable branches & git master.
I am proposing the following libvirt core team people as
members of the security team / list (all cc'd):
Daniel Berrange (Red Hat)
Eric Blake (Red Hat)
Jiri Denemar (Red Hat)
Daniel Veillard (Red Hat)
Jim Fehlig (SUSE)
Doug Goldstein (Gentoo)
Guido Günther (Debian)
We don't have anyone from Ubuntu on the libvirt core team.
Serge Hallyn is the most frequent submitter of patches from
Ubuntu in recent history, so I'd like to invite him to join.
Alternatively, Serge, feel free to suggest someone else to
represent Ubuntu's interests.
If any other vendors/distros have security people who are
responsible for dealing with libvirt security issues, and
want to join to get early disclosure of issues, they can
suggest people. Existing security team members will vet /
approve such requests to ensure they are genuine.
Anyone on the team / list will be **required** to honour any
embargo period agreed between members for non-public issues
that are reported. The aim will be to have a maximum 2 week
embargo period in the common case, extendable to 1 month if
there is sufficient justification made. If anyone feels they
are unable to follow such an embargo process for whatever
reason, please decline membership of the security list/team.
The patch which follows puts up some docs on the website
about all of this....
Document how to report security bugs and the process that
will be used for addressing them.
Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
Describe the new cgroups layout, how to customize placement
of guests and what virsh commands are used to access the
parameters.
Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
The rule generating the HTML docs passing the --html flag
to xsltproc. This makes it use the legacy HTML parser, which
either ignores or tries to fix all sorts of broken XML tags.
There's no reason why we should be writing broken XML in
the first place, so removing --html and adding the XHTML
doctype to all files forces us to create good XML.
This adds the XHTML doc type and fixes many, many XML tag
problems it exposes.
Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
This is based on recent developments on patch checker and the
goal is to keep a list of pending patches needing review on the
project web site. The page template in git just holds a pointer
to the web page.
There are a number of flaws with our packaging of the libvirtd
daemon:
- Installing 'libvirt' does not install 'qemu-kvm' or 'xen'
etc which are required to actually run the hypervisor in
question
- Installing 'libvirt' pulls in the default configuration
files which may not be wanted & cause problems if installed
inside a guest
- It is not possible to explicitly required all the peices
required to manage a specific hypervisor
This change takes the 'libvirt' RPM and and changes it thus
- libvirt: just a virtual package with dep on libvirt-daemon,
libvirt-daemon-config-network & libvirt-daemon-config-nwfilter
- libvirt-daemon: the libvirt daemon and related pieces
- libvirt-daemon-config-network: the default network config
- libvirt-daemon-config-nwfilter: the network filter configs
- libvirt-docs: the website HTML
We then introduce some more virtual (empty) packages
- libvirt-daemon-qemu: Deps on libvirt-daemon & 'qemu'
- libvirt-daemon-kvm: Deps on libvirt-daemon & 'qemu-kvm'
- libvirt-daemon-lxc: Deps on libvirt-daemon
- libvirt-daemon-uml: Deps on libvirt-daemon
- libvirt-daemon-xen: Deps on libvirt-daemon & 'xen'
- libvirt-qemu: Deps on libvirt-daemon-qemu & libvirt-daemon-config-{network,nwfilter}
- libvirt-kvm: Deps on libvirt-daemon-kvm & libvirt-daemon-config-{network,nwfilter}
- libvirt-lxc: Deps on libvirt-daemon-lxc & libvirt-daemon-config-{network,nwfilter}
- libvirt-uml: Deps on libvirt-daemon-uml & libvirt-daemon-config-{network,nwfilter}
- libvirt-xen: Deps on libvirt-daemon-xen & libvirt-daemon-config-network
My intent in the future is to turn on the driver modules by
default, at which time 'libvirt-daemon' will cease to include
any specific drivers, instead we'll get libvirt-daemon-driver-XXXX
packages for each driver. The libvirt-daemon-XXX packages will
then pull in each driver that they require.
It is recommended that applications required a locally installed
libvirtd daemon, use either 'Requires: libvirt-daemon-XXXX' or
'Requires: libvirt-XXX' and *not* "Requires: libvirt-daemon"
or 'Requires: libvirt'
* libvirt.spec.in: Refactor RPMs
* docs/packaging.html.in, docs/sitemap.html.in: Document
new RPM split rationale
This adds a page documenting many aspects of migration:
- The types of migration (managed direct, p2p, unmanaged direct)
- Data transports (native, tunnelled)
- Migration URIs
- Config file handling
- Example scenarios
* libvirt.css: Rules for data tables and diagrams
* Makefile.am: Include extra png/fig files
* migration-managed-direct.fig, migration-managed-direct.png,
migration-managed-direct.png, migration-managed-p2p.png,
migration-native.fig, migration-native.png,
migration-tunnel.fig, migration-tunnel.png,
migration-unmanaged-direct.fig, migration-unmanaged-direct.png:
Diagrams of migration
* migration.html.in, sitemap.html.in: New migration doc
* remote.html.in: Remove obsolete notes about internals of the
RPC protocol
* internals/rpc.html.in: Extensive docs on RPC protocol/API
* sitemap.html.in: Add new page
Add a page which documents how to configure lock managers,
focusing on use of sanlock with the QEMU/KVM driver
* docs/locking.html.in: Docs about lock managers
* docs/sitemap.html.in: Add lock manager config to
the deployment section
The Open Nebula driver has been unmaintained since it was first
introduced. The only commits have been for tree-wide cleanups.
It also has a major design flaw, in that it only knows about guests
that it has created itself, which makes it of very limited use.
Discussions wrt evolution of the VMWare ESX driver, concluded that
it should limit itself to single-node ESX operation and not try to
manage the multi-node architecture of VirtualCenter. Open Nebula
is a cluster like Virtual Center, not a single node system, so
the same reasoning applies.
The DeltaCloud project includes an Open Nebula driver and is a much
better fit architecturally, since it is explicitly targetting the
distributed multihost cluster scenario.
Thus this patch deletes the libvirt Open Nebula driver with the
recommendation that people use DeltaCloud for managing it instead.
* configure.ac: Remove probe for xmlrpc & --with-one arg
* daemon/Makefile.am, daemon/libvirtd.c, src/Makefile.am: Remove
ONE driver build
* src/opennebula/one_client.c, src/opennebula/one_client.h,
src/opennebula/one_conf.c, src/opennebula/one_conf.h,
src/opennebula/one_driver.c, src/opennebula/one_driver.c: Delete
files
* autobuild.sh, libvirt.spec.in, mingw32-libvirt.spec.in: Remove
build rules for Open Nebula
* docs/drivers.html.in, docs/sitemap.html.in: Remove reference
to OpenNebula
* docs/drvone.html.in: Delete file
This adds a script to generate the todo item page from
bugzilla. This requires a valid username+password for
bugzilla, so it is intended that this only be run on
the libvirt.org website via cron. Normal usage will just
generate an empty stub page.
* docs/todo.pl: Script to extract todo items from bugzilla
* docs/todo.cfg-example: Example config file
* docs/sitemap.html.in: Add todo page
* docs/Makefile.am: Generation rules for todo items
Added a workable initial page for the libvirt Application
Development Guide, giving the online viewable options +
the available download ones (pdf, epub, srpm).
Added a link to the PDF to the main Downloads page, plus
neatened the html tags throughout the page as they
were a bit of a mess.
Added --enable-compile-warnings=error to the autogen line,
as suggested by Eric Blake.
* docs/drivers.html.in: list the ESX driver
* docs/drvesx.html.in: the new ESX driver documentation
* docs/hvsupport.html.in: add the ESX driver to the matrix
* docs/index.html.in, docs/sitemap.html.in: list the ESX driver
* src/esx/esx_driver.c: fix and cleanup some comments
This patch is the result of running the following command in the docs
directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in
* docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
Define an <encryption> tag specifying volume encryption format and
format-depenedent parameters (e.g. passphrase, cipher name, key
length, key).
Currently the only defined parameter is a reference to a "secret"
(passphrase/key) managed using the virSecret* API.
Only the qcow/qcow2 encryption format, and a "default" format used to
let libvirt choose the format during volume creation, is currently
supported.
This patch does not add any users; the <encryption> tag is added in
the following patches to both volumes (to support encrypted volume
creation) and domains.
* docs/*.html: Re-generate
* docs/formatstorageencryption.html.in, docs/sitemap.html.in:
Add page describing storage encryption data format
* docs/schemas/Makefile.am, docs/schemas/storageencryption.rng:
Add RNG schema for storage encryption format
* po/POTFILES.in: Add src/storage_encryption_conf.c
* src/libvirt_private.syms: Export virStorageEncryption* functions
* src/storage_encryption_conf.h, src/storage_encryption_conf.c: Internal
helper APIs for dealing with storage encryption format
* libvirt.spec.in, mingw32-libvirt.spec.in: Add storageencryption.rng
RNG schema
This patch adds a "secret" as a separately managed object, using a
special-purpose API to transfer the secret values between nodes and
libvirt users.
* docs/schemas/secret.rng, docs/schemas/Makefilem.am: Add new
schema for virSecret objects
* docs/*html: Re-generated
* docs/formatsecret.html.in, docs/sitemap.html.in: Add page
describing the virSecret XML schema
* include/libvirt/libvirt.h.in: Define the new virSecret public
API
* src/libvirt_public.syms: Export symbols for new public APIs
* mingw32-libvirt.spec.in, libvirt.spec.in: Add secret.rng to
files list
* docs/drvone.html.in docs/drvone.html docs/drivers.html.in
docs/hvsupport.html.in docs/sitemap.html.in docs/*: added
documentation for OpenNebula driver by Abel Miguez Rodriguez
and regenerated the docs
Daniel