Commit Graph

20 Commits

Author SHA1 Message Date
Daniel P. Berrangé
fc721b0878 docs: add a minimal style guide for writing RST docs
Most importantly we document the required heading markup so that we get
consistency across the docs. Also mention that docs should have a table
of contents if they have headings & are likely longer than one page of
text.

The 3-space indent rule may sound wierd, but that's what python has
recommended and thus what tools like pandoc emit. Rather than try to
reindent things to 4-space, just accept this RST norm.

Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2019-12-04 15:48:28 +00:00
Daniel P. Berrangé
df99aa311a docs: split TLS certificate setup into its own file
The generation and deployment of x509 certificates for TLS is complex
and verbose and thus deserves its own standalone page.

Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2019-12-04 15:48:28 +00:00
Daniel P. Berrangé
0aa8536f14 docs: generate API reference pages for admin, qemu & lxc libraries
Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2019-11-22 11:14:20 +00:00
Daniel P. Berrangé
557ac8cbf5 docs: attempt to document the general libvirt dev strategy
There are various ideas / plans floating around for future libvirt work,
some of which is actively in progress. Historically we've never captured
this kind of information anywhere, except in mailing list discussions.
In particular guidelines in hacking.html.in don't appear until a policy
is actively applied.

This patch attempts to fill the documentation gap, by creating a new
"strategy" page which outlines the general vision for some notable
future changes. The key thing to note is that none of the stuff on this
page is guaranteed, plans may change as new information arises. IOW this
is a "best guess" as to the desired future.

This doc has focused on three areas, related to the topic of language
usage / consolidation

 - Use of non-C languages for the library, daemons or helper tools
 - Replacement of autotools with meson
 - Use of RST and Sphinx for documentation (website + man pages)

Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Andrea Bolognani <abologna@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2019-10-01 13:08:01 +01:00
Daniel P. Berrangé
2c52ecd960 util: purge all code for testing OOM handling
The OOM handling requires special build time options which we never
enable in our CI. Even once enabled the tests are incredibly slow and
typically require manual inspection of the results to weed out false
positives.

Since there was previous agreement to switch to abort on OOM in libvirt
code, there's no point continuing to keep the unused OOM testing code.

Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2019-09-13 10:05:17 +01:00
Eric Blake
0d44788fc3 backup: Introduce virDomainCheckpoint APIs
Introduce a bunch of new public APIs related to backup checkpoints.
Checkpoints are modeled heavily after virDomainSnapshotPtr (both
represent a point in time of the guest), although a snapshot exists
with the intent of rolling back to that state, while a checkpoint
exists to make it possible to create an incremental backup at a later
time.  We may have a future hypervisor that can completely manage
checkpoints without libvirt metadata, but the first two planned
hypervisors (qemu and test) both always use libvirt for tracking
metadata relations between checkpoints, so for now, I've deferred
the counterpart of virDomainSnapshotHasMetadata for a separate
API addition at a later date if there is ever a need for it.

Note that until we allow snapshots and checkpoints to exist
simultaneously on the same domain (although the actual prevention of
this will be in a separate patch for the sake of an easier revert down
the road), that it is not possible to branch out to create more than
one checkpoint child to a given parent, although it may become
possible later when we revert to a snapshot that coincides with a
checkpoint.  This also means that for now, the decision of which
checkpoint becomes the parent of a newly created one is the only
checkpoint with no child (so while there are APIs for dealing with a
current snapshot, we do not need those for checkpoints).  We may end
up exposing a notion of a current checkpoint later, but it's easier to
add stuff when proven needed than to blindly support it now and wish
we hadn't exposed it.

The following map shows the API relations to snapshots, with new APIs
on the right:

Operate on a domain object to create/redefine a child:
virDomainSnapshotCreateXML          virDomainCheckpointCreateXML

Operate on a child object for lifetime management:
virDomainSnapshotDelete             virDomainCheckpointDelete
virDomainSnapshotFree               virDomainCheckpointFree
virDomainSnapshotRef                virDomainCheckpointRef

Operate on a child object to learn more about it:
virDomainSnapshotGetXMLDesc         virDomainCheckpointGetXMLDesc
virDomainSnapshotGetConnect         virDomainCheckpointGetConnect
virDomainSnapshotGetDomain          virDomainCheckpointGetDomain
virDomainSnapshotGetName            virDomainCheckpiontGetName
virDomainSnapshotGetParent          virDomainCheckpiontGetParent
virDomainSnapshotHasMetadata        (deferred for later)
virDomainSnapshotIsCurrent          (no counterpart, see note above)

Operate on a domain object to list all children:
virDomainSnapshotNum                (no counterparts, these are the old
virDomainSnapshotListNames           racy interfaces)
virDomainSnapshotListAllSnapshots   virDomainListAllCheckpoints

Operate on a child object to list descendents:
virDomainSnapshotNumChildren        (no counterparts, these are the old
virDomainSnapshotListChildrenNames   racy interfaces)
virDomainSnapshotListAllChildren    virDomainCheckpointListAllChildren

Operate on a domain to locate a particular child:
virDomainSnapshotLookupByName       virDomainCheckpointLookupByName
virDomainSnapshotCurrent            (no counterpart, see note above)
virDomainHasCurrentSnapshot         (no counterpart, old racy interface)

