Commit Graph

55 Commits

Author SHA1 Message Date
Daniel P. Berrange
47fb613873 Fix API docs for header file re-organization
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
2014-11-13 10:20:26 +00:00
Michal Privoznik
614581f32b Introduce domain_capabilities
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>
2014-07-03 12:22:37 +02:00
Roman Bogorodskiy
e2d85e6fa1 bhyve: add basic documentation 2014-03-01 23:44:58 +04:00
Daniel P. Berrange
590029f672 Introduce new OOM testing support
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>
2014-02-20 15:36:10 +00:00
Daniel P. Berrange
e45b07314e Write up the project governance process
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>
2014-02-04 11:27:45 +00:00
Daniel P. Berrange
84fe15c332 Add docs about audit subsystem logging
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>
2013-12-02 10:43:44 +08:00
Daniel P. Berrange
8f35fd21cc Add some notes about secure usage of libvirt
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>
2013-10-15 11:33:01 +01:00
Daniel P. Berrange
da13f2c70c Add documentation for access control system
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>
2013-08-09 17:13:02 +01:00
Daniel P. Berrange
49e6a16f82 Document security reporting & handling process
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>
2013-07-01 11:08:58 +08:00
Daniel P. Berrange
486a86eb18 Add docs about cgroups layout and usage
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>
2013-05-13 12:04:42 +01:00
Daniel P. Berrange
f2f9742d4d Fix multiple formatting problems in HTML docs
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>
2013-05-03 15:56:15 +01:00
John Ferlan
6fd1b9d621 Add references for phyp and parallels 2013-03-04 17:36:03 -05:00
Cole Robinson
0cb72f2585 docs: Add 'maintenance releases' link in 'News' sidebar 2012-05-07 10:50:53 -04:00
Daniel Veillard
1ce159c1c9 Web placeholder for pending patches on the web site
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.
2012-04-13 23:57:00 +08:00
Daniel Veillard
683e011137 Revert "Refactor the libvirt RPM daemon pieces"
This reverts commit 06a0d57f5a.
2012-04-03 14:49:31 +08:00
Daniel P. Berrange
06a0d57f5a Refactor the libvirt RPM daemon pieces
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
2012-03-31 12:20:38 +01:00
Daniel P. Berrange
a784784438 Add documentation about migration.
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
2011-10-28 10:07:45 +01:00
Matthias Bolte
2137cb1911 hyperv: Add basic documentation 2011-08-26 17:52:55 +02:00
Daniel P. Berrange
977ba05973 Add some docs about the RPC protocol and APIs
* 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
2011-08-12 13:54:10 +01:00
Daniel P. Berrange
576682a5ef Add documentation for configuration lock managers
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
2011-06-28 18:19:00 +01:00
Daniel P. Berrange
395793a8ec Add initial docs about the lock managers 2011-06-02 10:54:01 +01:00
Daniel Veillard
ef82932bb5 Add documentation about test suites
Create a new top level entry, add a new page listing the 3
test suites, and then one page for the TCK and one page for
libvirt-test-API
2011-05-11 19:18:38 +08:00
Daniel P. Berrange
4591df766d Remove the Open Nebula driver
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
2011-03-28 14:09:11 +01:00
Michal Novotny
d0ae594885 Add libvirt-php information page
This adds a ibvirt-php information page with some
basic information on libvirt-php project compilation, contribution
and other useful information.
2011-02-09 09:43:09 +08:00
Justin Clift
413c88e773 docs: add a link to the bindings page under the downloads menu item
So people looking to download the language bindings, but don't know
they're under the "Docs" area.
2011-01-26 16:00:33 +11:00
Justin Clift
e23842856c docs: move the apps page to the top level as its good promo 2011-01-20 17:17:41 +11:00
Matthias Bolte
a50a22df45 docs: Move the "Network Filtering" page one level up in the hierarchy
"Network Filtering" is not directly related to "Networks".

