Xen project Mailing List

[Xen-changelog] [xen staging] docs/man: Fix/simplify generation of manpages

Date: Wed, 02 Jan 2019 17:55:25 +0000

Delivery-date: Wed, 02 Jan 2019 17:55:31 +0000

List-id: "Change log for Mercurial $receive only$" <xen-changelog.lists.xenproject.org>

commit 8410fcb54ac808c19a030c6f0ec64e760ac64ca5 Author: Andrew Cooper <andrew.cooper3@xxxxxxxxxx> AuthorDate: Wed Jan 2 10:26:49 2019 +0000 Commit: Andrew Cooper <andrew.cooper3@xxxxxxxxxx> CommitDate: Wed Jan 2 17:50:36 2019 +0000 docs/man: Fix/simplify generation of manpages The original intent of this patch was to rename xen-vbd-interface.markdown.7 to xen-vbd-interface.pandoc.7 to remove the final markdown file from the docs/ tree. The DOC_MANx lists are broken. They contain MANxSRC-y twice, the first half with a partial %.pod substituation, and the second half with a partial %.markdown substitution. This is also the root cause behind the filtering activity in the uninstall-man$(i)-pages rule. Furthermore, the logic for generating the manpage targets is unnecesserily repetative, owing to the layout of source files in the man/ directory. Therefore, tackle the problem by renaming all of our manpage source files from "$FORMAT.$SECTION" to "$SECTION.$FORMAT". For the two xl.cfg.5 and xl.1 which are preprocessed by autoconf to contain path information, this requires updating configure.ac and .gitignore. The markdown to pandoc conversion is performed as well, as it is also a straight rename. An ancillary benefit of this renaming is that text editors stand a chance of being able to work out the correct mode to use. As for the makefile: 1) Break the MAN_SECTIONS list out of the GENERATE_MANPAGE_RULES loop, as we are going to use it a second time. 2) Do away with the individaul MANxSRC-y variables. Use a single list, derived from all *.pod and *.pandoc files, with their format suffixes removed. 3) Use a $(foreach ...) to generate the DOC_MANx lists, filling them with the correct content. 4) The DOC_HTML and DOC_TXT can now include all manpages with a single substitution, as they don't need to separate the manpages by section-numbered-directory. 5) Fix up the filenames in the manpage metarule to match the renaming. No functional change. Signed-off-by: Andrew Cooper <andrew.cooper3@xxxxxxxxxx> Acked-by: Ian Jackson <ian.jackson@xxxxxxxxxxxxx> --- .gitignore | 4 +- docs/Makefile | 52 +- docs/configure | 6 +- docs/configure.ac | 4 +- docs/man/xen-pci-device-reservations.7.pod | 89 + docs/man/xen-pci-device-reservations.pod.7 | 89 - docs/man/xen-pv-channel.7.pod | 189 ++ docs/man/xen-pv-channel.pod.7 | 189 -- docs/man/xen-tscmode.7.pod | 284 +++ docs/man/xen-tscmode.pod.7 | 284 --- docs/man/xen-vbd-interface.7.pandoc | 135 ++ docs/man/xen-vbd-interface.markdown.7 | 135 -- docs/man/xen-vtpm.7.pod | 383 ++++ docs/man/xen-vtpm.pod.7 | 383 ---- docs/man/xen-vtpmmgr.7.pod | 383 ++++ docs/man/xen-vtpmmgr.pod.7 | 383 ---- docs/man/xenstore-chmod.1.pod | 62 + docs/man/xenstore-chmod.pod.1 | 62 - docs/man/xenstore-ls.1.pod | 62 + docs/man/xenstore-ls.pod.1 | 62 - docs/man/xenstore-read.1.pod | 32 + docs/man/xenstore-read.pod.1 | 32 - docs/man/xenstore-write.1.pod | 29 + docs/man/xenstore-write.pod.1 | 29 - docs/man/xenstore.1.pod | 52 + docs/man/xenstore.pod.1 | 52 - docs/man/xentop.1.pod | 111 ++ docs/man/xentop.pod.1 | 111 -- docs/man/xentrace.8.pod | 166 ++ docs/man/xentrace.pod.8 | 166 -- docs/man/xentrace_format.1.pod | 46 + docs/man/xentrace_format.pod.1 | 46 - docs/man/xl-disk-configuration.5.pod | 529 ++++++ docs/man/xl-disk-configuration.pod.5 | 529 ------ docs/man/xl-network-configuration.5.pod | 251 +++ docs/man/xl-network-configuration.pod.5 | 251 --- docs/man/xl-numa-placement.7.pod | 293 +++ docs/man/xl-numa-placement.pod.7 | 293 --- docs/man/xl.1.pod.in | 1992 +++++++++++++++++++ docs/man/xl.cfg.5.pod.in | 2843 ++++++++++++++++++++++++++++ docs/man/xl.cfg.pod.5.in | 2843 ---------------------------- docs/man/xl.conf.5.pod | 222 +++ docs/man/xl.conf.pod.5 | 222 --- docs/man/xl.pod.1.in | 1992 ------------------- docs/man/xlcpupool.cfg.5.pod | 133 ++ docs/man/xlcpupool.cfg.pod.5 | 133 -- 46 files changed, 8309 insertions(+), 8329 deletions(-) diff --git a/.gitignore b/.gitignore index f11e61321a..26bc583f74 100644 --- a/.gitignore +++ b/.gitignore @@ -45,8 +45,8 @@ build-* dist/* docs/tmp.* docs/html/ -docs/man/xl.cfg.pod.5 -docs/man/xl.pod.1 +docs/man/xl.cfg.5.pod +docs/man/xl.1.pod docs/man1/ docs/man5/ docs/man7/ diff --git a/docs/Makefile b/docs/Makefile index 8f933cf93f..2867efc53b 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -6,12 +6,10 @@ VERSION := $(shell $(MAKE) -C $(XEN_ROOT)/xen --no-print-directory xenversion) DATE := $(shell date +%Y-%m-%d) DOC_ARCHES := arm x86_32 x86_64 +MAN_SECTIONS := 1 5 7 8 # Documentation sources to build -MAN1SRC-y := $(sort $(wildcard man/*.pod.1 man/*.markdown.1)) -MAN5SRC-y := $(sort $(wildcard man/*.pod.5 man/*.markdown.5)) -MAN7SRC-y := $(sort $(wildcard man/*.pod.7 man/*.markdown.7)) -MAN8SRC-y := $(sort $(wildcard man/*.pod.8 man/*.markdown.8)) +MAN-SRC-y := $(sort $(basename $(wildcard man/*.pod man/*.pandoc))) MARKDOWNSRC-y := $(sort $(shell find misc -name '*.markdown' -print)) @@ -20,38 +18,20 @@ TXTSRC-y := $(sort $(shell find misc -name '*.txt' -print)) PANDOCSRC-y := $(sort $(shell find designs/ features/ misc/ process/ specs/ -name '*.pandoc' -print)) # Documentation targets -DOC_MAN1 := $(patsubst man/%.pod.1,man1/%.1,$(MAN1SRC-y)) \ - $(patsubst man/%.markdown.1,man1/%.1,$(MAN1SRC-y)) -DOC_MAN5 := $(patsubst man/%.pod.5,man5/%.5,$(MAN5SRC-y)) \ - $(patsubst man/%.markdown.5,man5/%.5,$(MAN5SRC-y)) -DOC_MAN7 := $(patsubst man/%.pod.7,man7/%.7,$(MAN7SRC-y)) \ - $(patsubst man/%.markdown.7,man7/%.7,$(MAN7SRC-y)) -DOC_MAN8 := $(patsubst man/%.pod.8,man8/%.8,$(MAN8SRC-y)) \ - $(patsubst man/%.markdown.8,man8/%.8,$(MAN8SRC-y)) +$(foreach i,$(MAN_SECTIONS), \ + $(eval DOC_MAN$(i) := $(patsubst man/%.$(i),man$(i)/%.$(i), \ + $(filter %.$(i),$(MAN-SRC-y))))) + DOC_HTML := html/SUPPORT.html \ $(patsubst %.markdown,html/%.html,$(MARKDOWNSRC-y)) \ $(patsubst %.pandoc,html/%.html,$(PANDOCSRC-y)) \ - $(patsubst man/%.markdown.1,html/man/%.1.html,$(MAN1SRC-y)) \ - $(patsubst man/%.markdown.5,html/man/%.5.html,$(MAN5SRC-y)) \ - $(patsubst man/%.markdown.7,html/man/%.7.html,$(MAN7SRC-y)) \ - $(patsubst man/%.markdown.8,html/man/%.8.html,$(MAN8SRC-y)) \ - $(patsubst man/%.pod.1,html/man/%.1.html,$(MAN1SRC-y)) \ - $(patsubst man/%.pod.5,html/man/%.5.html,$(MAN5SRC-y)) \ - $(patsubst man/%.pod.7,html/man/%.7.html,$(MAN7SRC-y)) \ - $(patsubst man/%.pod.8,html/man/%.8.html,$(MAN8SRC-y)) \ + $(patsubst %,html/%.html,$(MAN-SRC-y)) \ $(patsubst %.txt,html/%.txt,$(TXTSRC-y)) \ $(patsubst %,html/hypercall/%/index.html,$(DOC_ARCHES)) DOC_TXT := $(patsubst %.txt,txt/%.txt,$(TXTSRC-y)) \ $(patsubst %.markdown,txt/%.txt,$(MARKDOWNSRC-y)) \ $(patsubst %.pandoc,txt/%.txt,$(PANDOCSRC-y)) \ - $(patsubst man/%.markdown.1,txt/man/%.1.txt,$(MAN1SRC-y)) \ - $(patsubst man/%.markdown.5,txt/man/%.5.txt,$(MAN5SRC-y)) \ - $(patsubst man/%.markdown.7,txt/man/%.7.txt,$(MAN7SRC-y)) \ - $(patsubst man/%.markdown.8,txt/man/%.8.txt,$(MAN8SRC-y)) \ - $(patsubst man/%.pod.1,txt/man/%.1.txt,$(MAN1SRC-y)) \ - $(patsubst man/%.pod.5,txt/man/%.5.txt,$(MAN5SRC-y)) \ - $(patsubst man/%.pod.7,txt/man/%.7.txt,$(MAN7SRC-y)) \ - $(patsubst man/%.pod.8,txt/man/%.8.txt,$(MAN8SRC-y)) + $(patsubst %,txt/%.txt,$(MAN-SRC-y)) DOC_PDF := $(patsubst %.markdown,pdf/%.pdf,$(MARKDOWNSRC-y)) \ $(patsubst %.pandoc,pdf/%.pdf,$(PANDOCSRC-y)) @@ -99,7 +79,7 @@ distclean: clean define GENERATE_MANPAGE_RULES # Real manpages -man$(1)/%.$(1): man/%.pod.$(1) Makefile +man$(1)/%.$(1): man/%.$(1).pod Makefile ifneq ($(POD2MAN),) @$(INSTALL_DIR) $$(@D) $(POD2MAN) --release=$(VERSION) --name=$$* -s $(1) -c "Xen" $$< $$@ @@ -107,7 +87,7 @@ else @echo "pod2man not installed; skipping $$@" endif -man$(1)/%.$(1): man/%.markdown.$(1) Makefile +man$(1)/%.$(1): man/%.$(1).pandoc Makefile ifneq ($(PANDOC),) @$(INSTALL_DIR) $$(@D) $(PANDOC) --standalone -V title=$$* -V section=$(1) \ @@ -118,7 +98,7 @@ else endif # HTML manpages -html/man/%.$(1).html: man/%.pod.$(1) Makefile +html/man/%.$(1).html: man/%.$(1).pod Makefile ifneq ($(POD2HTML),) @$(INSTALL_DIR) $$(@D) $(POD2HTML) --infile=$$< --outfile=$$@ @@ -126,7 +106,7 @@ else @echo "pod2html not installed; skipping $$@" endif -html/man/%.$(1).html: man/%.markdown.$(1) Makefile +html/man/%.$(1).html: man/%.$(1).pandoc Makefile ifneq ($(PANDOC),) @$(INSTALL_DIR) $$(@D) $(PANDOC) --standalone $$< -t html --toc --output $$@ @@ -135,7 +115,7 @@ else endif # Text manpages -txt/man/%.$(1).txt: man/%.pod.$(1) Makefile +txt/man/%.$(1).txt: man/%.$(1).pod Makefile ifneq ($(POD2TEXT),) @$(INSTALL_DIR) $$(@D) $(POD2TEXT) $$< $$@ @@ -143,7 +123,7 @@ else @echo "pod2text not installed; skipping $$@" endif -txt/man/%.$(1).txt: man/%.markdown.$(1) Makefile +txt/man/%.$(1).txt: man/%.$(1).pandoc Makefile ifneq ($(PANDOC),) @$(INSTALL_DIR) $$(@D) $(PANDOC) --standalone $$< -t plain --output $$@ @@ -169,7 +149,7 @@ clean-man$(1)-pages: # Uninstall .PHONY: uninstall-man$(1)-pages uninstall-man$(1)-pages: - rm -f $(addprefix $(DESTDIR)$(mandir)/man$(1)/, $(filter-out %.pod.$(1) %.markdown.$(1), $(notdir $(DOC_MAN$(1))))) + rm -f $(addprefix $(DESTDIR)$(mandir)/,$(DOC_MAN$(1))) # Link buld/install/clean to toplevel rules man-pages: man$(1)-pages @@ -180,7 +160,7 @@ uninstall-man-pages: uninstall-man$(1)-pages endef # Generate manpage rules for each section -$(foreach i,1 5 7 8,$(eval $(call GENERATE_MANPAGE_RULES,$(i)))) +$(foreach i,$(MAN_SECTIONS),$(eval $(call GENERATE_MANPAGE_RULES,$(i)))) .PHONY: install-html install-html: html txt figs diff --git a/docs/configure b/docs/configure index a3b4cb6223..3e0089c435 100755 --- a/docs/configure +++ b/docs/configure @@ -1752,7 +1752,7 @@ ac_compiler_gnu=$ac_cv_c_compiler_gnu -ac_config_files="$ac_config_files ../config/Docs.mk man/xl.cfg.pod.5 man/xl.pod.1" +ac_config_files="$ac_config_files ../config/Docs.mk man/xl.cfg.5.pod man/xl.1.pod" ac_aux_dir= for ac_dir in ../ "$srcdir"/../; do @@ -3031,8 +3031,8 @@ for ac_config_target in $ac_config_targets do case $ac_config_target in "../config/Docs.mk") CONFIG_FILES="$CONFIG_FILES ../config/Docs.mk" ;; - "man/xl.cfg.pod.5") CONFIG_FILES="$CONFIG_FILES man/xl.cfg.pod.5" ;; - "man/xl.pod.1") CONFIG_FILES="$CONFIG_FILES man/xl.pod.1" ;; + "man/xl.cfg.5.pod") CONFIG_FILES="$CONFIG_FILES man/xl.cfg.5.pod" ;; + "man/xl.1.pod") CONFIG_FILES="$CONFIG_FILES man/xl.1.pod" ;; *) as_fn_error $? "invalid argument: \`$ac_config_target'" "$LINENO" 5;; esac diff --git a/docs/configure.ac b/docs/configure.ac index a2929c4aaa..577716265c 100644 --- a/docs/configure.ac +++ b/docs/configure.ac @@ -7,8 +7,8 @@ AC_INIT([Xen Hypervisor Documentation], m4_esyscmd([../version.sh ../xen/Makefil AC_CONFIG_SRCDIR([misc/xen-command-line.markdown]) AC_CONFIG_FILES([ ../config/Docs.mk -man/xl.cfg.pod.5 -man/xl.pod.1 +man/xl.cfg.5.pod +man/xl.1.pod ]) AC_CONFIG_AUX_DIR([../]) diff --git a/docs/man/xen-pci-device-reservations.7.pod b/docs/man/xen-pci-device-reservations.7.pod new file mode 100644 index 0000000000..0df41bcd29 --- /dev/null +++ b/docs/man/xen-pci-device-reservations.7.pod @@ -0,0 +1,89 @@ +=head1 NAME + +xen-pci-device-reservations - Xen PCI device ID registry + +=head1 Description + +PCI vendor ID 0x5853 has been reserved for use by Xen systems in order to +advertise certain virtual hardware to guest virtual machines. The primary +use of this is with device ID 0x0001 to advertise the Xen Platform PCI +device - the presence of this virtual device enables a guest Operating +System (subject to the availability of suitable drivers) to make use of +paravirtualisation features such as disk and network devices etc. + +Some Xen vendors wish to provide alternative and/or additional guest drivers +that can bind to virtual devices[1]. This may be done using the Xen PCI +vendor ID of 0x5853 and Xen-vendor/device specific PCI device IDs. This file +records reservations made within the device ID range in order to avoid +multiple Xen vendors using conflicting IDs. + +=head1 Guidelines + +=over 4 + +=item 1. A vendor may request a range of device IDs by submitting a patch to + this file. + +=item 2. Vendor allocations should be in the range 0xc000-0xfffe to reduce the + possibility of clashes with community IDs assigned from the bottom up. + +=item 3. The vendor is responsible for allocations within the range and should + try to record specific device IDs in PCI ID databases such as + http://pciids.sourceforge.net and http//www.pcidatabase.com + +=back + +=head1 Reservations + + range | vendor/product + --------------+-------------------------------------------------------------- + 0x0001 | (Xen Platform PCI device) + 0x0002 | Citrix XenServer (grandfathered allocation for XenServer 6.1) + 0xc000-0xc0ff | Citrix XenServer + 0xc100-0xc1ff | Citrix XenClient + 0xc200-0xc2ff | XCP-ng Project (https://xcp-ng.org) + +=head1 Notes + +=over 4 + +=item 1. + +Upstream QEMU provides a parameterized device called xen-pvdevice that +can be used to host guest drivers. Execute: + + qemu-system-i386 -device xen-pvdevice,help + +for a list of all parameters. The following parameters are relevant to +driver binding: + +=over 4 + +=item vendor-id (default 0x5853) + +The PCI vendor ID and subsystem vendor ID of the device. + +=item device-id (must be specified) + +The PCI device ID and subsystem device ID of the device. + +=item revision (default 0x01) + +The PCI revision of the device + +=back + +Also the size parameter (default 0x400000) can be used to specify the +size of the single MMIO BAR that the device exposes. This area may be +used by drivers for mapping grant tables, etc. + +Note that the presence of the Xen Platform PCI device is generally a +pre-requisite for an additional xen-pvdevice as it is the platform +device that provides that IO ports necessary for unplugging emulated +devices. See hvm-emulated-unplug.markdown for details of the IO ports +and unplug protocol. + +libxl provides support for creation of a single additional xen-pvdevice. +See the vendor_device parameter in xl.cfg(5). + +=back diff --git a/docs/man/xen-pci-device-reservations.pod.7 b/docs/man/xen-pci-device-reservations.pod.7 deleted file mode 100644 index 0df41bcd29..0000000000 --- a/docs/man/xen-pci-device-reservations.pod.7 +++ /dev/null @@ -1,89 +0,0 @@ -=head1 NAME - -xen-pci-device-reservations - Xen PCI device ID registry - -=head1 Description - -PCI vendor ID 0x5853 has been reserved for use by Xen systems in order to -advertise certain virtual hardware to guest virtual machines. The primary -use of this is with device ID 0x0001 to advertise the Xen Platform PCI -device - the presence of this virtual device enables a guest Operating -System (subject to the availability of suitable drivers) to make use of -paravirtualisation features such as disk and network devices etc. - -Some Xen vendors wish to provide alternative and/or additional guest drivers -that can bind to virtual devices[1]. This may be done using the Xen PCI -vendor ID of 0x5853 and Xen-vendor/device specific PCI device IDs. This file -records reservations made within the device ID range in order to avoid -multiple Xen vendors using conflicting IDs. - -=head1 Guidelines - -=over 4 - -=item 1. A vendor may request a range of device IDs by submitting a patch to - this file. - -=item 2. Vendor allocations should be in the range 0xc000-0xfffe to reduce the - possibility of clashes with community IDs assigned from the bottom up. - -=item 3. The vendor is responsible for allocations within the range and should - try to record specific device IDs in PCI ID databases such as - http://pciids.sourceforge.net and http//www.pcidatabase.com - -=back - -=head1 Reservations - - range | vendor/product - --------------+-------------------------------------------------------------- - 0x0001 | (Xen Platform PCI device) - 0x0002 | Citrix XenServer (grandfathered allocation for XenServer 6.1) - 0xc000-0xc0ff | Citrix XenServer - 0xc100-0xc1ff | Citrix XenClient - 0xc200-0xc2ff | XCP-ng Project (https://xcp-ng.org) - -=head1 Notes - -=over 4 - -=item 1. - -Upstream QEMU provides a parameterized device called xen-pvdevice that -can be used to host guest drivers. Execute: - - qemu-system-i386 -device xen-pvdevice,help - -for a list of all parameters. The following parameters are relevant to -driver binding: - -=over 4 - -=item vendor-id (default 0x5853) - -The PCI vendor ID and subsystem vendor ID of the device. - -=item device-id (must be specified) - -The PCI device ID and subsystem device ID of the device. - -=item revision (default 0x01) - -The PCI revision of the device - -=back - -Also the size parameter (default 0x400000) can be used to specify the -size of the single MMIO BAR that the device exposes. This area may be -used by drivers for mapping grant tables, etc. - -Note that the presence of the Xen Platform PCI device is generally a -pre-requisite for an additional xen-pvdevice as it is the platform -device that provides that IO ports necessary for unplugging emulated -devices. See hvm-emulated-unplug.markdown for details of the IO ports -and unplug protocol. - -libxl provides support for creation of a single additional xen-pvdevice. -See the vendor_device parameter in xl.cfg(5). - -=back diff --git a/docs/man/xen-pv-channel.7.pod b/docs/man/xen-pv-channel.7.pod new file mode 100644 index 0000000000..07898f6dde --- /dev/null +++ b/docs/man/xen-pv-channel.7.pod @@ -0,0 +1,189 @@ +=encoding utf8 + +=head1 NAME + +xen-pv-channel - Xen PV Channels + +=head1 DESCRIPTION + +A channel is a low-bandwidth private byte stream similar to a serial +link. Typical uses of channels are + +=over + +=item 1. + +to provide initial configuration information to a VM on boot +(example use: CloudStack's cloud-early-config service) + + +=item 2. + +to signal/query an in-guest agent +(example use: oVirt's guest agent) + + +=back + +Channels are similar to virtio-serial devices and emulated serial links. +Channels are intended to be used in the implementation of libvirt s +when running on Xen. + +Note: if an application requires a high-bandwidth link then it should use +vchan instead. + + +=head2 How to use channels: an example + +Consider a cloud deployment where VMs are cloned from pre-made templates, +and customised on first boot by an in-guest agent which sets the IP address, +hostname, ssh keys etc. To install the system the cloud administrator would +first: + +=over + +=item 1. + +Install a guest as normal (no channel configuration necessary) + + +=item 2. + +Install the in-guest agent specific to the cloud software. This will +prepare the guest to communicate over the channel, and also prepare +the guest to be cloned safely (sometimes known as "sysprepping") + + +=item 3. + +Shutdown the guest + + +=item 4. + +Register the guest as a template with the cloud orchestration software + + +=item 5. + +Install the cloud orchestration agent in dom0 + + +=back + +At runtime, when a cloud tenant requests that a VM is created from the template, +the sequence of events would be: (assuming a Linux domU) + +=over + +=item 1. + +A VM is "cloned" from the template + + +=item 2. + +A unique Unix domain socket path in dom0 is allocated +(e.g. /my/cloud/software/talk/to/domain/) + + +=item 3. + +Domain configuration is created for the VM, listing the channel +name expected by the in-guest agent. In xl syntax this would be: + +channel = [ "connection=socket, name=org.my.cloud.software.agent.version1, path = /my/cloud/software/talk/to/domain/" ] + +=item 4. + +The VM is started + + +=item 5. + +In dom0 the cloud orchestration agent connects to the Unix domain +socket, writes a handshake message and waits for a reply + + +=item 6. + +Assuming the guest kernel has CONFIG_HVC_XEN_FRONTEND set then the console +driver will generate a hotplug event + + +=item 7. + +A udev rule is activated by the hotplug event. + +The udev rule would look something like: + +SUBSYSTEM=="xen", DEVPATH=="/devices/console-[0-9]", RUN+="xen-console-setup" + +where the "xen-console-setup" script would read the channel name and +make a symlink in /dev/xen-channel/org.my.cloud.software.agent.version1 +pointing to /dev/hvcN. N is the same number as the number in "/devices/console-[0-9]". +In other words, "/devices/console-2" maps to /dev/hvc2. + + +=item 8. + +The in-guest agent uses inotify to see the creation of the /dev/xen-channel +symlink and opens the device. + + +=item 9. + +The in-guest agent completes the handshake with the dom0 agent + + +=item 10. + +The dom0 agent transmits the unique VM configuration: hostname, IP +address, ssh keys etc etc + + +=item 11. + +The in-guest agent receives the configuration and applies it. + + +=back + +Using channels avoids having to use a temporary disk device or network +connection. + + +=head2 Design recommendations and pitfalls + +It's necessary to install channel-specific software (an "agent") into the guest +before you can use a channel. By default a channel will appear as a device +which could be mistaken for a serial port or regular console. It is known +that some software will proactively seek out serial ports and issue AT commands +at them; make sure such software is disabled! + +Since channels are identified by names, application authors must ensure their +channel names are unique to avoid clashes. We recommend that channel names +include parts unique to the application such as a domain names. To assist +prevent clashes we recommend authors add their names to our global channel +registry at the end of this document. + + +=head2 Limitations + +Hotplug and unplug of channels is not currently implemented. + + +=head2 Channel name registry + +It is important that channel names are globally unique. To help ensure +that no-one's name clashes with yours, please add yours to this list. + + Key: + N: Name + C: Contact + D: Short description of use, possibly including a URL to your software or API + + N: org.xenproject.guest.clipboard.0.1 + C: David Scott <dave.scott@xxxxxxxxxx> + D: Share clipboard data via an in-guest agent. See: + http://wiki.xenproject.org/wiki/Clipboard_sharing_protocol diff --git a/docs/man/xen-pv-channel.pod.7 b/docs/man/xen-pv-channel.pod.7 deleted file mode 100644 index 07898f6dde..0000000000 --- a/docs/man/xen-pv-channel.pod.7 +++ /dev/null @@ -1,189 +0,0 @@ -=encoding utf8 - -=head1 NAME - -xen-pv-channel - Xen PV Channels - -=head1 DESCRIPTION - -A channel is a low-bandwidth private byte stream similar to a serial -link. Typical uses of channels are - -=over - -=item 1. - -to provide initial configuration information to a VM on boot -(example use: CloudStack's cloud-early-config service) - - -=item 2. - -to signal/query an in-guest agent -(example use: oVirt's guest agent) - - -=back - -Channels are similar to virtio-serial devices and emulated serial links. -Channels are intended to be used in the implementation of libvirt s -when running on Xen. - -Note: if an application requires a high-bandwidth link then it should use -vchan instead. - - -=head2 How to use channels: an example - -Consider a cloud deployment where VMs are cloned from pre-made templates, -and customised on first boot by an in-guest agent which sets the IP address, -hostname, ssh keys etc. To install the system the cloud administrator would -first: - -=over - -=item 1. - -Install a guest as normal (no channel configuration necessary) - - -=item 2. - -Install the in-guest agent specific to the cloud software. This will -prepare the guest to communicate over the channel, and also prepare -the guest to be cloned safely (sometimes known as "sysprepping") - - -=item 3. - -Shutdown the guest - - -=item 4. - -Register the guest as a template with the cloud orchestration software - - -=item 5. - -Install the cloud orchestration agent in dom0 - - -=back - -At runtime, when a cloud tenant requests that a VM is created from the template, -the sequence of events would be: (assuming a Linux domU) - -=over - -=item 1. - -A VM is "cloned" from the template - - -=item 2. - -A unique Unix domain socket path in dom0 is allocated -(e.g. /my/cloud/software/talk/to/domain/) - - -=item 3. - -Domain configuration is created for the VM, listing the channel -name expected by the in-guest agent. In xl syntax this would be: - -channel = [ "connection=socket, name=org.my.cloud.software.agent.version1, path = /my/cloud/software/talk/to/domain/" ] - -=item 4. - -The VM is started - - -=item 5. - -In dom0 the cloud orchestration agent connects to the Unix domain -socket, writes a handshake message and waits for a reply - - -=item 6. - -Assuming the guest kernel has CONFIG_HVC_XEN_FRONTEND set then the console -driver will generate a hotplug event - - -=item 7. - -A udev rule is activated by the hotplug event. - -The udev rule would look something like: - -SUBSYSTEM=="xen", DEVPATH=="/devices/console-[0-9]", RUN+="xen-console-setup" - -where the "xen-console-setup" script would read the channel name and -make a symlink in /dev/xen-channel/org.my.cloud.software.agent.version1 -pointing to /dev/hvcN. N is the same number as the number in "/devices/console-[0-9]". -In other words, "/devices/console-2" maps to /dev/hvc2. - - -=item 8. - -The in-guest agent uses inotify to see the creation of the /dev/xen-channel -symlink and opens the device. - - -=item 9. - -The in-guest agent completes the handshake with the dom0 agent - - -=item 10. - -The dom0 agent transmits the unique VM configuration: hostname, IP -address, ssh keys etc etc - - -=item 11. - -The in-guest agent receives the configuration and applies it. - - -=back - -Using channels avoids having to use a temporary disk device or network -connection. - - -=head2 Design recommendations and pitfalls - -It's necessary to install channel-specific software (an "agent") into the guest -before you can use a channel. By default a channel will appear as a device -which could be mistaken for a serial port or regular console. It is known -that some software will proactively seek out serial ports and issue AT commands -at them; make sure such software is disabled! - -Since channels are identified by names, application authors must ensure their -channel names are unique to avoid clashes. We recommend that channel names -include parts unique to the application such as a domain names. To assist -prevent clashes we recommend authors add their names to our global channel -registry at the end of this document. - - -=head2 Limitations - -Hotplug and unplug of channels is not currently implemented. - - -=head2 Channel name registry - -It is important that channel names are globally unique. To help ensure -that no-one's name clashes with yours, please add yours to this list. - - Key: - N: Name - C: Contact - D: Short description of use, possibly including a URL to your software or API - - N: org.xenproject.guest.clipboard.0.1 - C: David Scott <dave.scott@xxxxxxxxxx> - D: Share clipboard data via an in-guest agent. See: - http://wiki.xenproject.org/wiki/Clipboard_sharing_protocol diff --git a/docs/man/xen-tscmode.7.pod b/docs/man/xen-tscmode.7.pod new file mode 100644 index 0000000000..1d81a3fe18 --- /dev/null +++ b/docs/man/xen-tscmode.7.pod @@ -0,0 +1,284 @@ +=head1 NAME + +xen-tscmode - Xen TSC (time stamp counter) and timekeeping discussion + +=head1 OVERVIEW + +As of Xen 4.0, a new config option called tsc_mode may be specified +for each domain. The default for tsc_mode handles the vast majority +of hardware and software environments. This document is targeted +for Xen users and administrators that may need to select a non-default +tsc_mode. + +Proper selection of tsc_mode depends on an understanding not only of +the guest operating system (OS), but also of the application set that will +ever run on this guest OS. This is because tsc_mode applies +equally to both the OS and ALL apps that are running on this +domain, now or in the future. + +Key questions to be answered for the OS and/or each application are: + +=over 4 + +=item * + +Does the OS/app use the rdtsc instruction at all? +(We will explain below how to determine this.) + +=item * + +At what frequency is the rdtsc instruction executed by either the OS +or any running apps? If the sum exceeds about 10,000 rdtsc instructions +per second per processor, we call this a "high-TSC-frequency" +OS/app/environment. (This is relatively rare, and developers of OS's +and apps that are high-TSC-frequency are usually aware of it.) + +=item * + +If the OS/app does use rdtsc, will it behave incorrectly if "time goes +backwards" or if the frequency of the TSC suddenly changes? If so, +we call this a "TSC-sensitive" app or OS; otherwise it is "TSC-resilient". + +=back + +This last is the US$64,000 question as it may be very difficult +(or, for legacy apps, even impossible) to predict all possible +failure cases. As a result, unless proven otherwise, any app +that uses rdtsc must be assumed to be TSC-sensitive and, as we +will see, this is the default starting in Xen 4.0. + +Xen's new tsc_mode parameter determines the circumstances under which +the family of rdtsc instructions are executed "natively" vs emulated. +Roughly speaking, native means rdtsc is fast but TSC-sensitive apps +may, under unpredictable circumstances, run incorrectly; emulated means +there is some performance degradation (unobservable in most cases), +but TSC-sensitive apps will always run correctly. Prior to Xen 4.0, +all rdtsc instructions were native: "fast but potentially incorrect." +Starting at Xen 4.0, the default is that all rdtsc instructions are +"correct but potentially slow". The tsc_mode parameter in 4.0 provides +an intelligent default but allows system administrator's to adjust +how rdtsc instructions are executed differently for different domains. + +The non-default choices for tsc_mode are: + +=over 4 + +=item * B<tsc_mode=1> (always emulate). + +All rdtsc instructions are emulated; this is the best choice when +TSC-sensitive apps are running and it is necessary to understand +worst-case performance degradation for a specific hardware environment. + +=item * B<tsc_mode=2> (never emulate). + +This is the same as prior to Xen 4.0 and is the best choice if it +is certain that all apps running in this VM are TSC-resilient and +highest performance is required. + +=item * B<tsc_mode=3> (PVRDTSCP). + +This mode has been removed. + +=back + +If tsc_mode is left unspecified (or set to B<tsc_mode=0>), a hybrid +algorithm is utilized to ensure correctness while providing the +best performance possible given: + +=over 4 + +=item * + +the requirement of correctness, + +=item * + +the underlying hardware, and + +=item * + +whether or not the VM has been saved/restored/migrated + +=back + +To understand this in more detail, the rest of this document must +be read. + +=head1 DETERMINING RDTSC FREQUENCY + +To determine the frequency of rdtsc instructions that are emulated, +an "xl" command can be used by a privileged user of domain0. The +command: + + # xl debug-key s; xl dmesg | tail + +provides information about TSC usage in each domain where TSC +emulation is currently enabled. + +=head1 TSC HISTORY + +To understand tsc_mode completely, some background on TSC is required: + +The x86 "timestamp counter", or TSC, is a 64-bit register on each +processor that increases monotonically. Historically, TSC incremented +every processor cycle, but on recent processors, it increases +at a constant rate even if the processor changes frequency (for example, +to reduce processor power usage). TSC is known by x86 programmers +as the fastest, highest-precision measurement of the passage of time +so it is often used as a foundation for performance monitoring. +And since it is guaranteed to be monotonically increasing and, at +64 bits, is guaranteed to not wraparound within 10 years, it is +sometimes used as a random number or a unique sequence identifier, +such as to stamp transactions so they can be replayed in a specific +order. + +On most older SMP and early multi-core machines, TSC was not synchronized +between processors. Thus if an application were to read the TSC on +one processor, then was moved by the OS to another processor, then read +TSC again, it might appear that "time went backwards". This loss of +monotonicity resulted in many obscure application bugs when TSC-sensitive +apps were ported from a uniprocessor to an SMP environment; as a result, +many applications -- especially in the Windows world -- removed their +dependency on TSC and replaced their timestamp needs with OS-specific +functions, losing both performance and precision. On some more recent +generations of multi-core machines, especially multi-socket multi-core +machines, the TSC was synchronized but if one processor were to enter +certain low-power states, its TSC would stop, destroying the synchrony +and again causing obscure bugs. This reinforced decisions to avoid use +of TSC altogether. On the most recent generations of multi-core +machines, however, synchronization is provided across all processors +in all power states, even on multi-socket machines, and provide a +flag that indicates that TSC is synchronized and "invariant". Thus +TSC is once again useful for applications, and even newer operating +systems are using and depending upon TSC for critical timekeeping +tasks when running on these recent machines. + +We will refer to hardware that ensures TSC is both synchronized and +invariant as "TSC-safe" and any hardware on which TSC is not (or +may not remain) synchronized as "TSC-unsafe". + +As a result of TSC's sordid history, two classes of applications use +TSC: old applications designed for single processors, and the most recent +enterprise applications which require high-frequency high-precision +timestamping. + +We will refer to apps that might break if running on a TSC-unsafe +machine as "TSC-sensitive"; apps that don't use TSC, or do use +TSC but use it in a way that monotonicity and frequency invariance +are unimportant as "TSC-resilient". + +The emergence of virtualization once again complicates the usage of +TSC. When features such as save/restore or live migration are employed, +a guest OS and all its currently running applications may be invisibly +transported to an entirely different physical machine. While TSC +may be "safe" on one machine, it is essentially impossible to precisely +synchronize TSC across a data center or even a pool of machines. As +a result, when run in a virtualized environment, rare and obscure +"time going backwards" problems might once again occur for those +TSC-sensitive applications. Worse, if a guest OS moves from, for +example, a 3GHz +machine to a 1.5GHz machine, attempts by an OS/app to measure time +intervals with TSC may without notice be incorrect by a factor of two. + +The rdtsc (read timestamp counter) instruction is used to read the +TSC register. The rdtscp instruction is a variant of rdtsc on recent +processors. We refer to these together as the rdtsc family of instructions, +or just "rdtsc". Instructions in the rdtsc family are non-privileged, but +privileged software may set a cpuid bit to cause all rdtsc family +instructions to trap. This trap can be detected by Xen, which can +then transparently "emulate" the results of the rdtsc instruction and +return control to the code following the rdtsc instruction. + +To provide a "safe" TSC, i.e. to ensure both TSC monotonicity and a +fixed rate, Xen provides rdtsc emulation whenever necessary or when +explicitly specified by a per-VM configuration option. TSC emulation is +relatively slow -- roughly 15-20 times slower than the rdtsc instruction +when executed natively. However, except when an OS or application uses +the rdtsc instruction at a high frequency (e.g. more than about 10,000 times +per second per processor), this performance degradation is not noticeable +(i.e. <0.3%). And, TSC emulation is nearly always faster than +OS-provided alternatives (e.g. Linux's gettimeofday). For environments +where it is certain that all apps are TSC-resilient (e.g. +"TSC-safeness" is not necessary) and highest performance is a +requirement, TSC emulation may be entirely disabled (tsc_mode==2). + +The default mode (tsc_mode==0) checks TSC-safeness of the underlying +hardware on which the virtual machine is launched. If it is +TSC-safe, rdtsc will execute at hardware speed; if it is not, rdtsc +will be emulated. Once a virtual machine is save/restored or migrated, +however, there are two possibilities: TSC remains native IF the source +physical machine and target physical machine have the same TSC frequency +(or, for HVM/PVH guests, if TSC scaling support is available); else TSC +is emulated. Note that, though emulated, the "apparent" TSC frequency +will be the TSC frequency of the initial physical machine, even after +migration. + +Finally, tsc_mode==1 always enables TSC emulation, regardless of +the underlying physical hardware. The "apparent" TSC frequency will +be the TSC frequency of the initial physical machine, even after migration. +This mode is useful to measure any performance degradation that +might be encountered by a tsc_mode==0 domain after migration occurs, +or a tsc_mode==3 domain when it is running on TSC-unsafe hardware. + +Note that while Xen ensures that an emulated TSC is "safe" across migration, +it does not ensure that it continues to tick at the same rate during +the actual migration. As an oversimplified example, if TSC is ticking +once per second in a guest, and the guest is saved when the TSC is 1000, +then restored 30 seconds later, TSC is only guaranteed to be greater +than or equal to 1001, not precisely 1030. This has some OS implications +as will be seen in the next section. + +=head1 TSC INVARIANT BIT and NO_MIGRATE + +Related to TSC emulation, the "TSC Invariant" bit is architecturally defined +in a cpuid bit on the most recent x86 processors. If set, TSC invariance +ensures that the TSC is "safe", that is it will increment at a constant rate +regardless of power events, will be synchronized across all processors, and +was properly initialized to zero on all processors at boot-time +by system hardware/BIOS. As long as system software never writes to TSC, +TSC will be safe and continuously incremented at a fixed rate and thus +can be used as a system "clocksource". + +This bit is used by some OS's, and specifically by Linux starting with +version 2.6.30(?), to select TSC as a system clocksource. Once selected, +TSC remains the Linux system clocksource unless manually overridden. In +a virtualized environment, since it is not possible to synchronize TSC +across all the machines in a pool or data center, a migration may "break" +TSC as a usable clocksource; while time will not go backwards, it may +not track wallclock time well enough to avoid certain time-sensitive +consequences. As a result, Xen can only expose the TSC Invariant bit +to a guest OS if it is certain that the domain will never migrate. +As of Xen 4.0, the "no_migrate=1" VM configuration option may be specified +to disable migration. If no_migrate is selected and the VM is running +on a physical machine with "TSC Invariant", Linux 2.6.30+ will safely +use TSC as the system clocksource. But, attempts to migrate or, once +saved, restore this domain will fail. + +There is another cpuid-related complication: The x86 cpuid instruction is +non-privileged. HVM domains are configured to always trap this instruction +to Xen, where Xen can "filter" the result. In a PV OS, all cpuid instructions +have been replaced by a paravirtualized equivalent of the cpuid instruction +("pvcpuid") and also trap to Xen. But apps in a PV guest that use a +cpuid instruction execute it directly, without a trap to Xen. As a result, +an app may directly examine the physical TSC Invariant cpuid bit and make +decisions based on that bit. + +=head1 HARDWARE TSC SCALING + +Intel VMX TSC scaling and AMD SVM TSC ratio allow the guest TSC read +by guest rdtsc/p increasing in a different frequency than the host +TSC frequency. + +If a HVM container in default TSC mode (tsc_mode=0) is created on a host +that provides constant TSC, its guest TSC frequency will be the same as +the host. If it is later migrated to another host that provides constant +TSC and supports Intel VMX TSC scaling/AMD SVM TSC ratio, its guest TSC +frequency will be the same before and after migration. + +For above HVM container in default TSC mode (tsc_mode=0), if above +hosts support rdtscp, both guest rdtsc and rdtscp instructions will be +executed natively before and after migration. + +=head1 AUTHORS + +Dan Magenheimer <dan.magenheimer@xxxxxxxxxx> diff --git a/docs/man/xen-tscmode.pod.7 b/docs/man/xen-tscmode.pod.7 deleted file mode 100644 index 1d81a3fe18..0000000000 --- a/docs/man/xen-tscmode.pod.7 +++ /dev/null @@ -1,284 +0,0 @@ -=head1 NAME - -xen-tscmode - Xen TSC (time stamp counter) and timekeeping discussion - -=head1 OVERVIEW - -As of Xen 4.0, a new config option called tsc_mode may be specified -for each domain. The default for tsc_mode handles the vast majority -of hardware and software environments. This document is targeted -for Xen users and administrators that may need to select a non-default -tsc_mode. - -Proper selection of tsc_mode depends on an understanding not only of -the guest operating system (OS), but also of the application set that will -ever run on this guest OS. This is because tsc_mode applies -equally to both the OS and ALL apps that are running on this -domain, now or in the future. - -Key questions to be answered for the OS and/or each application are: - -=over 4 - -=item * - -Does the OS/app use the rdtsc instruction at all? -(We will explain below how to determine this.) - -=item * - -At what frequency is the rdtsc instruction executed by either the OS -or any running apps? If the sum exceeds about 10,000 rdtsc instructions -per second per processor, we call this a "high-TSC-frequency" -OS/app/environment. (This is relatively rare, and developers of OS's -and apps that are high-TSC-frequency are usually aware of it.) - -=item * - -If the OS/app does use rdtsc, will it behave incorrectly if "time goes -backwards" or if the frequency of the TSC suddenly changes? If so, -we call this a "TSC-sensitive" app or OS; otherwise it is "TSC-resilient". - -=back - -This last is the US$64,000 question as it may be very difficult -(or, for legacy apps, even impossible) to predict all possible -failure cases. As a result, unless proven otherwise, any app -that uses rdtsc must be assumed to be TSC-sensitive and, as we -will see, this is the default starting in Xen 4.0. - -Xen's new tsc_mode parameter determines the circumstances under which -the family of rdtsc instructions are executed "natively" vs emulated. -Roughly speaking, native means rdtsc is fast but TSC-sensitive apps -may, under unpredictable circumstances, run incorrectly; emulated means -there is some performance degradation (unobservable in most cases), -but TSC-sensitive apps will always run correctly. Prior to Xen 4.0, -all rdtsc instructions were native: "fast but potentially incorrect." -Starting at Xen 4.0, the default is that all rdtsc instructions are -"correct but potentially slow". The tsc_mode parameter in 4.0 provides -an intelligent default but allows system administrator's to adjust -how rdtsc instructions are executed differently for different domains. - -The non-default choices for tsc_mode are: - -=over 4 - -=item * B<tsc_mode=1> (always emulate). - -All rdtsc instructions are emulated; this is the best choice when -TSC-sensitive apps are running and it is necessary to understand -worst-case performance degradation for a specific hardware environment. - -=item * B<tsc_mode=2> (never emulate). - -This is the same as prior to Xen 4.0 and is the best choice if it -is certain that all apps running in this VM are TSC-resilient and -highest performance is required. - -=item * B<tsc_mode=3> (PVRDTSCP). - -This mode has been removed. - -=back - -If tsc_mode is left unspecified (or set to B<tsc_mode=0>), a hybrid -algorithm is utilized to ensure correctness while providing the -best performance possible given: - -=over 4 - -=item * - -the requirement of correctness, - -=item * - -the underlying hardware, and - -=item * - -whether or not the VM has been saved/restored/migrated - -=back - -To understand this in more detail, the rest of this document must -be read. - -=head1 DETERMINING RDTSC FREQUENCY - -To determine the frequency of rdtsc instructions that are emulated, -an "xl" command can be used by a privileged user of domain0. The -command: - - # xl debug-key s; xl dmesg | tail - -provides information about TSC usage in each domain where TSC -emulation is currently enabled. - -=head1 TSC HISTORY - -To understand tsc_mode completely, some background on TSC is required: - -The x86 "timestamp counter", or TSC, is a 64-bit register on each -processor that increases monotonically. Historically, TSC incremented -every processor cycle, but on recent processors, it increases -at a constant rate even if the processor changes frequency (for example, -to reduce processor power usage). TSC is known by x86 programmers -as the fastest, highest-precision measurement of the passage of time -so it is often used as a foundation for performance monitoring. -And since it is guaranteed to be monotonically increasing and, at -64 bits, is guaranteed to not wraparound within 10 years, it is -sometimes used as a random number or a unique sequence identifier, -such as to stamp transactions so they can be replayed in a specific -order. - -On most older SMP and early multi-core machines, TSC was not synchronized -between processors. Thus if an application were to read the TSC on -one processor, then was moved by the OS to another processor, then read -TSC again, it might appear that "time went backwards". This loss of -monotonicity resulted in many obscure application bugs when TSC-sensitive -apps were ported from a uniprocessor to an SMP environment; as a result, -many applications -- especially in the Windows world -- removed their -dependency on TSC and replaced their timestamp needs with OS-specific -functions, losing both performance and precision. On some more recent -generations of multi-core machines, especially multi-socket multi-core -machines, the TSC was synchronized but if one processor were to enter -certain low-power states, its TSC would stop, destroying the synchrony -and again causing obscure bugs. This reinforced decisions to avoid use -of TSC altogether. On the most recent generations of multi-core -machines, however, synchronization is provided across all processors -in all power states, even on multi-socket machines, and provide a -flag that indicates that TSC is synchronized and "invariant". Thus -TSC is once again useful for applications, and even newer operating -systems are using and depending upon TSC for critical timekeeping -tasks when running on these recent machines. - -We will refer to hardware that ensures TSC is both synchronized and -invariant as "TSC-safe" and any hardware on which TSC is not (or -may not remain) synchronized as "TSC-unsafe". - -As a result of TSC's sordid history, two classes of applications use -TSC: old applications designed for single processors, and the most recent -enterprise applications which require high-frequency high-precision -timestamping. - -We will refer to apps that might break if running on a TSC-unsafe -machine as "TSC-sensitive"; apps that don't use TSC, or do use -TSC but use it in a way that monotonicity and frequency invariance -are unimportant as "TSC-resilient". - -The emergence of virtualization once again complicates the usage of -TSC. When features such as save/restore or live migration are employed, -a guest OS and all its currently running applications may be invisibly -transported to an entirely different physical machine. While TSC -may be "safe" on one machine, it is essentially impossible to precisely -synchronize TSC across a data center or even a pool of machines. As -a result, when run in a virtualized environment, rare and obscure -"time going backwards" problems might once again occur for those -TSC-sensitive applications. Worse, if a guest OS moves from, for -example, a 3GHz -machine to a 1.5GHz machine, attempts by an OS/app to measure time -intervals with TSC may without notice be incorrect by a factor of two. - -The rdtsc (read timestamp counter) instruction is used to read the -TSC register. The rdtscp instruction is a variant of rdtsc on recent -processors. We refer to these together as the rdtsc family of instructions, -or just "rdtsc". Instructions in the rdtsc family are non-privileged, but -privileged software may set a cpuid bit to cause all rdtsc family -instructions to trap. This trap can be detected by Xen, which can -then transparently "emulate" the results of the rdtsc instruction and -return control to the code following the rdtsc instruction. - -To provide a "safe" TSC, i.e. to ensure both TSC monotonicity and a -fixed rate, Xen provides rdtsc emulation whenever necessary or when -explicitly specified by a per-VM configuration option. TSC emulation is -relatively slow -- roughly 15-20 times slower than the rdtsc instruction -when executed natively. However, except when an OS or application uses -the rdtsc instruction at a high frequency (e.g. more than about 10,000 times -per second per processor), this performance degradation is not noticeable -(i.e. <0.3%). And, TSC emulation is nearly always faster than -OS-provided alternatives (e.g. Linux's gettimeofday). For environments -where it is certain that all apps are TSC-resilient (e.g. -"TSC-safeness" is not necessary) and highest performance is a -requirement, TSC emulation may be entirely disabled (tsc_mode==2). - -The default mode (tsc_mode==0) checks TSC-safeness of the underlying -hardware on which the virtual machine is launched. If it is -TSC-safe, rdtsc will execute at hardware speed; if it is not, rdtsc -will be emulated. Once a virtual machine is save/restored or migrated, -however, there are two possibilities: TSC remains native IF the source -physical machine and target physical machine have the same TSC frequency -(or, for HVM/PVH guests, if TSC scaling support is available); else TSC -is emulated. Note that, though emulated, the "apparent" TSC frequency -will be the TSC frequency of the initial physical machine, even after -migration. - -Finally, tsc_mode==1 always enables TSC emulation, regardless of -the underlying physical hardware. The "apparent" TSC frequency will -be the TSC frequency of the initial physical machine, even after migration. -This mode is useful to measure any performance degradation that -might be encountered by a tsc_mode==0 domain after migration occurs, -or a tsc_mode==3 domain when it is running on TSC-unsafe hardware. - -Note that while Xen ensures that an emulated TSC is "safe" across migration, -it does not ensure that it continues to tick at the same rate during -the actual migration. As an oversimplified example, if TSC is ticking -once per second in a guest, and the guest is saved when the TSC is 1000, -then restored 30 seconds later, TSC is only guaranteed to be greater -than or equal to 1001, not precisely 1030. This has some OS implications -as will be seen in the next section. - -=head1 TSC INVARIANT BIT and NO_MIGRATE - -Related to TSC emulation, the "TSC Invariant" bit is architecturally defined -in a cpuid bit on the most recent x86 processors. If set, TSC invariance -ensures that the TSC is "safe", that is it will increment at a constant rate -regardless of power events, will be synchronized across all processors, and -was properly initialized to zero on all processors at boot-time -by system hardware/BIOS. As long as system software never writes to TSC, -TSC will be safe and continuously incremented at a fixed rate and thus -can be used as a system "clocksource". - -This bit is used by some OS's, and specifically by Linux starting with -version 2.6.30(?), to select TSC as a system clocksource. Once selected, -TSC remains the Linux system clocksource unless manually overridden. In -a virtualized environment, since it is not possible to synchronize TSC -across all the machines in a pool or data center, a migration may "break" -TSC as a usable clocksource; while time will not go backwards, it may -not track wallclock time well enough to avoid certain time-sensitive -consequences. As a result, Xen can only expose the TSC Invariant bit -to a guest OS if it is certain that the domain will never migrate. -As of Xen 4.0, the "no_migrate=1" VM configuration option may be specified -to disable migration. If no_migrate is selected and the VM is running -on a physical machine with "TSC Invariant", Linux 2.6.30+ will safely -use TSC as the system clocksource. But, attempts to migrate or, once -saved, restore this domain will fail. - -There is another cpuid-related complication: The x86 cpuid instruction is -non-privileged. HVM domains are configured to always trap this instruction -to Xen, where Xen can "filter" the result. In a PV OS, all cpuid instructions -have been replaced by a paravirtualized equivalent of the cpuid instruction -("pvcpuid") and also trap to Xen. But apps in a PV guest that use a -cpuid instruction execute it directly, without a trap to Xen. As a result, -an app may directly examine the physical TSC Invariant cpuid bit and make -decisions based on that bit. - -=head1 HARDWARE TSC SCALING - -Intel VMX TSC scaling and AMD SVM TSC ratio allow the guest TSC read -by guest rdtsc/p increasing in a different frequency than the host -TSC frequency. - -If a HVM container in default TSC mode (tsc_mode=0) is created on a host -that provides constant TSC, its guest TSC frequency will be the same as -the host. If it is later migrated to another host that provides constant -TSC and supports Intel VMX TSC scaling/AMD SVM TSC ratio, its guest TSC -frequency will be the same before and after migration. - -For above HVM container in default TSC mode (tsc_mode=0), if above -hosts support rdtscp, both guest rdtsc and rdtscp instructions will be -executed natively before and after migration. - -=head1 AUTHORS - -Dan Magenheimer <dan.magenheimer@xxxxxxxxxx> diff --git a/docs/man/xen-vbd-interface.7.pandoc b/docs/man/xen-vbd-interface.7.pandoc new file mode 100644 index 0000000000..1c996bf64d --- /dev/null +++ b/docs/man/xen-vbd-interface.7.pandoc @@ -0,0 +1,135 @@ +Xen guest interface +------------------- + +A Xen guest can be provided with block devices. These are always +provided as Xen VBDs; for HVM guests they may also be provided as +emulated IDE, AHCI or SCSI disks. + +The abstract interface involves specifying, for each block device: + + * Nominal disk type: Xen virtual disk (aka xvd*, the default); SCSI + (sd*); IDE or AHCI (hd*). + + For HVM guests, each whole-disk hd* and and sd* device is made + available _both_ via emulated IDE resp. SCSI controller, _and_ as a + Xen VBD. The HVM guest is entitled to assume that the IDE or SCSI + disks available via the emulated IDE controller target the same + underlying devices as the corresponding Xen VBD (ie, multipath). + In hd* case with hdtype=ahci, disk will be AHCI via emulated + ich9 disk controller. + + For PV guests every device is made available to the guest only as a + Xen VBD. For these domains the type is advisory, for use by the + guest's device naming scheme. + + The Xen interface does not specify what name a device should have + in the guest (nor what major/minor device number it should have in + the guest, if the guest has such a concept). + + * Disk number, which is a nonnegative integer, + conventionally starting at 0 for the first disk. + + * Partition number, which is a nonnegative integer where by + convention partition 0 indicates the "whole disk". + + Normally for any disk _either_ partition 0 should be supplied in + which case the guest is expected to treat it as they would a native + whole disk (for example by putting or expecting a partition table + or disk label on it); + + _Or_ only non-0 partitions should be supplied in which case the + guest should expect storage management to be done by the host and + treat each vbd as it would a partition or slice or LVM volume (for + example by putting or expecting a filesystem on it). + + Non-whole disk devices cannot be passed through to HVM guests via + the emulated IDE or SCSI controllers. + + +Configuration file syntax +------------------------- + +The config file syntaxes are, for example + + d0 d0p0 xvda Xen virtual disk 0 partition 0 (whole disk) + d1p2 xvdb2 Xen virtual disk 1 partition 2 + d536p37 xvdtq37 Xen virtual disk 536 partition 37 + sdb3 SCSI disk 1 partition 3 + hdc2 IDE disk 2 partition 2 + +The d*p* syntax is not supported by xm/xend. + +To cope with guests which predate this specification we preserve the +existing facility to specify the xenstore numerical value directly by +putting a single number (hex, decimal or octal) in the domain config +file instead of the disk identifier; this number is written directly +to xenstore (after conversion to the canonical decimal format). + + +Concrete encoding in the VBD interface (in xenstore) +---------------------------------------------------- + +The information above is encoded in the concrete interface as an +integer (in a canonical decimal format in xenstore), whose value +encodes the information above as follows: + + 1 << 28 | disk << 8 | partition xvd, disks or partitions 16 onwards + 202 << 8 | disk << 4 | partition xvd, disks and partitions up to 15 + 8 << 8 | disk << 4 | partition sd, disks and partitions up to 15 + 3 << 8 | disk << 6 | partition hd, disks 0..1, partitions 0..63 + 22 << 8 | (disk-2) << 6 | partition hd, disks 2..3, partitions 0..63 + 2 << 28 onwards reserved for future use + other values less than 1 << 28 deprecated / reserved + +The 1<<28 format handles disks up to (1<<20)-1 and partitions up to +255. It will be used only where the 202<<8 format does not have +enough bits. + +Guests MAY support any subset of the formats above except that if they +support 1<<28 they MUST also support 202<<8. PV-on-HVM drivers MUST +support at least one of 3<<8 or 8<<8; 3<<8 is recommended. + +Some software has used or understood Linux-specific encodings for SCSI +disks beyond disk 15 partition 15, and IDE disks beyond disk 3 +partition 63. These vbds, and the corresponding encoded integers, are +deprecated. + +Guests SHOULD ignore numbers that they do not understand or +recognise. They SHOULD check supplied numbers for validity. + + +Notes on Linux as a guest +------------------------- + +Very old Linux guests (PV and PV-on-HVM) are able to "steal" the +device numbers and names normally used by the IDE and SCSI +controllers, so that writing "hda1" in the config file results in +/dev/hda1 in the guest. These systems interpret the xenstore integer +as + major << 8 | minor +where major and minor are the Linux-specific device numbers. Some old +configurations may depend on deprecated high-numbered SCSI and IDE +disks. This does not work in recent versions of Linux. + +So for Linux PV guests, users are recommended to supply xvd* devices +only. Modern PV drivers will map these to identically-named devices +in the guest. + +For Linux HVM guests using PV-on-HVM drivers, users are recommended to +supply as few hd* devices as possible, and for the rest of the disks, +to use pure xvd* devices starting at xvde. Modern PV-on-HVM drivers +will map provided hd* devices to the corresponding /dev/xvd* (for +example, hda is presented also as /dev/xvda). + +Some Linux HVM guests with broken PV-on-HVM drivers do not cope +properly if both hda and hdc are supplied, nor with both hda and xvda, +because they directly map the bottom 8 bits of the xenstore integer +directly to the Linux guest's device number and throw away the rest; +they can crash due to minor number clashes. With these guests, the +workaround is not to supply problematic combinations of devices. + + +Other frontend and backend options +---------------------------------- + +See xen/include/public/io/blkif.h for the full list of options. diff --git a/docs/man/xen-vbd-interface.markdown.7 b/docs/man/xen-vbd-interface.markdown.7 deleted file mode 100644 index 1c996bf64d..0000000000 --- a/docs/man/xen-vbd-interface.markdown.7 +++ /dev/null @@ -1,135 +0,0 @@ -Xen guest interface -------------------- - -A Xen guest can be provided with block devices. These are always -provided as Xen VBDs; for HVM guests they may also be provided as -emulated IDE, AHCI or SCSI disks. - -The abstract interface involves specifying, for each block device: - - * Nominal disk type: Xen virtual disk (aka xvd*, the default); SCSI - (sd*); IDE or AHCI (hd*). - - For HVM guests, each whole-disk hd* and and sd* device is made - available _both_ via emulated IDE resp. SCSI controller, _and_ as a - Xen VBD. The HVM guest is entitled to assume that the IDE or SCSI - disks available via the emulated IDE controller target the same - underlying devices as the corresponding Xen VBD (ie, multipath). - In hd* case with hdtype=ahci, disk will be AHCI via emulated - ich9 disk controller. - - For PV guests every device is made available to the guest only as a - Xen VBD. For these domains the type is advisory, for use by the - guest's device naming scheme. - - The Xen interface does not specify what name a device should have - in the guest (nor what major/minor device number it should have in - the guest, if the guest has such a concept). - - * Disk number, which is a nonnegative integer, - conventionally starting at 0 for the first disk. - - * Partition number, which is a nonnegative integer where by - convention partition 0 indicates the "whole disk". - - Normally for any disk _either_ partition 0 should be supplied in - which case the guest is expected to treat it as they would a native - whole disk (for example by putting or expecting a partition table - or disk label on it); - - _Or_ only non-0 partitions should be supplied in which case the - guest should expect storage management to be done by the host and - treat each vbd as it would a partition or slice or LVM volume (for - example by putting or expecting a filesystem on it). - - Non-whole disk devices cannot be passed through to HVM guests via - the emulated IDE or SCSI controllers. - - -Configuration file syntax -------------------------- - -The config file syntaxes are, for example - - d0 d0p0 xvda Xen virtual disk 0 partition 0 (whole disk) - d1p2 xvdb2 Xen virtual disk 1 partition 2 - d536p37 xvdtq37 Xen virtual disk 536 partition 37 - sdb3 SCSI disk 1 partition 3 - hdc2 IDE disk 2 partition 2 - -The d*p* syntax is not supported by xm/xend. - -To cope with guests which predate this specification we preserve the -existing facility to specify the xenstore numerical value directly by -putting a single number (hex, decimal or octal) in the domain config -file instead of the disk identifier; this number is written directly -to xenstore (after conversion to the canonical decimal format). - - -Concrete encoding in the VBD interface (in xenstore) ----------------------------------------------------- - -The information above is encoded in the concrete interface as an -integer (in a canonical decimal format in xenstore), whose value -encodes the information above as follows: - - 1 << 28 | disk << 8 | partition xvd, disks or partitions 16 onwards - 202 << 8 | disk << 4 | partition xvd, disks and partitions up to 15 - 8 << 8 | disk << 4 | partition sd, disks and partitions up to 15 - 3 << 8 | disk << 6 | partition hd, disks 0..1, partitions 0..63 - 22 << 8 | (disk-2) << 6 | partition hd, disks 2..3, partitions 0..63 - 2 << 28 onwards reserved for future use - other values less than 1 << 28 deprecated / reserved - -The 1<<28 format handles disks up to (1<<20)-1 and partitions up to -255. It will be used only where the 202<<8 format does not have -enough bits. - -Guests MAY support any subset of the formats above except that if they -support 1<<28 they MUST also support 202<<8. PV-on-HVM drivers MUST -support at least one of 3<<8 or 8<<8; 3<<8 is recommended. - -Some software has used or understood Linux-specific encodings for SCSI -disks beyond disk 15 partition 15, and IDE disks beyond disk 3 -partition 63. These vbds, and the corresponding encoded integers, are -deprecated. - -Guests SHOULD ignore numbers that they do not understand or -recognise. They SHOULD check supplied numbers for validity. - - -Notes on Linux as a guest -------------------------- - -Very old Linux guests (PV and PV-on-HVM) are able to "steal" the -device numbers and names normally used by the IDE and SCSI -controllers, so that writing "hda1" in the config file results in -/dev/hda1 in the guest. These systems interpret the xenstore integer -as - major << 8 | minor -where major and minor are the Linux-specific device numbers. Some old -configurations may depend on deprecated high-numbered SCSI and IDE -disks. This does not work in recent versions of Linux. - -So for Linux PV guests, users are recommended to supply xvd* devices -only. Modern PV drivers will map these to identically-named devices -in the guest. - -For Linux HVM guests using PV-on-HVM drivers, users are recommended to -supply as few hd* devices as possible, and for the rest of the disks, -to use pure xvd* devices starting at xvde. Modern PV-on-HVM drivers -will map provided hd* devices to the corresponding /dev/xvd* (for -example, hda is presented also as /dev/xvda). - -Some Linux HVM guests with broken PV-on-HVM drivers do not cope -properly if both hda and hdc are supplied, nor with both hda and xvda, -because they directly map the bottom 8 bits of the xenstore integer -directly to the Linux guest's device number and throw away the rest; -they can crash due to minor number clashes. With these guests, the -workaround is not to supply problematic combinations of devices. - - -Other frontend and backend options ----------------------------------- - -See xen/include/public/io/blkif.h for the full list of options. diff --git a/docs/man/xen-vtpm.7.pod b/docs/man/xen-vtpm.7.pod new file mode 100644 index 0000000000..1d8185616a --- /dev/null +++ b/docs/man/xen-vtpm.7.pod @@ -0,0 +1,383 @@ +=head1 NAME + +xen-vtpm - Xen virtual Trusted Platform Module (vTPM) subsystem + +=head1 RUBRIC + +Copyright (c) 2010-2012 United States Government, as represented by +the Secretary of Defense. All rights reserved. +November 12 2012 +Authors: Matthew Fioravante (JHUAPL), Daniel De Graaf (NSA) + +This document describes the virtual Trusted Platform Module (vTPM) subsystem +for Xen. The reader is assumed to have familiarity with building and installing +Xen, Linux, and a basic understanding of the TPM and vTPM concepts. + +=head1 INTRODUCTION + +The goal of this work is to provide a TPM functionality to a virtual guest +operating system (a DomU). This allows programs to interact with a TPM in a +virtual system the same way they interact with a TPM on the physical system. +Each guest gets its own unique, emulated, software TPM. However, each of the +vTPM's secrets (Keys, NVRAM, etc) are managed by a vTPM Manager domain, which +seals the secrets to the Physical TPM. If the process of creating each of these +domains (manager, vTPM, and guest) is trusted, the vTPM subsystem extends the +chain of trust rooted in the hardware TPM to virtual machines in Xen. Each +major component of vTPM is implemented as a separate domain, providing secure +separation guaranteed by the hypervisor. The vTPM domains are implemented in +mini-os to reduce memory and processor overhead. + +This mini-os vTPM subsystem was built on top of the previous vTPM work done by +IBM and Intel corporation. + +=head1 DESIGN OVERVIEW + +The architecture of vTPM is described below: + + +------------------+ + | Linux DomU | ... + | | ^ | + | v | | + | xen-tpmfront | + +------------------+ + | ^ + v | + +------------------+ + | mini-os/tpmback | + | | ^ | + | v | | + | vtpm-stubdom | ... + | | ^ | + | v | | + | mini-os/tpmfront | + +------------------+ + | ^ + v | + +------------------+ + | mini-os/tpmback | + | | ^ | + | v | | + | vtpmmgr-stubdom | + | | ^ | + | v | | + | mini-os/tpm_tis | + +------------------+ + | ^ + v | + +------------------+ + | Hardware TPM | + +------------------+ + +=over 4 + +=item Linux DomU + +The Linux based guest that wants to use a vTPM. There many be +more than one of these. + +=item xen-tpmfront.ko + +Linux kernel virtual TPM frontend driver. This driver +provides vTPM access to a para-virtualized Linux based DomU. + +=item mini-os/tpmback + +Mini-os TPM backend driver. The Linux frontend driver +connects to this backend driver to facilitate +communications between the Linux DomU and its vTPM. This +driver is also used by vtpmmgr-stubdom to communicate with +vtpm-stubdom. + +=item vtpm-stubdom + +A mini-os stub domain that implements a vTPM. There is a +one to one mapping between running vtpm-stubdom instances and +logical vtpms on the system. The vTPM Platform Configuration +Registers (PCRs) are all initialized to zero. + +=item mini-os/tpmfront + +Mini-os TPM frontend driver. The vTPM mini-os domain +vtpm-stubdom uses this driver to communicate with +vtpmmgr-stubdom. This driver could also be used separately to +implement a mini-os domain that wishes to use a vTPM of +its own. + +=item vtpmmgr-stubdom + +A mini-os domain that implements the vTPM manager. +There is only one vTPM manager and it should be running during +the entire lifetime of the machine. This domain regulates +access to the physical TPM on the system and secures the +persistent state of each vTPM. + +=item mini-os/tpm_tis + +Mini-os TPM version 1.2 TPM Interface Specification (TIS) +driver. This driver used by vtpmmgr-stubdom to talk directly to +the hardware TPM. Communication is facilitated by mapping +hardware memory pages into vtpmmgr-stubdom. + +=item Hardware TPM + +The physical TPM that is soldered onto the motherboard. + +=back + +=head1 INSTALLATION + +=head2 Prerequisites: + +You must have an x86 machine with a TPM on the motherboard. The only extra +software requirement for compiling vTPM is cmake. You must use libxl to manage +domains with vTPMs; 'xm' is deprecated and does not support vTPMs. + +=head2 Compiling the Xen tree: + +Compile and install the Xen tree as usual; be sure that the vTPM domains are +enabled when you run configure. + +=head2 Compiling the LINUX dom0 kernel: + +Because the TPM manager uses direct access to the physical TPM, it may interfere +with access to the TPM by dom0. The simplest solution for this is to prevent +dom0 from accessing the physical TPM by compiling the kernel without a driver or +blacklisting the module. If dom0 needs a TPM but does not need to use it during +the boot process (i.e. it is not using IMA), a virtual TPM can be attached to +dom0 after the system is booted. + +Access to the physical TPM may be required in order to manage the NVRAM or to +perform other advanced operations where the vTPM is insufficient. In order to +prevent interference, the TPM Manager and dom0 should use different values for +the TPM's locality; since Linux always uses locality 0, using locality 2 for the +TPM Manager is recommended. If both Linux and the TPM Manager attempt to access +the TPM at the same time, the TPM device will return a busy status; some +applications will consider this a fatal error instead of retrying the command at +a later time. If a vTPM gets an error when loading its key, it will currently +generate a fresh vTPM image (with a new EK, SRK, and blank NVRAM). + + +=head2 Compiling the LINUX domU kernel: + +The domU kernel used by domains with vtpms must include the xen-tpmfront.ko +driver. It can be built directly into the kernel or as a module; however, some +features such as IMA require the TPM to be built in to the kernel. + + CONFIG_TCG_TPM=y + CONFIG_TCG_XEN=y + +=head1 VTPM MANAGER SETUP + +=head2 Manager disk image setup: + +The vTPM Manager requires a disk image to store its encrypted data. The image +does not require a filesystem and can live anywhere on the host disk. The image +is not large; the Xen 4.5 vtpmmgr is limited to using the first 2MB of the image +but can support more than 20,000 vTPMs. + +=head2 Manager config file: + +The vTPM Manager domain (vtpmmgr-stubdom) must be started like any other Xen +virtual machine and requires a config file. The manager requires a disk image +for storage and permission to access the hardware memory pages for the TPM. The +disk must be presented as "hda", and the TPM memory pages are passed using the +iomem configuration parameter. The TPM TIS uses 5 pages of IO memory (one per +locality) that start at physical address 0xfed40000. By default, the TPM manager +uses locality 0 (so only the page at 0xfed40 is needed); this can be changed on +the domain's command line. For full functionality in deep quotes, using +locality 2 is required to manipulate PCR 20-22. + +=head2 Starting and stopping the manager: + +The vTPM manager should be started at boot; you may wish to create an init +script to do this. If a domain builder is used, the TPM Manager should be +started by the domain builder to minimize the trusted computing base for the +vTPM manager's secrets. + +Once initialization is complete you should see the following: + + INFO[VTPM]: Waiting for commands from vTPM's: + +The TPM Manager does not respond to shutdown requests; use the destroy command +to shut it down. + +=head1 VTPM AND LINUX PVM SETUP + +=head2 vTPM disk image setup: + +The vTPM requires a disk image to store its persistent data (RSA keys, NVRAM, +etc). The image does not require a filesystem. The image does not need to be +large; 2 Mb should be sufficient. + +=head2 vTPM config file: + +The vTPM domain requires a configuration file like any other domain. The vTPM +requires a disk image for storage and a TPM frontend driver to communicate with +the manager. You are required to generate a uuid for this vtpm, which is +specified on the C<vtpm=> line that describes its connection to the vTPM Manager. +The uuidgen application may be used to generate a uuid, or one from the output +of the C<manage-vtpmmgr.pl vtpm-add> command may be used to create a vTPM +belonging to a specific group. + +If you wish to clear the vTPM data you can either recreate the disk image or +change the uuid. + +=head2 Linux Guest config file: + +The Linux guest config file needs to be modified to include the Linux tpmfront +driver. Add the following line: + + vtpm=["backend=domu-vtpm"] + +Currently only Linux guests are supported (PV or HVM with PV drivers). + +While attaching a vTPM after a guest is booted (using xl vtpm-attach) is +supported, the attached vTPM will not have a record of the boot of the attached +guest. Furthermore, if the vTPM has been freshly created, a malicious guest +could then extend any values into PCRs, potentially forging its boot +configuration. Attaching a vTPM to a running domain should only be used for +trusted domains or when measurements have already been sent to the vTPM from +another source. + +=head2 Using the vTPM in the guest: + +If xen-tpmfront was compiled as a module, it must be loaded it in the guest. + + # modprobe xen-tpmfront + +After the Linux domain boots and the xen-tpmfront driver is loaded, you should +see the following on the vtpm console: + + Info: VTPM attached to Frontend X/Y + +You can quickly test the vTPM by using the sysfs interface: + + # cat /sys/devices/vtpm-0/pubek + # cat /sys/devices/vtpm-0/pcrs + +If you have trousers and tpm_tools installed on the guest, the tpm_version +command should return the following: + +The version command should return the following: + + TPM 1.2 Version Info: + Chip Version: 1.2.0.7 + Spec Level: 2 + Errata Revision: 1 + TPM Vendor ID: ETHZ + TPM Version: 01010000 + Manufacturer Info: 4554485a + +You should also see the command being sent to the vtpm console as well as the +vtpm saving its state. You should see the vtpm key being encrypted and stored on +the vtpmmgr console. + +You may wish to write a script to start your vtpm and guest together and to +destroy the vtpm when the guest shuts down. + +=head1 INTEGRATION WITH PV-GRUB + +The vTPM currently starts up with all PCRs set to their default values (all +zeros for the lower 16). This means that any decisions about the +trustworthiness of the created domain must be made based on the environment that +created the vTPM and the domU; for example, a system that only constructs images +using a trusted configuration and guest kernel be able to provide guarantees +about the guests and any measurements done that kernel (such as the IMA TCB +log). Guests wishing to use a custom kernel in such a secure environment are +often started using the pv-grub bootloader as the kernel, which then can load +the untrusted kernel without needing to parse an untrusted filesystem and kernel +in dom0. If the pv-grub stub domain succeeds in connecting to a vTPM, it will +extend the hash of the kernel that it boots into PCR #4, and will extend the +command line and initrd into PCR #5 before booting so that a domU booted in this +way can attest to its early boot state. + +=head1 MORE INFORMATION + +See <xen-vtpmmgr(7)> for more details about how the manager domain works, how to use +it, and its command line parameters. + +=head1 VTPM DOMAIN OPERATION + +The vtpm-stubdom is a mini-OS domain that emulates a TPM for the guest OS to +use. It is a small wrapper around the Berlios TPM emulator version 0.7.4. +Commands are passed from the linux guest via the mini-os TPM backend driver. +vTPM data is encrypted and stored via a disk image provided to the virtual +machine. The key used to encrypt the data along with a hash of the vTPM's data +is sent to the vTPM manager for secure storage and later retrieval. The vTPM +domain communicates with the manager using a mini-os tpm front/back device pair. + +=head1 VTPM DOMAIN COMMAND LINE ARGUMENTS + +Command line arguments are passed to the domain via the 'extra' parameter in the +VM config file. Each parameter is separated by white space. For example: + + extra="foo=bar baz" + +=head2 List of Arguments: + +=over 4 + +=item B<loglevel>=<LOG> + +Controls the amount of logging printed to the console. +The possible values for <LOG> are: + +=over 4 + +=item * error + +=item * info (default) + +=item * debug + +=back + +=item B<clear> + +Start the Berlios emulator in "clear" mode. (default) + +=item B<save> + +Start the Berlios emulator in "save" mode. + +=item B<deactivated> + +Start the Berlios emulator in "deactivated" mode. +See the Berlios TPM emulator documentation for details +about the startup mode. For all normal use, always use clear +which is the default. You should not need to specify any of these. + +=item B<maintcmds>=<1|0> + +Enable to disable the TPM maintenance commands. +These commands are used by tpm manufacturers and thus +open a security hole. They are disabled by default. + +=item B<hwinitpcr>=<PCRSPEC> + +Initialize the virtual Platform Configuration Registers +(PCRs) with PCR values from the hardware TPM. Each pcr specified by +<PCRSPEC> will be initialized with the value of that same PCR in TPM +once at startup. By default all PCRs are zero initialized. +Possible values of <PCRSPEC> are: + +=over + +=item * all: copy all pcrs + +=item * none: copy no pcrs (default) + +=item * <N>: copy pcr n + +=item * <X-Y>: copy pcrs x to y (inclusive) + +=back + +These can also be combined by comma separation, for example: +C<hwinitpcrs=5,12-16> will copy pcrs 5, 12, 13, 14, 15, and 16. + +=back + +=head1 REFERENCES + +Berlios TPM Emulator: L<http://tpm-emulator.berlios.de/> diff --git a/docs/man/xen-vtpm.pod.7 b/docs/man/xen-vtpm.pod.7 deleted file mode 100644 index 1d8185616a..0000000000 --- a/docs/man/xen-vtpm.pod.7 +++ /dev/null @@ -1,383 +0,0 @@ -=head1 NAME - -xen-vtpm - Xen virtual Trusted Platform Module (vTPM) subsystem - -=head1 RUBRIC - -Copyright (c) 2010-2012 United States Government, as represented by -the Secretary of Defense. All rights reserved. -November 12 2012 -Authors: Matthew Fioravante (JHUAPL), Daniel De Graaf (NSA) - -This document describes the virtual Trusted Platform Module (vTPM) subsystem -for Xen. The reader is assumed to have familiarity with building and installing -Xen, Linux, and a basic understanding of the TPM and vTPM concepts. - -=head1 INTRODUCTION - -The goal of this work is to provide a TPM functionality to a virtual guest -operating system (a DomU). This allows programs to interact with a TPM in a -virtual system the same way they interact with a TPM on the physical system. -Each guest gets its own unique, emulated, software TPM. However, each of the -vTPM's secrets (Keys, NVRAM, etc) are managed by a vTPM Manager domain, which -seals the secrets to the Physical TPM. If the process of creating each of these -domains (manager, vTPM, and guest) is trusted, the vTPM subsystem extends the -chain of trust rooted in the hardware TPM to virtual machines in Xen. Each -major component of vTPM is implemented as a separate domain, providing secure -separation guaranteed by the hypervisor. The vTPM domains are implemented in -mini-os to reduce memory and processor overhead. - -This mini-os vTPM subsystem was built on top of the previous vTPM work done by -IBM and Intel corporation. - -=head1 DESIGN OVERVIEW - -The architecture of vTPM is described below: - - +------------------+ - | Linux DomU | ... - | | ^ | - | v | | - | xen-tpmfront | - +------------------+ - | ^ - v | - +------------------+ - | mini-os/tpmback | - | | ^ | - | v | | - | vtpm-stubdom | ... - | | ^ | - | v | | - | mini-os/tpmfront | - +------------------+ - | ^ - v | - +------------------+ - | mini-os/tpmback | - | | ^ | - | v | | - | vtpmmgr-stubdom | - | | ^ | - | v | | - | mini-os/tpm_tis | - +------------------+ - | ^ - v | - +------------------+ - | Hardware TPM | - +------------------+ - -=over 4 - -=item Linux DomU - -The Linux based guest that wants to use a vTPM. There many be -more than one of these. - -=item xen-tpmfront.ko - -Linux kernel virtual TPM frontend driver. This driver -provides vTPM access to a para-virtualized Linux based DomU. - -=item mini-os/tpmback - -Mini-os TPM backend driver. The Linux frontend driver -connects to this backend driver to facilitate -communications between the Linux DomU and its vTPM. This -driver is also used by vtpmmgr-stubdom to communicate with -vtpm-stubdom. - -=item vtpm-stubdom - -A mini-os stub domain that implements a vTPM. There is a -one to one mapping between running vtpm-stubdom instances and -logical vtpms on the system. The vTPM Platform Configuration -Registers (PCRs) are all initialized to zero. - -=item mini-os/tpmfront - -Mini-os TPM frontend driver. The vTPM mini-os domain -vtpm-stubdom uses this driver to communicate with -vtpmmgr-stubdom. This driver could also be used separately to -implement a mini-os domain that wishes to use a vTPM of -its own. - -=item vtpmmgr-stubdom - -A mini-os domain that implements the vTPM manager. -There is only one vTPM manager and it should be running during -the entire lifetime of the machine. This domain regulates -access to the physical TPM on the system and secures the -persistent state of each vTPM. - -=item mini-os/tpm_tis - -Mini-os TPM version 1.2 TPM Interface Specification (TIS) -driver. This driver used by vtpmmgr-stubdom to talk directly to -the hardware TPM. Communication is facilitated by mapping -hardware memory pages into vtpmmgr-stubdom. - -=item Hardware TPM - -The physical TPM that is soldered onto the motherboard. - -=back - -=head1 INSTALLATION - -=head2 Prerequisites: - -You must have an x86 machine with a TPM on the motherboard. The only extra -software requirement for compiling vTPM is cmake. You must use libxl to manage -domains with vTPMs; 'xm' is deprecated and does not support vTPMs. - -=head2 Compiling the Xen tree: - -Compile and install the Xen tree as usual; be sure that the vTPM domains are -enabled when you run configure. - -=head2 Compiling the LINUX dom0 kernel: - -Because the TPM manager uses direct access to the physical TPM, it may interfere -with access to the TPM by dom0. The simplest solution for this is to prevent -dom0 from accessing the physical TPM by compiling the kernel without a driver or -blacklisting the module. If dom0 needs a TPM but does not need to use it during -the boot process (i.e. it is not using IMA), a virtual TPM can be attached to -dom0 after the system is booted. - -Access to the physical TPM may be required in order to manage the NVRAM or to -perform other advanced operations where the vTPM is insufficient. In order to -prevent interference, the TPM Manager and dom0 should use different values for -the TPM's locality; since Linux always uses locality 0, using locality 2 for the -TPM Manager is recommended. If both Linux and the TPM Manager attempt to access -the TPM at the same time, the TPM device will return a busy status; some -applications will consider this a fatal error instead of retrying the command at -a later time. If a vTPM gets an error when loading its key, it will currently -generate a fresh vTPM image (with a new EK, SRK, and blank NVRAM). - - -=head2 Compiling the LINUX domU kernel: - -The domU kernel used by domains with vtpms must include the xen-tpmfront.ko -driver. It can be built directly into the kernel or as a module; however, some -features such as IMA require the TPM to be built in to the kernel. - - CONFIG_TCG_TPM=y - CONFIG_TCG_XEN=y - -=head1 VTPM MANAGER SETUP - -=head2 Manager disk image setup: - -The vTPM Manager requires a disk image to store its encrypted data. The image -does not require a filesystem and can live anywhere on the host disk. The image -is not large; the Xen 4.5 vtpmmgr is limited to using the first 2MB of the image -but can support more than 20,000 vTPMs. - -=head2 Manager config file: - -The vTPM Manager domain (vtpmmgr-stubdom) must be started like any other Xen -virtual machine and requires a config file. The manager requires a disk image -for storage and permission to access the hardware memory pages for the TPM. The -disk must be presented as "hda", and the TPM memory pages are passed using the -iomem configuration parameter. The TPM TIS uses 5 pages of IO memory (one per -locality) that start at physical address 0xfed40000. By default, the TPM manager -uses locality 0 (so only the page at 0xfed40 is needed); this can be changed on -the domain's command line. For full functionality in deep quotes, using -locality 2 is required to manipulate PCR 20-22. - -=head2 Starting and stopping the manager: - -The vTPM manager should be started at boot; you may wish to create an init -script to do this. If a domain builder is used, the TPM Manager should be -started by the domain builder to minimize the trusted computing base for the -vTPM manager's secrets. - -Once initialization is complete you should see the following: - - INFO[VTPM]: Waiting for commands from vTPM's: - -The TPM Manager does not respond to shutdown requests; use the destroy command -to shut it down. - -=head1 VTPM AND LINUX PVM SETUP - -=head2 vTPM disk image setup: - -The vTPM requires a disk image to store its persistent data (RSA keys, NVRAM, -etc). The image does not require a filesystem. The image does not need to be -large; 2 Mb should be sufficient. - -=head2 vTPM config file: - -The vTPM domain requires a configuration file like any other domain. The vTPM -requires a disk image for storage and a TPM frontend driver to communicate with -the manager. You are required to generate a uuid for this vtpm, which is -specified on the C<vtpm=> line that describes its connection to the vTPM Manager. -The uuidgen application may be used to generate a uuid, or one from the output -of the C<manage-vtpmmgr.pl vtpm-add> command may be used to create a vTPM -belonging to a specific group. - -If you wish to clear the vTPM data you can either recreate the disk image or -change the uuid. - -=head2 Linux Guest config file: - -The Linux guest config file needs to be modified to include the Linux tpmfront -driver. Add the following line: - - vtpm=["backend=domu-vtpm"] - -Currently only Linux guests are supported (PV or HVM with PV drivers). - -While attaching a vTPM after a guest is booted (using xl vtpm-attach) is -supported, the attached vTPM will not have a record of the boot of the attached -guest. Furthermore, if the vTPM has been freshly created, a malicious guest -could then extend any values into PCRs, potentially forging its boot -configuration. Attaching a vTPM to a running domain should only be used for -trusted domains or when measurements have already been sent to the vTPM from -another source. - -=head2 Using the vTPM in the guest: - -If xen-tpmfront was compiled as a module, it must be loaded it in the guest. - - # modprobe xen-tpmfront - -After the Linux domain boots and the xen-tpmfront driver is loaded, you should -see the following on the vtpm console: - - Info: VTPM attached to Frontend X/Y - -You can quickly test the vTPM by using the sysfs interface: - - # cat /sys/devices/vtpm-0/pubek - # cat /sys/devices/vtpm-0/pcrs - -If you have trousers and tpm_tools installed on the guest, the tpm_version -command should return the following: - -The version command should return the following: - - TPM 1.2 Version Info: - Chip Version: 1.2.0.7 - Spec Level: 2 - Errata Revision: 1 - TPM Vendor ID: ETHZ - TPM Version: 01010000 - Manufacturer Info: 4554485a - -You should also see the command being sent to the vtpm console as well as the -vtpm saving its state. You should see the vtpm key being encrypted and stored on -the vtpmmgr console. - -You may wish to write a script to start your vtpm and guest together and to -destroy the vtpm when the guest shuts down. - -=head1 INTEGRATION WITH PV-GRUB - -The vTPM currently starts up with all PCRs set to their default values (all -zeros for the lower 16). This means that any decisions about the -trustworthiness of the created domain must be made based on the environment that -created the vTPM and the domU; for example, a system that only constructs images -using a trusted configuration and guest kernel be able to provide guarantees -about the guests and any measurements done that kernel (such as the IMA TCB -log). Guests wishing to use a custom kernel in such a secure environment are -often started using the pv-grub bootloader as the kernel, which then can load -the untrusted kernel without needing to parse an untrusted filesystem and kernel -in dom0. If the pv-grub stub domain succeeds in connecting to a vTPM, it will -extend the hash of the kernel that it boots into PCR #4, and will extend the -command line and initrd into PCR #5 before booting so that a domU booted in this -way can attest to its early boot state. - -=head1 MORE INFORMATION - -See <xen-vtpmmgr(7)> for more details about how the manager domain works, how to use -it, and its command line parameters. - -=head1 VTPM DOMAIN OPERATION - -The vtpm-stubdom is a mini-OS domain that emulates a TPM for the guest OS to -use. It is a small wrapper around the Berlios TPM emulator version 0.7.4. -Commands are passed from the linux guest via the mini-os TPM backend driver. -vTPM data is encrypted and stored via a disk image provided to the virtual -machine. The key used to encrypt the data along with a hash of the vTPM's data -is sent to the vTPM manager for secure storage and later retrieval. The vTPM -domain communicates with the manager using a mini-os tpm front/back device pair. - -=head1 VTPM DOMAIN COMMAND LINE ARGUMENTS - -Command line arguments are passed to the domain via the 'extra' parameter in the -VM config file. Each parameter is separated by white space. For example: - - extra="foo=bar baz" - -=head2 List of Arguments: - -=over 4 - -=item B<loglevel>=<LOG> - -Controls the amount of logging printed to the console. -The possible values for <LOG> are: - -=over 4 - -=item * error - -=item * info (default) - -=item * debug - -=back - -=item B<clear> - -Start the Berlios emulator in "clear" mode. (default) - -=item B<save> - -Start the Berlios emulator in "save" mode. - -=item B<deactivated> - -Start the Berlios emulator in "deactivated" mode. -See the Berlios TPM emulator documentation for details -about the startup mode. For all normal use, always use clear -which is the default. You should not need to specify any of these. - -=item B<maintcmds>=<1|0> - -Enable to disable the TPM maintenance commands. -These commands are used by tpm manufacturers and thus -open a security hole. They are disabled by default. - -=item B<hwinitpcr>=<PCRSPEC> - -Initialize the virtual Platform Configuration Registers -(PCRs) with PCR values from the hardware TPM. Each pcr specified by -<PCRSPEC> will be initialized with the value of that same PCR in TPM -once at startup. By default all PCRs are zero initialized. -Possible values of <PCRSPEC> are: - -=over - -=item * all: copy all pcrs - -=item * none: copy no pcrs (default) - -=item * <N>: copy pcr n - -=item * <X-Y>: copy pcrs x to y (inclusive) - -=back - -These can also be combined by comma separation, for example: -C<hwinitpcrs=5,12-16> will copy pcrs 5, 12, 13, 14, 15, and 16. - -=back - -=head1 REFERENCES - -Berlios TPM Emulator: L<http://tpm-emulator.berlios.de/> diff --git a/docs/man/xen-vtpmmgr.7.pod b/docs/man/xen-vtpmmgr.7.pod new file mode 100644 index 0000000000..af825a7ffe --- /dev/null +++ b/docs/man/xen-vtpmmgr.7.pod @@ -0,0 +1,383 @@ +=head1 NAME + +xen-vtpmgr - Xen virtual TPM stubdomain + +=head1 Authors + +=over 4 + +=item Daniel De Graaf <dgdegra@xxxxxxxxxxxxx> + +=item Quan Xu <quan.xu@xxxxxxxxx> + +=back + +This document describes the operation and command line interface of +vtpmmgr-stubdom. See L<xen-vtpm(7)> for details on the vTPM subsystem as a +whole. + +=head1 Overview + +The TPM Manager has three primary functions: + +=over 4 + +=item 1. Securely store the encryption keys for vTPMs + +=item 2. Provide a single controlled path of access to the physical TPM + +=item 3. Provide evidence (via TPM Quotes) of the current configuration + +=back + +When combined with a platform that provides a trusted method for creating +domains, the TPM Manager provides assurance that the private keys in a vTPM are +only available in specific trusted configurations. + +The manager accepts commands from the vtpm-stubdom domains via the mini-os TPM +backend driver. The vTPM manager communicates directly with hardware TPM using +the mini-os tpm_tis driver. + +=head1 Boot Configurations and TPM Groups + +The TPM Manager's data is secured by using the physical TPM's seal operation, +which allows data to be bound to specific PCRs. These PCRs are populated in the +physical TPM during the boot process, either by the firmware/BIOS or by a +dynamic launch environment such as TBOOT. In order to provide assurance of the +system's security, the PCRs used to seal the TPM manager's data must contain +measurements for domains used to bootstrap the TPM Manager and vTPMs. + +Because these measurements are based on hashes, they will change any time that +any component of the system is upgraded. Since it is not possible to construct a +list of all possible future good measurements, the job of approving +configurations is delegated to a third party, referred to here as the system +approval agent (SAA). The SAA is identified by its public (RSA) signature key, +which is used to sign lists of valid configurations. A single TPM manager can +support multiple SAAs via the use of vTPM groups. Each group is associated with +a single SAA; this allows the creation of a multi-tenant environment where +tenants may not all choose to trust the same SAA. + +Each vTPM is bound to a vTPM group at the time of its creation. Each vTPM group +has its own AIK in the physical TPM for quotes of the hardware TPM state; when +used with a conforming Privacy CA, this allows each group on the system to form +the basis of a distinct identity. + +=head1 Initial Provisioning + +When the TPM Manager first boots up, it will create a stub vTPM group along with +entries for any vTPMs that communicate with it. This stub group must be +provisioned with an SAA and a boot configuration in order to survive a reboot. + +When a vTPM is connected to the TPM Manager using a UUID that is not recognized, +a slot will be created in group 0 for it. In the future, this auto-creation may +be restricted to specific UUIDs (such as the all-zero UUID) to enforce the use +of the TPM manager as the generator of the UUID. The first vTPM to be connected +is given administrative privileges for the TPM Manager, and should be attached +to dom0 or a control domain in order to send provisioning commands. + +Provisioning a vTPM group for the system requires the public key of the SAA and +privacy CA data used to certify the AIK (see the TPM spec for details). Once the +group is created, a signed list of boot measurements can be installed. The +initial group controls the ability to boot the system as a whole, and cannot be +deleted once provisioned. + +=head1 Command Line Arguments + +Command line arguments are passed to the domain via the 'extra' parameter in the +VM config file. Each parameter is separated by white space. For example: + + extra="foo=bar baz" + +Valid arguments: + +=over 4 + +=item owner_auth=<AUTHSPEC> + +=item srk_auth=<AUTHSPEC> + +Set the owner and SRK authdata for the TPM. If not specified, the +default is 160 zero bits (the well-known auth value). Valid values of +<AUTHSPEC> are: + +=over 4 + +=item well-known + +Use the well known auth (default) + +=item hash:<HASH> + +Use the given 40-character ASCII hex string + +=item text:<STR> + +Use sha1 hash of <STR>. + +=back + +=item tpmdriver=<DRIVER> + +Choose the driver used for communication with the hardware TPM. Values +other than tpm_tis should only be used for testing. + +The possible values of <DRIVER> are: + +=over 4 + +=item tpm_tis + +Direct communication with a hardware TPM 1.2. The +domain must have access to TPM IO memory. (default) + +=item tpmfront + +Use the Xen tpmfront interface to talk to another +domain which provides access to the TPM. + +=back + +=back + +The following options only apply to the tpm_tis driver: + +=over 4 + +=item tpmiomem=<ADDR> + +The base address of the hardware memory pages of the TPM. +The default is 0xfed40000, as defined by the TCG's PC Client spec. + +=item tpmirq=<IRQ> + +The irq of the hardware TPM if using interrupts. A value of +"probe" can be set to probe for the irq. A value of 0 disables +interrupts and uses polling (default 0). + +=item tpmlocality=<LOC> + +Attempt to use locality <LOC> of the hardware TPM. +For full functionality of the TPM Manager, this should be set to "2". + +=back + +=head1 Platform Security Assumptions + +While the TPM Manager has the ability to check the hash of the vTPM requesting a +key, there is currently no trusted method to inform the TPM Manager of the hash +of each new domain. Because of this, the TPM Manager trusts the UUID key in +Xenstore to identify a vTPM in a trusted manner. The XSM policy may be used to +strengthen this assumption if the creation of vTPM-labeled domains is more +constrained (for example, only permitted to a domain builder service): the only +grants mapped by the TPM Manager should belong to vTPM domains, so restricting +the ability to map other domain's granted pages will prevent other domains from +directly requesting keys from the TPM Manager. The TPM Manager uses the hash of +the XSM label of the attached vTPM as the kernel hash, so vTPMs with distinct +labels may be further partitioned using vTPM groups. + +A domain with direct access to the hardware TPM will be able to decrypt the TPM +Manager's disk image if the haredware TPM's PCR values are in a permitted +configuration. To protect the TPM Manager's data, the list of permitted +configurations should be chosen to include PCRs that measure the hypervisor, +domain 0, the TPM Manager, and other critical configuration such as the XSM +policy. If the TPM Manager is configured to use locality 2 as recommended, it +is safe to permit the hardware domain to access locality 0 (the default in +Linux), although concurrent use of the TPM should be avoided as it can result in +unexpected busy errors from the TPM driver. The ability to access locality 2 of +the TPM should be enforced using IO memory labeling in the XSM policy; the +physical address 0xFED42xxx is always locality 2 for TPMs using the TIS driver. + +=head1 Appendix: unsecured migration process for vtpmmgr domain upgrade + +There is no direct upgrade supported from previous versions of the vtpmmgr +domain due to changes in the on-disk format and the method used to seal data. +If a vTPM domain supports migration, this feature should be used to migrate the +vTPM's data; however, the vTPM packaged with Xen does not yet support migration. + +If adding migration support to the vTPM is not desired, a simpler migration +domain usable only for local migration can be constructed. The migration process +would look like the following: + +=over 4 + +=item 1. Start the old vtpmmgr + +=item 2. Start the vTPM migration domain + +=item 3. Attach the vTPM migration domain's vtpm/0 device to the old vtpmmgr + +=item 4. Migration domain executes vtpmmgr_LoadHashKey on vtpm/0 + +=item 5. Start the new vtpmmgr, possibly shutting down the old one first + +=item 6. Attach the vTPM migration domain's vtpm/1 device to the new vtpmmgr + +=item 7. Migration domain executes vtpmmgr_SaveHashKey on vtpm/1 + +=back + +This requires the migration domain to be added to the list of valid vTPM kernel +hashes. In the current version of the vtpmmgr domain, this is the hash of the +XSM label, not the kernel. + +=head1 Appendix B: vtpmmgr on TPM 2.0 + +=head2 Manager disk image setup: + +The vTPM Manager requires a disk image to store its encrypted data. The image +does not require a filesystem and can live anywhere on the host disk. The image +is not large; the Xen 4.5 vtpmmgr is limited to using the first 2MB of the image +but can support more than 20,000 vTPMs. + + dd if=/dev/zero of=/home/vtpm2/vmgr bs=16M count=1 + +=head2 Manager config file: + +The vTPM Manager domain (vtpmmgr-stubdom) must be started like any other Xen +virtual machine and requires a config file. The manager requires a disk image +for storage and permission to access the hardware memory pages for the TPM. The +disk must be presented as "hda", and the TPM memory pages are passed using the +iomem configuration parameter. The TPM TIS uses 5 pages of IO memory (one per +locality) that start at physical address 0xfed40000. By default, the TPM manager +uses locality 0 (so only the page at 0xfed40 is needed). + +Add: + + extra="tpm2=1" + +extra option to launch vtpmmgr-stubdom domain on TPM 2.0, and ignore it on TPM +1.x. for example: + + kernel="/usr/lib/xen/boot/vtpmmgr-stubdom.gz" + memory=128 + disk=["file:/home/vtpm2/vmgr,hda,w"] + name="vtpmmgr" + iomem=["fed40,5"] + extra="tpm2=1" + + +=head2 Key Hierarchy + + +------------------+ + | vTPM's secrets | ... + +------------------+ + | ^ + | |(Bind / Unbind) +- - - - - -v |- - - - - - - - TPM 2.0 + +------------------+ + | SK + + +------------------+ + | ^ + v | + +------------------+ + | SRK | + +------------------+ + | ^ + v | + +------------------+ + | TPM 2.0 Storage | + | Primary Seed | + +------------------+ + +Now the secrets for the vTPMs are only being bound to the presence of thephysical +TPM 2.0. Since using PCRs to seal the data can be an important security feature +that users of the vtpmmgr rely on. I will replace TPM2_Bind/TPM2_Unbind with +TPM2_Seal/TPM2_Unseal to provide as much security as it did for TPM 1.2 in later +series of patch. + +=head2 Design Overview + +The architecture of vTPM subsystem on TPM 2.0 is described below: + + +------------------+ + | Linux DomU | ... + | | ^ | + | v | | + | xen-tpmfront | + +------------------+ + | ^ + v | + +------------------+ + | mini-os/tpmback | + | | ^ | + | v | | + | vtpm-stubdom | ... + | | ^ | + | v | | + | mini-os/tpmfront | + +------------------+ + | ^ + v | + +------------------+ + | mini-os/tpmback | + | | ^ | + | v | | + | vtpmmgr-stubdom | + | | ^ | + | v | | + | mini-os/tpm2_tis | + +------------------+ + | ^ + v | + +------------------+ + | Hardware TPM 2.0 | + +------------------+ + +=over 4 + +=item Linux DomU + +The Linux based guest that wants to use a vTPM. There many be +more than one of these. + +=item xen-tpmfront.ko + +Linux kernel virtual TPM frontend driver. This driver +provides vTPM access to a para-virtualized Linux based DomU. + +=item mini-os/tpmback + +Mini-os TPM backend driver. The Linux frontend driver +connects to this backend driver to facilitate +communications between the Linux DomU and its vTPM. This +driver is also used by vtpmmgr-stubdom to communicate with +vtpm-stubdom. + +=item vtpm-stubdom + +A mini-os stub domain that implements a vTPM. There is a +one to one mapping between running vtpm-stubdom instances and +logical vtpms on the system. The vTPM Platform Configuration +Registers (PCRs) are all initialized to zero. + +=item mini-os/tpmfront + +Mini-os TPM frontend driver. The vTPM mini-os domain +vtpm-stubdom uses this driver to communicate with +vtpmmgr-stubdom. This driver could also be used separately to +implement a mini-os domain that wishes to use a vTPM of +its own. + +=item vtpmmgr-stubdom + +A mini-os domain that implements the vTPM manager. +There is only one vTPM manager and it should be running during +the entire lifetime of the machine. This domain regulates +access to the physical TPM on the system and secures the +persistent state of each vTPM. + +=item mini-os/tpm2_tis + +Mini-os TPM version 2.0 TPM Interface Specification (TIS) +driver. This driver used by vtpmmgr-stubdom to talk directly +to the hardware TPM 2.0. Communication is facilitated by mapping +hardware memory pages into vtpmmgr-stubdom. + +=item Hardware TPM 2.0 + +The physical TPM 2.0 that is soldered onto the motherboard. + +=back + +Noted: + functionality for a virtual guest operating system (a DomU) is still TPM 1.2. diff --git a/docs/man/xen-vtpmmgr.pod.7 b/docs/man/xen-vtpmmgr.pod.7 deleted file mode 100644 index af825a7ffe..0000000000 --- a/docs/man/xen-vtpmmgr.pod.7 +++ /dev/null @@ -1,383 +0,0 @@ -=head1 NAME - -xen-vtpmgr - Xen virtual TPM stubdomain - -=head1 Authors - -=over 4 - -=item Daniel De Graaf <dgdegra@xxxxxxxxxxxxx> - -=item Quan Xu <quan.xu@xxxxxxxxx> - -=back - -This document describes the operation and command line interface of -vtpmmgr-stubdom. See L<xen-vtpm(7)> for details on the vTPM subsystem as a -whole. - -=head1 Overview - -The TPM Manager has three primary functions: - -=over 4 - -=item 1. Securely store the encryption keys for vTPMs - -=item 2. Provide a single controlled path of access to the physical TPM - -=item 3. Provide evidence (via TPM Quotes) of the current configuration - -=back - -When combined with a platform that provides a trusted method for creating -domains, the TPM Manager provides assurance that the private keys in a vTPM are -only available in specific trusted configurations. - -The manager accepts commands from the vtpm-stubdom domains via the mini-os TPM -backend driver. The vTPM manager communicates directly with hardware TPM using -the mini-os tpm_tis driver. - -=head1 Boot Configurations and TPM Groups - -The TPM Manager's data is secured by using the physical TPM's seal operation, -which allows data to be bound to specific PCRs. These PCRs are populated in the -physical TPM during the boot process, either by the firmware/BIOS or by a -dynamic launch environment such as TBOOT. In order to provide assurance of the -system's security, the PCRs used to seal the TPM manager's data must contain -measurements for domains used to bootstrap the TPM Manager and vTPMs. - -Because these measurements are based on hashes, they will change any time that -any component of the system is upgraded. Since it is not possible to construct a -list of all possible future good measurements, the job of approving -configurations is delegated to a third party, referred to here as the system -approval agent (SAA). The SAA is identified by its public (RSA) signature key, -which is used to sign lists of valid configurations. A single TPM manager can -support multiple SAAs via the use of vTPM groups. Each group is associated with -a single SAA; this allows the creation of a multi-tenant environment where -tenants may not all choose to trust the same SAA. - -Each vTPM is bound to a vTPM group at the time of its creation. Each vTPM group -has its own AIK in the physical TPM for quotes of the hardware TPM state; when -used with a conforming Privacy CA, this allows each group on the system to form -the basis of a distinct identity. - -=head1 Initial Provisioning - -When the TPM Manager first boots up, it will create a stub vTPM group along with -entries for any vTPMs that communicate with it. This stub group must be -provisioned with an SAA and a boot configuration in order to survive a reboot. - -When a vTPM is connected to the TPM Manager using a UUID that is not recognized, -a slot will be created in group 0 for it. In the future, this auto-creation may -be restricted to specific UUIDs (such as the all-zero UUID) to enforce the use -of the TPM manager as the generator of the UUID. The first vTPM to be connected -is given administrative privileges for the TPM Manager, and should be attached -to dom0 or a control domain in order to send provisioning commands. - -Provisioning a vTPM group for the system requires the public key of the SAA and -privacy CA data used to certify the AIK (see the TPM spec for details). Once the -group is created, a signed list of boot measurements can be installed. The -initial group controls the ability to boot the system as a whole, and cannot be -deleted once provisioned. - -=head1 Command Line Arguments - -Command line arguments are passed to the domain via the 'extra' parameter in the -VM config file. Each parameter is separated by white space. For example: - - extra="foo=bar baz" - -Valid arguments: - -=over 4 - _______________________________________________ Xen-changelog mailing list Xen-changelog@xxxxxxxxxxxxxxxxxxxx https://lists.xenproject.org/xen-changelog

©2013 Xen Project, A Linux Foundation Collaborative Project. All Rights Reserved.
Linux Foundation is a registered trademark of The Linux Foundation.
Xen Project is a trademark of The Linux Foundation.