Operate on a snapshot to roll back to earlier state:
virDomainSnapshotRevert             (no counterpart, instead checkpoints
                                     are used in incremental backups via
				     XML to virDomainBackupBegin)

Signed-off-by: Eric Blake <eblake@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2019-07-26 16:48:58 -05:00
Eric Blake
d85842cfd7 backup: Document new XML for checkpoints
Prepare for new checkpoint APIs by describing the XML that will
represent a checkpoint.  The checkpoint XML is modeled heavily after
virDomainSnapshotPtr. See the docs for more details.

Add testsuite coverage for some minimal uses of the XML (bare minimum,
the sample from html, and a full dumpxml, and some counter-examples
that should fail schema validation). Although use of the REDEFINE flag
will require the <domain> subelement to be present, it is easier for
most of the tests to provide counterpart output produced with the
NO_DOMAIN flag (particularly since synthesizing a valid <domain>
during testing is not trivial).

Signed-off-by: Eric Blake <eblake@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2019-07-26 16:48:58 -05:00
Daniel P. Berrangé
3918fb0dc1 docs: introduce a "knowledge base" for task oriented guides
The previously added AMD SEV doc was not linked from anywhere on the
website. Address this by introducing a new "Knowledge base" section
that can hold task oriented guide to various features. Moving the SEV,
disk locking and secure usage guides under this section.

Reviewed-by: Eric Blake <eblake@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2019-07-09 18:43:12 +01:00
Daniel P. Berrangé
4b4a981d60 conf: introduce virNetworkPortDefPtr struct and XML support
Introduce a virNetworkPortDefPtr struct to represent the data associated
with a virtual network port. Add APIs for parsing/formatting XML docs
with the data.

Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2019-06-17 15:19:54 +01:00
John Ferlan
784cd46fb8 docs: Add description for Storage Pool Capabilities
Signed-off-by: John Ferlan <jferlan@redhat.com>
ACKed-by: Michal Privoznik <mprivozn@redhat.com>
2019-03-06 11:12:48 -05:00
Pavel Hrdina
247e3a7275 docs: introduce libvirt-dbus binding
libvirt-dbus is a new binding that wraps libvirt API into D-Bus calls.

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Signed-off-by: Pavel Hrdina <phrdina@redhat.com>
2018-03-23 12:59:56 +01:00
Pavel Hrdina
0641b5fe06 docs: fix a typo in docs.html page
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Signed-off-by: Pavel Hrdina <phrdina@redhat.com>
2018-03-23 12:59:47 +01:00
Daniel P. Berrange
9061b3090e docs: add a page describing support guarantees for libvirt features
While we have collective knowledge about the support status of various
parts of libvirt, this has never been formally documented, leaving our
users to guess.

Note, this document makes one change to our previous policy. It explicitly
declares the RPC protocol of libvirtd as being a supported interface. THis
accepts the reality that we can a) never change it without breaking compat
with old libvirt.so, b) there are both rust + go impls that are written
against the RPC protocol already.

Reviewed-by: John Ferlan <jferlan@redhat.com>
Reviewed-by: Jim Fehlig <jfehlig@suse.com>
Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2017-11-17 16:39:14 +00:00
Daniel P. Berrange
e371b3bf41 Use https:// links for most sites
This adds a rule to require https links for the libvirt, qemu
and kvm websites.

Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2017-10-16 10:22:34 +01:00
Daniel P. Berrange
b1c81567c7 docs: switch to using HTML5 doctype declaration
The HTML5 doctype is simply

  <!DOCTYPE html>

no DTD is present because HTML5 is no longer defined as an
extension of SGML.

XSL has no way to natively output a doctype without a public
or system identifier, so we have to use an <xsl:text> hack
instead.

See also

  https://dev.w3.org/html5/html-author/#doctype-declaration

Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2017-08-02 17:00:11 +01:00
Daniel P. Berrange
5a26d1ce12 Point to the new libvirt-go bindings
The github.com/rgbkrk/libvirt-go bindings were the most complete
bindings historically, but their API coverage stops at 1.2.4,
with exception of a couple of newer APIs.

The new bindings at http://libvirt.org/git/?p=libvirt-go.git;a=log
how have (almost[1]) 100% API coverage all the way to 2.5.0. They also
expose the APIs in a way that allows for much stronger go type
checking by the compiler, and expose typed parameters as explicit
structs. Finally the bindings are able to conditionally compile against
any libvirt version 1.2.0 -> 2.5.0 without use of go build tags.

Change the docs to point to these new bindings, since they'll be
a better bet for users long term.

[1] virEvent & virStream callbacks are still TODO to be fixed
    real soon.

Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2016-12-19 10:26:22 +00:00
Daniel P. Berrange
7a568d5fca docs: remove navigation sidebar from pages
A combination of the index page, top nav bar and docs.html page
provide links to all pages on the site. The left hand nav bar
is thus redundant and can be removed to provide a simpler style
for the site.

Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2016-11-11 12:15:06 +00:00
Daniel P. Berrange
4f1812f88d docs: fill out docs page with useful links
The docs page is currently completely empty. Fill it in with
links to the various documentation, categorized as to whether
it is targetting people deploying libvirt, application
developers using libvirt, or people working on libvirt
itself.

Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2016-11-11 12:15:06 +00: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
Daniel P. Berrange
9092c3d491 Split website out into one file per page. APply new layout and styling 2008-04-23 17:08:31 +00:00