Suggested by Daniel P. Berrange.
2011-01-18 23:14:37 +01:00
Matthias Bolte
e1cee1085a docs: Make VMware Workstation / Player page appear in the menu
By adding it to sitemap.html.in. Also <ul> can't be nested in <p>.
2010-12-23 17:01:17 +01:00
Justin Clift
2954eb7b35 docs: added compiling page and significantly expanded windows page
Also added an additional menu placement for the windows page, in
order to attract further potential testers.
2010-12-21 20:55:10 +11:00
Daniel P. Berrange
a317c50a04 virCommand: docs for usage of new command APIs
* docs/internals/command.html.in: New file.
* docs/Makefile.am: Build new docs.
* docs/subsite.xsl: New glue file.
* docs/internals.html.in, docs/sitemap.html.in: Update glue.
2010-12-02 16:00:47 -07:00
Justin Clift
7deca200e9 docs: added virsh command reference page.
Using temporary location links for the moment, until we get a
proper place to store the files on the libvirt.org server.
2010-11-13 03:51:51 +11:00
Justin Clift
5e0211e0d3 docs: removed old changelog file, as it is no longer relevant
We instead point to the live git log URL for the few links still
needing to point to something.
2010-10-23 02:56:51 +11:00
Justin Clift
956e3c5890 docs: added initial page for c# binding, with links to it
Adds a new page for the C# language bindings being developed by Arnaud
Champion.
2010-10-20 07:20:10 +11:00
Daniel P. Berrange
1938bc69a7 Add automatic generation of a todo item page
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
2010-10-12 11:26:52 +01:00
Justin Clift
7ebe214942 docs: add the app dev guide
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.
2010-09-11 01:36:38 +10:00
Cole Robinson
f8b76f419a docs: Link wiki FAQ to main page
Since DV recommended keeping the build instructions distributed with the
source, move them from the old FAQ to the downloads page.
2010-07-27 15:41:36 -04:00
Justin Clift
8cc02e8627 html docs: added firewall explanation page by daniel berrange 2010-07-10 22:47:00 +10:00
Stefan Berger
f36eb6935d nwfilter: documentation
This patch adds documentation of the nwfilter subsystem of libvirt to
the existing (web) docs.
2010-05-25 07:09:31 -04:00
Daniel Veillard
22de841a76 Add documentation for synchronous hooks
* docs/sitemap.html.in: add in navigation under
  Documentation/Deployment/Hooks
* docs/hooks.html.in: new doc describing current support for 0.8.0
2010-04-12 18:03:35 +02:00
Chris Lalancette
86fe2ba6dc Website documentation for the snapshot XML.
Signed-off-by: Chris Lalancette <clalance@redhat.com>
2010-04-06 09:44:03 -04:00
Chris Lalancette
a7d17c6187 Fix two instances of misspelled 'pseudo'
Signed-off-by: Chris Lalancette <clalance@redhat.com>
2010-01-25 16:25:28 -05:00
Matthias Bolte
57dbe08e74 esx: Add documentation to the website
* 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
2009-11-15 15:21:13 +01:00
Matthew Booth
c6d5ac174e Cleanup whitespace in docs
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
2009-11-06 16:05:18 +01:00
Miloslav Trmač
05b9b8fda3 Add volume encryption information handling.
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
2009-09-01 18:27:28 +01:00
Miloslav Trmač
6acc17af8c Secret manipulation public API
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
2009-09-01 17:38:52 +01:00
Daniel Veillard
9dfcca0353 OpenNebula driver documentation
* 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
2009-07-01 14:27:24 +00:00
Daniel P. Berrange
2c359dd609 Add HACKING doc to the website 2009-06-29 11:09:17 +00:00
Daniel P. Berrange
ce958c191c Added docs on extending public API (Dave Allen) 2009-06-09 11:42:41 +00:00
Daniel Veillard
b4ee10dfde VirtualBox Documentation
* docs/drvvbox.html.in docs/hvsupport.html.in docs/drivers.html.in
  docs/sitemap.html.in docs/*.html: VirtualBox Documentation by
  Pritesh Kothari
Daniel
2009-04-21 12:24:14 +00:00
Daniel Veillard
316befbb0c Api documentation
* docs/Makefile.am docs/api.html docs/api.html.in docs/archdomain.html
 docs/archnetwork.html docs/archnode.html docs/archstorage.html
 docs/goals.html docs/intro.html
 docs/libvirt-daemon-arch.fig docs/libvirt-daemon-arch.png
 docs/libvirt-driver-arch.fig docs/libvirt-driver-arch.png
 docs/libvirt-object-model.fig docs/libvirt-object-model.png
 docs/page.xsl docs/sitemap.html docs/sitemap.html.in:
 adding a new api page, extending the stylesheet to allow references
 and including images from Dan Berrange
daniel
2009-04-15 20:42:50 +00:00